sid, and that sid is the only thing you ever address — the phone leg, the
SIP leg, the browser softphone leg, and an attached AI agent are all facets of
it. Understand the four nouns on this page — call, track, stream, and
frame — and the rest of the voice API reads as vocabulary you already know.
One call, one sid
A call is a two-legged conversation (caller ↔ agent) that a SIP gateway runs as a back-to-back user agent (B2BUA). Whether you originate it, receive it inbound, or place it from a browser, the control plane hands you aCall keyed by one
sid. You never juggle separate handles for signalling, media, and the agent:
- Originate returns a
Callas soon as it isdialing. - Fetch, transfer, hang up all take the same
sid. - Attach an audio bridge or an AI agent by
sid— the engine wires the media end to end.
transfer() re-points the live audio at a new number or a different agent while
keeping the same sid, so a call’s identity survives an AI→human handoff or
a carrier re-route. See Call lifecycle
for the full state machine.
The two audio tracks
A call’s media is exactly two MoQT audio tracks under a per-call namespace:voice/<sid>/uplink without the
publisher knowing they exist.
Uplink and downlink are named from the caller’s point of view. When you
attach as the server, you subscribe uplink (hear the caller) and
publish downlink (talk to the caller). When you attach as the browser
caller, you do the mirror image — publish uplink (your mic) and
subscribe downlink (playback). Same two track names, opposite ends.
The capability tag: voice/<codec>
Each track carries a capability string of the form voice/<codec> — for
example voice/opus or voice/pcm16. The relay routes on that capability, not
on a hardcoded peer address, so you subscribe by intent: “give me this call’s
audio as Opus.” A capability is how an AI-agent attach, a recording sidecar, or
your own ASR tap all find a call’s audio without being wired to it in advance.
This is the voice-specific instance of the general rule that a track’s capability
is its routing key — the same mechanism "asr" and "tts" tracks use elsewhere.
Streams and frames
A track is a continuous stream of small binary frames. For voice, one frame is one encoded audio packet — a 20 ms Opus frame is the default unit — and the bridge writes each frame as a MoQT object with a microsecond timestamp:Codecs
The bridge transcodes between what the call leg negotiated with the carrier and what your code asked for — PSTN µ-law in, Opus to your code, and back — so you never run media tooling in your own process. Pick a codec per attach:| Codec | When to use it |
|---|---|
opus | Default. Best quality-per-bit; the native browser-softphone format. |
pcm16 | Raw 16-bit PCM — what many realtime AI models want on their input. |
g711_ulaw | PSTN-direct, no transcode. µ-law (North America / Japan). |
g711_alaw | PSTN-direct, no transcode. A-law (most of the rest of the world). |
sampleRate (default 48000), channels (default 1), and frameMs (default 20)
round out the audio shape. Voice is audio-only — there are no video codecs on
this path. See Codecs for the
transcode matrix and passthrough fast paths.
Where sessions fit
“Session” is the transport-level connection your SDK client holds — one authenticated QUIC link that can carry many calls’ tracks at once. You open a session once (the client auto-reconnects and re-attaches your tracks for you), and each call multiplexes itsuplink/downlink pair over it. A single auth token
authorizes the whole session, so attaching to another sid needs no new setup.
The browser softphone places audio on these same
voice/<sid> tracks — there
is no separate WebRTC transport and no SFU on that path. Only the browser’s Opus
encoder is borrowed (via encoded/insertable streams); the encoded frames ride
QUIC/MoQT like every other frame. See
Browser audio capture.Related
Calls API
Originate, fetch, transfer, and hang up — the control surface for a
sid.Realtime tracks
The MoQT publish/subscribe primitive the audio bridge is built on.
Codecs
Opus, PCM16, and G.711 — transcode matrix and passthrough paths.
Voice architecture
How signalling, media, transport, and the agent runtime fit together.