Live Audio Integration Guide

1. Two transports

Audio delivery is a per-match choice. You declare it when you create the match; one deployment serves both, and two matches running against the same service can use different ones.

2. Credentials

You will be given two tokens over a private channel. They are not interchangeable, and neither of them is the operations token.

Both go in Authorization: Bearer <token>. If you are ever handed a token that also opens /v1/status or /v1/scout, that is an operations credential and it was sent to you by mistake — tell us.

3. Create the match, and declare the transport

POST/v1/matches

{
  "match_id": "your-match-001",
  "match_package": { "competition": "…", "teams": { … } },
  "output": {
    "mode": "audio",
    "languages": ["zh-CN"],
    "commentary_profile": "betting",
    "audio_transport": "websocket"
  }
}

Creation returns the stored request settings. A later GET /v1/matches/{match_id} also returns the effective settings. For example, on a service configured to use v1 audio:

"output": {
  "mode": "audio", "languages": ["zh-CN"],
  "audio_transport": "websocket", "commentary_profile": "betting",
  "effective_mode": "v1", "effective_transport": "websocket",
  "effective_commentary_profile": "betting"
}

4. Arm the match and publish

POST /v1/matches/{match_id}/arm returns your SRT ingest URL and the stream epoch for this attempt. Publish your MPEG-TS feed to it; commentary starts once we see frames.

5. WebSocket transport

wss://<host>/v1/matches/{match_id}/audio/stream?after_sequence=0
Authorization: Bearer <audio receipt token>

Each delivery is one self-contained JSON message. There is no metadata/bytes frame pairing to reassemble.

{
  "type": "delivery",
  "action": "upsert",
  "delivery_sequence": 41,
  "idempotency_key": "your-match-001:epoch-…:speech-acde1234:r1",
  "target_start_pts_ms": 51600,
  "expires_pts_ms": 61600,
  "duration_ms": 4500,
  "codec": "wav", "sample_rate": 24000, "channels": 1,
  "payload_bytes": 216044,
  "content_sha256": "<64 lowercase hex>",
  "audio_base64": "<the WAV bytes>",
  "commentary_text": "…",
  "emotion": "Tension"
}

Cancellations

"action": "cancel" withdraws a segment revision that has not been played yet. It carries no audio_base64. Drop the matching idempotency_key from your playout queue.

Reconnecting

Reconnect with after_sequence set to the highest delivery_sequence you have processed. Anything enqueued while you were away is replayed in order. Connecting with after_sequence=0 after the match was re-armed gives you the current epoch only — a previous attempt’s audio is never replayed into a new one.

6. Callback transport

We POST to the audio_callback_url you gave at match creation. Each request carries:

The body is identical to the WebSocket message except that audio_base64 is replaced by audio_url — a signed link, valid five minutes.

7. Receipts — the part integrations skip, and regret

A receipt tells us what actually happened to a segment. Send exactly one per delivery.

→ {"type":"receipt","idempotency_key":"…:r1","status":"played"}
← {"type":"receipt_ack","idempotency_key":"…:r1","accepted":true,"duplicate":false,"status":"played"}

On the callback transport, send the same thing as POST /v1/audio/receipts with the Audio Receipt token.

Re-sending the same key with the same status is safe and answers duplicate: true. Sending the same key with a different status is refused — the first receipt is the one that counts. On the WebSocket transport that refusal closes the connection with 1008 and the reason timed audio already has a different receipt; on the callback transport it is a 400. So do not, for example, report failed at expiry and then played when a late buffer finally drains: pick one, and it is the first one that sticks. receipt_ack is what lets you tell “it landed” from “the socket died on the way” — do not treat a successful send() as confirmation; keep it queued until the ack arrives, and re-send unacked receipts after a reconnect.

8. Subtitles come with the audio

An audio match also produces subtitles, derived from the same admitted segment — same text, same timing, one duration model. You do not ask for them separately and they cannot disagree with what was spoken.

Read them the same way a subtitle-only integration does: GET /v1/matches/{match_id}/subtitles, or the subtitle WebSocket. See the subtitle guide for that surface.

9. Playing the audio

emotion

emotion is the delivery mood of the segment — exactly one of five fixed values, present on every line, never empty. The voice in the WAV already follows it; it is set from the confirmed match situation the segment reports, not from its wording. A replay is always Calm: it is never voiced as if it were happening again.

The same value appears on the matching subtitle line. Use it for on-screen treatment or mixing if you wish; you do not need it to play the audio. Treat any value you do not recognise as Calm.

10. Latency — read this before you integrate

Commentary is produced behind live edge by a fixed broadcast buffer. That buffer is the delay your viewers experience, and it is a deployment setting, not something a match can shorten below the pipeline’s worst case.

Practically: your player is expected to be running that far behind the source feed already. If you play our audio against a feed that is not delayed, every segment will arrive after the moment it describes and you will fail all of them at expires_pts_ms.

11. Errors

12. Integration checklist

13. Changelog