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:
- Inbound normalisation (parseIncoming) -- Convert the provider's proprietary wire format into MediaStreamIncoming events.
- Outbound formatting (formatOutgoing) -- Wrap mu-law audio bytes in whatever envelope the provider expects.
- 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,
connectedack. - TelnyxMediaStreamParser -- legacy: JSON inbound, raw binary outbound, no ack.
- PlivoMediaStreamParser -- legacy: JSON envelope,
playAudiooutbound, no ack.
Properties
protocol?
readonlyoptionalprotocol:"legacy"|"carrier"
Defined in: packages/agentos/src/io/channels/telephony/MediaStreamParser.ts:117
Explicit wire profile; omission denotes the released compatibility protocol.
Methods
formatClear()?
optionalformatClear(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()?
optionalformatConnected(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 andnullin 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()?
optionalformatMark(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
stringwrapping base64-encoded audio in a{ event: 'media', streamSid, media: { payload } }envelope. - Telnyx: Returns the raw
Bufferunchanged (binary WS frame). - Plivo: Returns a JSON
stringwith 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.).