Interface MediaStreamParser

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).

See

  • TwilioMediaStreamParser -- JSON envelope, base64 audio, connected ack.
  • TelnyxMediaStreamParser -- JSON inbound, raw binary outbound, no ack.
  • PlivoMediaStreamParser -- JSON envelope, playAudio outbound, no ack.
interface MediaStreamParser {
    parseIncoming(data): null | MediaStreamIncoming;
    formatOutgoing(audio, streamSid): string | Buffer<ArrayBufferLike>;
    formatConnected?(streamSid): null | string;
}

Implemented by

Methods

parseIncoming formatOutgoing formatConnected?

Methods

parseIncoming

  • parseIncoming(data): null | MediaStreamIncoming

  • 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: string | Buffer<ArrayBufferLike>

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

    Returns null | MediaStreamIncoming

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

formatOutgoing

  • formatOutgoing(audio, streamSid): string | Buffer<ArrayBufferLike>

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

    The returned type varies by provider:

    • 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.

    Parameters

    • audio: Buffer<ArrayBufferLike>

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

    • streamSid: string

      Provider stream identifier required by some formats.

    Returns string | Buffer<ArrayBufferLike>

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

Optional formatConnected

  • formatConnected(streamSid): null | string

  • 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' }.
    • Telnyx: Returns null (no handshake needed).
    • Plivo: Not defined (no handshake needed).

    Parameters

    • streamSid: string

      The stream identifier established during the handshake.

    Returns null | string

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

Settings

Member Visibility

Theme

On This Page

parseIncomingformatOutgoingformatConnected