Skip to main content

Interface: MediaStreamParser

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:67

Contract for parsing and formatting provider-specific WebSocket media stream messages.

The interface has three responsibilities:

  1. Inbound normalisation (parseIncoming) -- Convert the provider's proprietary wire format into MediaStreamIncoming events.
  2. Outbound formatting (formatOutgoing) -- Wrap mu-law audio bytes in whatever envelope the provider expects.
  3. Connection handshake (formatConnected) -- Optionally generate a first-message acknowledgment required by some providers (e.g., Twilio).

The built-in parsers take { protocol: 'carrier' } to select each carrier's documented PCMU 8 kHz media messages and playback controls; without it they keep the legacy profile summarised below.

See​

  • TwilioMediaStreamParser -- legacy: JSON envelope, base64 audio, connected ack.
  • TelnyxMediaStreamParser -- legacy: JSON inbound, raw binary outbound, no ack.
  • PlivoMediaStreamParser -- legacy: JSON envelope, playAudio outbound, no ack.

Properties​

protocol?​

readonly optional protocol: "legacy" | "carrier"

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:117

Explicit wire profile; omission denotes the released compatibility protocol.

Methods​

formatClear()?​

optional formatClear(streamSid): string | null

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:119

Encodes cancellation of queued carrier playback, or null when unavailable.

Parameters​

streamSid​

string

Returns​

string | null


formatConnected()?​

optional formatConnected(streamSid): string | null

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:114

Generate the initial connection acknowledgment message, if the provider requires one immediately after the WebSocket handshake.

  • Twilio: Returns { event: 'connected', protocol: 'Call', version: '1.0.0' } in the legacy profile and null in the carrier profile.
  • Telnyx: Returns null (no handshake needed).
  • Plivo: Not defined (no handshake needed).

Parameters​

streamSid​

string

The stream identifier established during the handshake.

Returns​

string | null

A JSON string to send as the first WS message, or null if the provider does not need an explicit acknowledgment.


formatMark()?​

optional formatMark(streamSid, name): string | null

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:121

Encodes a named playback checkpoint, or null when unavailable.

Parameters​

streamSid​

string

name​

string

Returns​

string | null


formatOutgoing()​

formatOutgoing(audio, streamSid): string | Buffer

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:99

Encode mu-law audio for transmission back to the telephony provider.

The returned type varies by provider. In the legacy profile:

  • Twilio: Returns a JSON string wrapping base64-encoded audio in a { event: 'media', streamSid, media: { payload } } envelope.
  • Telnyx: Returns the raw Buffer unchanged (binary WS frame).
  • Plivo: Returns a JSON string with a { event: 'playAudio', media: { payload } } envelope.

In the carrier profile every built-in parser returns a JSON string in its carrier's documented media message.

Parameters​

audio​

Buffer

Raw mu-law PCM bytes to send to the caller.

streamSid​

string

Provider stream identifier required by some formats.

Returns​

string | Buffer

A Buffer (for providers that accept raw binary) or a JSON string (for providers that wrap audio in an envelope).


parseIncoming()​

parseIncoming(data): MediaStreamIncoming | null

Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:80

Parse a raw WebSocket message received from the telephony provider.

Implementations must handle both Buffer (binary frames) and string (text frames) inputs, since different providers and WebSocket libraries deliver data in different forms.

Parameters​

data​

Raw message bytes or string as delivered by the WS frame.

string | Buffer

Returns​

MediaStreamIncoming | null

A normalised MediaStreamIncoming event, or null if the message should be silently ignored (e.g. unknown event type, outbound audio track, heartbeat frames, etc.).