Interface MediaStreamParser

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. 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<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' } 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 null | string

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

Optional formatClear

• formatClear(streamSid): null | string

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

  Parameters

  • streamSid: string

  Returns null | string

Optional formatMark

• formatMark(streamSid, name): null | string

• Encodes a named playback checkpoint, or null when unavailable.

  Parameters

  • streamSid: string
  • name: string

  Returns null | string

Optional Readonly protocol