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.

  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.
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.
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">
</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">
  </Stream>
</Connect>

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