Stream

Definition

A Stream can send and receive call audio in near real-time. The audio is sent as Web Socket Messages.

There are two types of streams:

• A unidirectional Stream forks the audio streams of a call to your application. In this case your application is not sending any audio into the call, but a unidirectional Stream carries call audio only in one direction: from the call via WebSockets to your web application. To start a unidirectional stream, use the Start verb. To stop a unidirectional stream, use the Stop verb.

  info

  A unidirectional Stream is a background activity, meaning FlexML continues executing subsequent instructions after starting the stream. When Stream is used as a top-level verb with suppressAnswer="true", the call can remain unanswered while media is being streamed.

  With unidirectional streams, you can get inbound, outbound or both as a single track.

• A bidirectional Stream allows your web application to receive audio from a call and send audio back to the call via WebSockets. To start a bidirectional stream, use the Connect verb. You can stop the bidirectional stream by either closing the WebSocket or ending the call.

  info

  A bidirectional Stream is a foreground activity, meaning FlexML does not continue executing subsequent instructions until the WebSocket is closed.

  With bidirectional streams, you will receive only the inbound track.

  The bidirectional stream blocks FlexML, so any FlexML verbs after the </Connect> will not execute until the stream is closed. You can stop the bidirectional stream by either closing the WebSocket or ending the call.

  There can be only one concurrent bidirectional stream per call; no simultaneous bidirectional streams.

  CarrierX neither issues nor answers mark message events.

Supported Attributes

These attributes can be used to modify Stream. They are inserted as name-value pairs in the opening tag.

Attribute	Data Type	Description
audio_track	string	Determines which tracks to stream. The same as track. Use either the track attribute or the audio_track attribute, but not both. inbound - only the inbound audio. outbound - only the outbound audio. both - both the inbound and outbound audio as separate tracks. mixed - both the inbound and outbound audio as a single track. Note that this attribute is applicable to unidirectional streams only.
encoding	string	Determines the audio encoding format for the stream. audio/x-mulaw - default encoding. audio/L16 - linear 16-bit PCM (Pulse-Code Modulation). Note: If the call uses an HD (wideband) codec, using audio/L16 can preserve higher audio quality. For non-HD codecs, audio/L16 works but doesn't improve quality. It only increases bandwidth.
maxLength	string	The maximum length, in seconds, to stream. Note that this attribute is applicable to unidirectional streams only.
name	string	A unique identifier of the stream. If the stream will be stopped, via the Stop verb, use the same name, which was used to Start this stream.
suppressAnswer	boolean	When set to true, prevents the system from automatically answering the call (returning a 200 OK response). This allows media to be streamed while the call remains unanswered. The default value is false. To answer the call at a later point in the flow, include a verb such as Say or Play after Stream. You can also use PreAnswer to play early media while the call remains unanswered. If the flow reaches Hangup before an answering verb, the call is declined without ever being answered. Note: This attribute only works when Stream is used as a top-level verb directly inside Response. It has no effect when Stream is nested inside Start, Stop, or Connect. Support within Start is planned for a future release.
timestampStart	string	relative (default) or absolute - this defines how the timestamp attribute of the Media Message Object is represented. relative timestamps start at 0. absolute timestamps start at the epoch (1970-01-01T00:00:00).
track	string	Determines which tracks to stream. The same as audio_track. Use either the track attribute or the audio_track attribute, but not both. inbound_track - only the inbound audio. outbound_track - only the outbound audio. both_tracks - both the inbound and outbound audio as separate tracks. mixed_tracks - both the inbound and outbound audio as a single track. Note that this attribute is applicable to unidirectional streams only.
url required	string	The relative or absolute URL of the WebSocket server. Both ws and wss protocols are supported. As the url does not support URL parameters, use Parameters to send custom key/value pairs. Note that url is required only for the Start verb.

Starting and Stopping the Stream

To start and stop a unidirectional Stream, you should wrap Stream in Start tags when opening a stream and in Stop tags to stop the stream, using the name attribute to identify the stream. If you do not stop the Stream, it will continue until the end of the call.

...
<Start>
  <Stream url="wss://example.com" name="myStream" encoding="audio/L16" />
</Start>
...
<Stop>
  <Stream name="myStream" />
</Stop>
...

To pass custom key/value pairs to the WebSocket server, use Parameter.

<Stream>
  <Parameter name="First Name" value="John"/>
  <Parameter name="Last Name" value="Cleese"/>
</Stream>

To start and stop a bidirectional Stream you should wrap Stream in Connect tags, using the name attribute to identify the stream.

<Connect>
  <Stream url="wss://example.com" name="myStream" encoding="audio/L16" />
</Connect>

Examples

Example: Media Streaming without Answering

In this example, Stream is used as a top-level verb so that media streaming begins immediately without answering the call. The call remains unanswered while audio is forked to your WebSocket server.

<Response>
  <Stream url="wss://example.com/stream"
          name="mediaFork"
          track="both_tracks"
          suppressAnswer="true">
    <Parameter name="sessionId" value="12345"/>
  </Stream>
  <PreAnswer>
    <Say>Please hold while we verify your identity.</Say>
  </PreAnswer>
  <Hangup />
</Response>

note

suppressAnswer is only applicable to Stream when Stream is used as a top-level verb directly inside Response. It does not work when Stream is nested inside Start, Stop, or Connect. For session-based recording without answering, see the suppressAnswer attribute on the Record verb.

Nesting Rules

• You can nest Parameter within Stream
• You can nest Stream within Start and Stop verbs (in case of unidirectional streams), and within Connect verb (in case of bidirectional streams).