Legs

Add an audio stream to a live call

Changed on

Negotiates an additional m=audio section with a re-INVITE (RFC 3264 §8.1). The new section is appended below the existing ones and binds its own RTP port. Use it to carry a second independent audio stream — a translated feed, for example — alongside the original. Set content to "alt" and lang to the feed's language so the peer can tell them apart. A peer that answers the new section with port 0 leaves the call untouched and this returns 409.

post/legs/{id}/streams

Request

  • Base URL
    http://localhost:8080/v1
  • URL
    http://localhost:8080/v1/legs/{id}/streams
  • Auth
    none declared

Request body

direction'sendrecv' | 'sendonly' | 'recvonly' | 'inactive'

Media direction for the new stream, from this server's point of view. Defaults to sendrecv.

langstring

BCP 47 language tag advertised as a=lang (RFC 8866), e.g. "es-ES" for a Spanish translation feed.

content'main' | 'alt' | 'speaker' | 'slides' | 'sl'

Value advertised as a=content (RFC 4796). Use "main" for original audio and "alt" for an alternative feed such as a translation.

labelstring

Value advertised as a=label (RFC 4574), for correlating the stream with external metadata.

room_idstring

If set, attach the new stream to this room once it is negotiated.

rolestring

Routing role to apply when room_id is set.

Response

Stream negotiated

idstring required

Stream identifier, stable for the life of the dialog. The primary stream is always "0".

midstring

The stream's SDP a=mid token (RFC 5888), used to correlate it across offer/answer.

indexinteger required

Position of the stream's m= line in the SDP. Fixed for the life of the dialog (RFC 3264 §8).

primaryboolean required

True for the call's main bidirectional audio stream, which cannot be removed or attached to a room independently.

state'pending' | 'active' | 'removed' required

Negotiation state.

direction'sendrecv' | 'sendonly' | 'recvonly' | 'inactive' required

Negotiated media direction from this server's point of view.

desired_direction'sendrecv' | 'sendonly' | 'recvonly' | 'inactive'

Direction requested by the application. Survives hold/unhold, unlike the negotiated direction.

codecstring

Codec the stream's media pipeline is actually running, which after a mid-call re-INVITE is the renegotiated one. Streams on one leg may use different codecs.

sample_rateinteger

Native sample rate of the codec the stream is running, in Hz. It follows a mid-call codec renegotiation.

local_portinteger

Local RTP port. Each stream binds its own port; a shared transport is undefined without BUNDLE (RFC 9143).

remote_addrstring

Remote RTP address media is currently sent to.

labelstring

The stream's a=label value (RFC 4574), for correlating it with external metadata.

contentstring

The stream's a=content value (RFC 4796), e.g. "main" for original audio and "alt" for a translated feed.

langstring

The stream's a=lang value (RFC 8866): a BCP 47 language tag such as "en" or "es-ES".

room_idstring

Room this stream's audio is mixed into. A secondary stream may sit in a different room than its leg.

rolestring

Routing role of this stream within its room. Streams carry their own role, independent of their leg's.

Changes