Documentation

Global

Members

<constant> AudioCodec :string

Names of the supported audio codecs.

Type:
  • string
Properties:
Name Type Default Description
isac string isac
opus string opus
PCMA string PCMA
PCMU string PCMU

<constant> BandwidthProfileMode :string

BandwidthProfileMode specifies how RemoteVideoTracks' Track.Priority values are mapped to bandwidth allocation in Group Rooms.

Type:
  • string
Properties:
Name Type Default Description
grid string grid

This mode is for use cases where all the subscribed RemoteVideoTracks are equally important. The bandwidth allocation algorithm will share the available downlink bandwidth equally among the subscribed RemoteVideoTracks, irrespective of their Track.Priority. In case of insufficient downlink bandwidth, the lower priority RemoteVideoTracks are switched off.
collaboration string collaboration

This mode is for use cases where some RemoteVideoTracks are prioritized more than others. However, the lower priority RemoteVideoTracks still need to be visible. The bandwidth allocation algorithm will share the available downlink bandwidth proportional to the requested VideoRenderDimensions corresponding to their Track.Priority. In case of insufficient downlink bandwidth, the quality of higher priority RemoteVideoTracks may be degraded to avoid switching off lower priority RemoteVideoTracks.
presentation string presentation

This mode is for use cases where some RemoteVideoTracks are deemed critical and must be preserved at any cost over the other RemoteVideoTracks. The bandwidth allocation algorithm will allocate as big a share of the available downlink bandwidth as it possibly can to the higher priority RemoteVideoTracks, and only then consider the lower priority RemoteVideoTracks. In case of insufficient downlink bandwidth, the lower priority RemoteVideoTracks are switched off in order to preserve the quality of the higher priority RemoteVideoTracks.

<constant> EventListenerGroup :string

Names of the supported groups for EventListenerEvents.

Type:
  • string
Properties:
Name Type Default Description
signaling string signaling

Events associated with the connection to Twilio's signaling server

<constant> EventListenerLevel :string

Names of the supported levels for EventListenerEvents.

Type:
  • string
Properties:
Name Type Default Description
debug string debug
error string error
info string info
warning string warning

<constant> LogLevel :string

Levels for logging verbosity.

Type:
  • string
Properties:
Name Type Default Description
debug string debug
info string info
warn string warn
error string error
off string off

<constant> NetworkQualityVerbosity :number

The verbosity level of network quality information of a Participant.

Type:
  • number
Properties:
Name Type Default Description
none number 0

Nothing is reported for the Participant. This has no effect and defaults to NetworkQualityVerbosity#minimal for the LocalParticipant.
minimal number 1

Reports NetworkQualityLevel for the Participant.
moderate number 2

Reports NetworkQualityLevel and NetworkQualityStats for the Participant. NetworkQualityStats is populated with audio and video NetworkQualityLevels based on which the Participant's NetworkQualityLevel is calculated.
detailed number 3

Reports NetworkQualityLevel and NetworkQualityStats for the Participant. NetworkQualityStats is populated with audio and Video NetworkQualityLevels and their corresponding NetworkQualityMediaStats based on which the Participant's NetworkQualityLevel is calculated.

<constant> TrackSwitchOffMode :string

TrackSwitchOffMode specifies when RemoteVideoTracks' are switched off.

Type:
  • string
Properties:
Name Type Default Description
detected string detected

In this mode, RemoteVideoTracks are switched off only when network congestion is detected.
predicted string predicted

In this mode, RemoteVideoTracks are pro-actively switched off when network congestion is predicted by the bandwidth estimation mechanism.
disabled string disabled

In this mode, RemoteVideoTracks are not switched off. Instead in response to network congestion, tracks will be adjusted to lower quality.

<constant> VideoCodec :string

Names of the supported video codecs.

Type:
  • string
Properties:
Name Type Default Description
H264 string H264
VP8 string VP8
VP9 string VP9

Type Definitions

AudioCodecSettings

Audio codec settings.

Type:
  • object
Properties:
Name Type Description
codec AudioCodec

Audio codec name

AudioLevel

The maximum absolute amplitude of a set of audio samples in the range of 0 to 32767 inclusive.

Type:
  • number

AudioTrackPublication

A LocalAudioTrackPublication or a RemoteAudioTrackPublication.

Type:

BandwidthProfileOptions

BandwidthProfileOptions allows you to configure how your available downlink bandwidth is shared among the RemoteTracks you have subscribed to in a Group Room.

Type:
  • object
Properties:
Name Type Argument Description
video VideoBandwidthProfileOptions <optional>

Optional parameter to configure how your available downlink bandwidth is shared among the RemoteVideoTracks you have subscribed to in a Group Room.

ConnectOptions

You may pass these options to connect in order to override the default behavior.

Type:
  • object
Properties:
Name Type Argument Default Description
audio boolean | CreateLocalTrackOptions <optional>
 true

Whether or not to get local audio with getUserMedia when tracks are not provided.
automaticSubscription boolean <optional>
 true

By default, you will subscribe to all RemoteTracks shared by other Participants in a Room. You can now override this behavior by setting this flag to false. It will make sure that you will not subscribe to any RemoteTrack in a Group or Small Group Room. Setting it to true, or not setting it at all preserves the default behavior. This flag does not have any effect in a Peer-to-Peer Room.
bandwidthProfile BandwidthProfileOptions <optional>

You can optionally configure how your available downlink bandwidth is shared among the RemoteTracks you have subscribed to in a Group Room. By default, bandwidth is shared equally among the RemoteTracks. This has no effect in Peer-to-Peer Rooms.
dominantSpeaker boolean <optional>
 false

Whether to enable the Dominant Speaker API or not. This only takes effect in Group Rooms.
dscpTagging boolean <optional>
 false

(deprecated: use "enableDscp" instead) DSCP tagging allows you to request enhanced QoS treatment for RTP media packets from any firewall that the client may be behind. Setting this option to true will request DSCP tagging for media packets on supported browsers (only Chrome supports this as of now). Audio packets will be sent with DSCP header value set to 0xb8 which corresponds to Expedited Forwarding (EF). Video packets will be sent with DSCP header value set to 0x88 which corresponds to Assured Forwarding (AF41).
enableDscp boolean <optional>
 false

DSCP tagging allows you to request enhanced QoS treatment for RTP media packets from any firewall that the client may be behind. Setting this option to true will request DSCP tagging for media packets on supported browsers (only Chrome supports this as of now). Audio packets will be sent with DSCP header value set to 0xb8 which corresponds to Expedited Forwarding (EF). Video packets will be sent with DSCP header value set to 0x88 which corresponds to Assured Forwarding (AF41).
eventListener EventListener <optional>

(deprecated: use Video.Logger you can listen to fine-grained events related to signaling and media that are not available in the public APIs. These events might be useful for your own reporting and diagnostics.
iceServers Array.<RTCIceServer>

Override the STUN and TURN servers used when connecting to Rooms
iceTransportPolicy RTCIceTransportPolicy <optional>
 "all"

Override the ICE transport policy to be one of "relay" or "all"
insights boolean <optional>
 true

Whether publishing events to the Insights gateway is enabled or not
maxAudioBitrate number <optional>
<nullable>
 null

Max outgoing audio bitrate (bps); A null or a 0 value does not set any bitrate limit; This value is set as a hint for variable bitrate codecs, but will not take effect for fixed bitrate codecs; Based on our tests, Chrome, Firefox and Safari support a bitrate range of 12000 bps to 256000 bps for Opus codec; This parameter has no effect on iSAC, PCMU and PCMA codecs
maxVideoBitrate number <optional>
<nullable>
 null

Max outgoing video bitrate (bps); A null or 0 value does not set any bitrate limit; This value is set as a hint for variable bitrate codecs, but will not take effect for fixed bitrate codecs; Based on our tests, Chrome, Firefox and Safari all seem to support an average bitrate range of 20000 bps (20 kbps) to 8000000 bps (8 mbps) for a 720p VideoTrack
name string <optional>
<nullable>
 null

Set to connect to a Room by name
networkQuality boolean | NetworkQualityConfiguration <optional>
 false

Whether to enable the Network Quality API or not. This only takes effect in Group Rooms. Pass a NetworkQualityConfiguration to configure verbosity levels for network quality information for LocalParticipant and RemoteParticipants. A true value will set the NetworkQualityVerbosity for the LocalParticipant to NetworkQualityVerbosity#minimal and the NetworkQualityVerbosity for RemoteParticipants to NetworkQualityVerbosity#none.
region string <optional>
 'gll'

Preferred signaling region; By default, you will be connected to the nearest signaling server determined by latency based routing. Setting a value other than gll bypasses routing and guarantees that signaling traffic will be terminated in the region that you prefer. Please refer to this table for the list of supported signaling regions.
preferredAudioCodecs Array.<(AudioCodec|AudioCodecSettings)> <optional>
 []

Preferred audio codecs; An empty array preserves the current audio codec preference order.
preferredVideoCodecs Array.<(VideoCodec|VideoCodecSettings)> <optional>
 []

Preferred video codecs; An empty array preserves the current video codec preference order. If you want to set a preferred video codec on a Group Room, you will need to create the Room using the REST API and set the VideoCodecs property. See here for more information.
logLevel LogLevel | LogLevels <optional>
 'warn'

(deprecated: use Video.Logger instead. See examples for details) Set the default log verbosity of logging. Passing a LogLevel string will use the same level for all components. Pass a LogLevels to set specific log levels.
loggerName string <optional>
 'twilio-video'

The name of the logger. Use this name when accessing the logger used by the SDK. See examples for details.
tracks Array.<(LocalTrack|MediaStreamTrack)> <optional>

The LocalTracks or MediaStreamTracks with which to join the Room. These tracks can be obtained either by calling createLocalTracks, or by constructing them from the MediaStream obtained by calling getUserMedia().
video boolean | CreateLocalTrackOptions <optional>
 true

Whether or not to get local video with getUserMedia when tracks are not provided.

CreateLocalTrackOptions

Create LocalTrack options. Apart from the properties listed here, you can also specify any of the MediaTrackConstraints properties.

Type:
  • MediaTrackConstraints
Properties:
Name Type Argument Default Description
logLevel LogLevel | LogLevels <optional>
 'warn'

(deprecated: use Video.Logger instead. See examples for details) Set the default log verbosity of logging. Passing a LogLevel string will use the same level for all components. Pass a LogLevels to set specific log levels.
loggerName string <optional>
 'twilio-video'

The name of the logger. Use this name when accessing the logger used by the SDK. See examples for details.
name string <optional>

The LocalTrack's name; by default, it is set to the LocalTrack's ID.
workaroundWebKitBug180748 boolean <optional>
 false

Only valid for LocalAudioTracks; setting this attempts to workaround WebKit Bug 180748, where, in Safari, getUserMedia may return a silent audio MediaStreamTrack.

CreateLocalTracksOptions

createLocalTracks options

Type:
  • object
Properties:
Name Type Argument Default Description
audio boolean | CreateLocalTrackOptions <optional>
 true

Whether or not to get local audio with getUserMedia when tracks are not provided.
logLevel LogLevel | LogLevels <optional>
 'warn'

(deprecated: use Video.Logger instead. See examples for details) Set the default log verbosity of logging. Passing a LogLevel string will use the same level for all components. Pass a LogLevels to set specific log levels.
loggerName string <optional>
 'twilio-video'

The name of the logger. Use this name when accessing the logger used by the SDK. See examples for details.
video boolean | CreateLocalTrackOptions <optional>
 true

Whether or not to get local video with getUserMedia when tracks are not provided.

DataTrack

A DataTrack is a LocalDataTrack or RemoteDataTrack.

Type:

DataTrackPublication

A LocalDataTrackPublication or a RemoteDataTrackPublication.

Type:

EncodingParameters

Outgoing media encoding parameters.

Type:
  • object
Properties:
Name Type Argument Description
maxAudioBitrate number <optional>
<nullable>

Max outgoing audio bitrate (bps); If not specified, retains the existing bitrate limit; A null or a 0 value removes any previously set bitrate limit; This value is set as a hint for variable bitrate codecs, but will not take effect for fixed bitrate codecs; Based on our tests, Chrome, Firefox and Safari support a bitrate range of 12000 bps to 256000 bps for Opus codec; This parameter has no effect on iSAC, PCMU and PCMA codecs
maxVideoBitrate number <optional>
<nullable>

Max outgoing video bitrate (bps); If not specified, retains the existing bitrate limit; A null or a 0 value removes any previously set bitrate limit; This value is set as a hint for variable bitrate codecs, but will not take effect for fixed bitrate codecs; Based on our tests, Chrome, Firefox and Safari all seem to support an average bitrate range of 20000 bps (20 kbps) to 8000000 bps (8 mbps) for a 720p VideoTrack. Note: this limit is not applied for screen share tracks published on Chrome.

EventListener

An EventListener allows you to listen to fine-grained EventListenerEvents related to signaling and media that are not available in the public APIs, which might be useful for your own reporting and diagnostics.

Type:
  • EventEmitter
Example
const { EventEmitter } = require('events');
const { connect } = require('twilio-video');

const eventListener = new EventEmitter();
eventListener.on('event', function(event) {
  console.log('The SDK raised an event:', event);
});

connect('token', {
  eventListener: eventListener
});

EventListenerClosedEvent

The connection to Twilio's signaling server was closed.

Type:
Properties:
Name Type Default Description
group EventListenerGroup 'signaling'
level EventListenerLevel

'info' if the connection was closed by the client, 'error' otherwise
name string 'closed'
payload Object

Reason for the connection being closed. It can be one of 'busy', 'failed', 'local', 'remote' or 'timeout'

EventListenerConnectingEvent

The SDK is connecting to Twilio's signaling server.

Type:
Properties:
Name Type Default Description
group EventListenerGroup 'signaling'
level EventListenerLevel 'info'
name string 'connecting'

EventListenerEarlyEvent

The SDK is about to connect to Twilio's signaling server.

Type:
Properties:
Name Type Default Description
group EventListenerGroup 'signaling'
level EventListenerLevel 'info'
name string 'early'

EventListenerEvent

An EventListenerEvent provides context about an event raised by the SDK on the EventListener. Apart from the properties listed here, it may also include some event-specific data within an optional "payload" property. The different types of EventListenerEvents are listed below:

Type:
  • object
Properties:
Name Type Argument Description
elapsedTime number

The time elapsed in milliseconds since connect() was called
group EventListenerGroup

The group under which the event is classified
level EventListenerLevel

The verbosity level of the event, which can be one of "debug", "error", "info", "warning"
name string

The name of the event
payload * <optional>

Optional event-specific data
timestamp number

The time in milliseconds relative to the Unix Epoch when the event was raised

EventListenerOpenEvent

The SDK has established a signaling connection to Twilio's signaling server.

Type:
Properties:
Name Type Default Description
group EventListenerGroup 'signaling'
level EventListenerLevel 'info'
name string 'open'

EventListenerWaitingEvent

The SDK is waiting to retry connecting th Twilio's signaling server. This can happen if the server is busy with too many connection requests.

Type:
Properties:
Name Type Default Description
group EventListenerGroup 'signaling'
level EventListenerLevel 'warning'
name string 'waiting'

LocalDataTrackOptions

LocalDataTrack options

Type:
Properties:
Name Type Argument Default Description
maxPacketLifeTime number <optional>
<nullable>
 null

Set this to limit the time (in milliseconds) during which the LocalDataTrack will send or re-send data if not successfully delivered on the underlying RTCDataChannel(s). It is an error to specify both this and maxRetransmits.
maxRetransmits number <optional>
<nullable>
 null

Set this to limit the number of times the LocalDataTrack will send or re-send data if not acknowledged on the underlying RTCDataChannel(s). It is an error to specify both this and maxPacketLifeTime.
ordered boolean <optional>
 true

Set this to false to allow data on the LocalDataTrack to be sent out-of-order.

LocalTrack

A LocalTrack is a LocalAudioTrack, LocalVideoTrack, or LocalDataTrack.

Type:

LocalTrackOptions

LocalTrack options

Type:
  • object
Properties:
Name Type Argument Description
logLevel LogLevel | LogLevels

Log level for 'media' modules
name string <optional>

The LocalTrack's name; by default, it is set to the LocalTrack's ID.

LocalTrackPublishOptions

Options for publishing a LocalTrack.

Type:
  • object
Properties:
Name Type Argument Default Description
priority Track.Priority <optional>
 'standard'

The priority with which the LocalTrack is to be published; In Group or Small Group Rooms, the appropriate bandwidth is allocated to the LocalTrack based on its Track.Priority; It has no effect in Peer-to-Peer Rooms; It defaults to "standard" when not provided

LogLevels

You may pass these levels to ConnectOptions to override log levels for individual components.

Type:
  • object
Properties:
Name Type Argument Default Description
default LogLevel <optional>
 'warn'

Log level for 'default' modules.
media LogLevel <optional>
 'warn'

Log level for 'media' modules.
signaling LogLevel <optional>
 'warn'

Log level for 'signaling' modules.
webrtc LogLevel <optional>
 'warn'

Log level for 'webrtc' modules.

MediaStreamTrackPublishOptions

Options for publishing a MediaStreamTrack.

Type:
Properties:
Name Type Argument Default Description
priority Track.Priority <optional>
 'standard'

The priority with which the LocalTrack is to be published; In Group or Small Group Rooms, the appropriate bandwidth is allocated to the LocalTrack based on its Track.Priority; It has no effect in Peer-to-Peer Rooms; It defaults to "standard" when not provided

NetworkQualityConfiguration

Configure verbosity levels for network quality information for LocalParticipant and RemoteParticipants.

Type:
  • object
Properties:
Name Type Argument Default Description
local NetworkQualityVerbosity <optional>
 1

Verbosity level for LocalParticipant
remote NetworkQualityVerbosity <optional>
 0

Verbosity level for RemoteParticipants

NetworkQualityLevel

NetworkQualityLevel is a value from 0–5, inclusive, representing the quality of a network connection.

Type:
  • number

OpusCodecSettings

Opus codec settings.

Type:
Properties:
Name Type Argument Default Description
name AudioCodec

"opus"
dtx boolean <optional>
 true

Enable/disable discontinuous transmission (DTX); If enabled all published LocalAudioTracks will reduce the outgoing bitrate to near-zero whenever speech is not detected, resulting in bandwidth and CPU savings; It defaults to true.

RemoteTrack

A RemoteTrack is a RemoteAudioTrack, RemoteVideoTrack, or RemoteDataTrack.

Type:

RemoteTrackPublicationOptions

RemoteTrackPublication options

Type:
  • object
Properties:
Name Type Description
logLevel LogLevel | LogLevels

Log level for 'media' modules

TrackPublicationOptions

TrackPublication options

Type:
  • object
Properties:
Name Type Description
logLevel LogLevel | LogLevels

Log level for 'media' modules

VideoBandwidthProfileOptions

VideoBandwidthProfileOptions allows you to configure how your available downlink bandwidth is shared among the RemoteVideoTracks you have subscribed to in a Group Room.

Type:
  • object
Properties:
Name Type Argument Default Description
dominantSpeakerPriority Track.Priority <optional>
 "standard"

Optional parameter to specify the minimum subscribe Track.Priority of the Dominant Speaker's RemoteVideoTracks. This means that the Dominant Speaker's RemoteVideoTracks that are published with lower Track.Priority will be subscribed to with the Track.Priority specified here. This has no effect on RemoteVideoTracks published with higher Track.Priority, which will still be subscribed to with with the same Track.Priority. If not specified, this defaults to "standard". This parameter only applies to a Group Room Participant when ConnectOptions.dominantSpeaker is set to true.
maxSubscriptionBitrate number <optional>

Optional parameter to specify the maximum downlink video bandwidth in bits per second (bps). By default, there are no limits on the downlink video bandwidth.
maxTracks number <optional>

Optional parameter to specify the maximum number of visible RemoteVideoTracks, which will be selected based on Track.Priority and an N-Loudest policy. By default there are no limits on the number of visible RemoteVideoTracks. 0 or a negative value will remove any limit on the maximum number of visible RemoteVideoTracks.
mode BandwidthProfileMode <optional>
 "grid"

Optional parameter to specify how the RemoteVideoTracks' TrackPriority values are mapped to bandwidth allocation in Group Rooms. This defaults to "grid", which results in equal bandwidth share allocation to all RemoteVideoTracks.
renderDimensions VideoRenderDimensions <optional>

Optional parameter to specify the desired render dimensions of RemoteVideoTracks based on Track.Priority and the RemoteVideoTracks of the Dominant Speaker.
trackSwitchOffMode TrackSwitchOffMode <optional>
 "predicted"

Optional parameter to configure how RemoteVideoTracks are switched off in response to bandwidth pressure. Defaults to "predicted".

VideoCodecSettings

Video codec settings.

Type:
  • object
Properties:
Name Type Description
codec VideoCodec

Video codec name

VideoProcessor

A VideoProcessor is used to process incoming video frames before sending to the encoder or renderer.

Type:
  • object
Properties:
Name Type Description
processFrame function

A callback to receive incoming video frames for processing. Any exception raised (either synchronously or asynchronously) in processFrame will result in the frame being dropped. Developers can drop the current frame by returning null. This callback has the following signature: processFrame(inputFrame: OffscreenCanvas)
  : Promise<OffscreenCanvas | null>
  | OffscreenCanvas | null;

VideoRenderDimensions

VideoRenderDimensions allows you to specify the desired render dimensions of RemoteVideoTracks based on Track.Priority. The bandwidth allocation algorithm will distribute the available downlink bandwidth proportional to the requested render dimensions. This is just an input for calculating the bandwidth to be allocated and does not affect the actual resolution of the RemoteVideoTracks.

Type:
  • object
Properties:
Name Type Argument Description
high VideoTrack.Dimensions <optional>

Optional parameter to specify the desired rendering dimensions of RemoteVideoTrack whose Track.Priority is "high". 0 or a negative value will result in the lowest possible resolution. This defaults to 1280 x 720 (HD).
low VideoTrack.Dimensions <optional>

Optional parameter to specify the desired rendering dimensions of RemoteVideoTrack whose Track.Priority is "low". 0 or a negative value will result in the lowest possible resolution. This defaults to 176 x 144 (QCIF).
standard VideoTrack.Dimensions <optional>

Optional parameter to specify the desired rendering dimensions of RemoteVideoTrack whose Track.Priority is "standard". 0 or a negative value will result in the lowest possible resolution. This defaults to 640 x 480 (VGA).

VideoTrackPublication

A LocalVideoTrackPublication or a RemoteVideoTrackPublication.

Type:

VP8CodecSettings

VP8 codec settings.

Type:
Properties:
Name Type Argument Default Description
name VideoCodec

"VP8"
simulcast boolean <optional>
 false

Enable/disable VP8 simulcast; If enabled, Twilio's Video SDK will send three video streams of different qualities