This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.
By default clients connecting to a Group Room subscribe to all tracks published and as such all participants can see and hear all other participants. The Track Subscription API allows you to change this behavior and manage the communication topology of a Group Room. There are many possibilities, for example one participant could be set up as a silent observer, or the Group Room could be arranged so that all participants are only subscribed to the video and audio of a single presenter. Specifically, the API allows you to:
The Track Subscription API is only available in Group Rooms. Check the SDK Compatibility section below for further compatibility information.
The Track Subscription API is a REST API. However, it fires subscription events that must be managed client side, which is only available in the following SDK versions:
Twilio SDK | Track Subscriptions Support |
---|---|
JavaScript | SDK 1.15.0+ |
iOS | SDK 2.4.0+ |
Android | SDK 3.0.0+ |
For further information on how to manage client side subscription events and errors check the Managing Track Subscriptions with Twilio Client SDKs section below.
Twilio Group Rooms media communications work though a publish/subscribe model that relies on the following principles:
This document describes how the Track Subscription API can be used for setting which participants subscribe to which tracks. Some possible subscription models developers can implement using this API are the following:
By default Group Rooms use a "subscribe-to-all" model. Hence, each participant subscribes to all the tracks published to the room by the rest of participants.
For the sake of simplicity, we define the Participant Resource URI as:
_10PARTICIPANT_URI = https://video.twilio.com/v1/Rooms/{RoomNameOrSid}/Participants/{ParticipantIdentityOrSid}
As children, the resources of the Track Subscription API are:
PARTICIPANT_URI/SubscribedTracks
GET
: Lists the Tracks subscribed by the specified Participant.
PARTICIPANT_URI/SubscribedTracks/{TrackSid}/
GET
: Retrieves the SubscribedTrack instance resource with information about the
subscription of the specified Track by the specified Participant.
PARTICIPANT_URI/SubscribeRules
GET
: Retrieves the subscribe rules for the specified Participant.
POST
: Updates the subscribe rules of the specified Participant
A SubscribedTrack
instance is a Participant
's resource that represents the
subscription such Participant has for a given Track.
PARTICIPANT_URI/SubscribedTracks/{TrackSid}/
This resource has the following properties:
The unique string that we created to identify the RoomParticipantSubscribedTrack resource.
The track name. Must have no more than 128 characters and be unique among the participant's published tracks.
The date and time in GMT when the resource was created specified in ISO 8601 format.
The date and time in GMT when the resource was last updated specified in ISO 8601 format.
The track type. Can be: audio
, video
or data
.
audio
video
data
The absolute URL of the resource.
Retrieves the SubscribedTrack
instance resource associated to the specified Participant and TrackSid.
This resource does not support POST
, PUT
or DELETE
. For modifying the
track subscriptions of a participant see the SubscribeRules Resource
section below.
The SubscribedTracks
list resource represents the subscriptions of a
given Participant in a Group Room.
PARTICIPANT_URI/SubscribedTracks
Retrieves the list of subscribed tracks associated to the specified Participant
with paging data.
This resource does not support POST
, PUT
or DELETE
. For modifying the
track subscriptions of a participant see the SubscribeRules Resource
section below.
The SubscribeRules
resource is a singleton resource that represents the
subscribe rules that are enforced on a given Participant.
PARTICIPANT_URI/SubscribeRules
This resource has the following properties:
A collection of Subscribe Rules that describe how to include or exclude matching tracks. See the Specifying Subscribe Rules section for further information.
The date and time in GMT when the resource was created specified in ISO 8601 format.
Returns the subscribe rules of the specified Participant.
Updates the subscribe rules of the specified Participant. The following parameters are supported:
The SID of the Room resource where the subscribe rules to update apply.
The SID of the Participant resource to update the Subscribe Rules.
A JSON-encoded array of subscribe rules. See the Specifying Subscribe Rules section for further information.
For a deeper understanding on how subscribe rules work, see the Understanding Subscribe Rules section below.
This resource does not support PUT
or DELETE
.
Subscribe rules can be set:
A subscription rule instance is a JSON with the following structure:
_10{"type": rule_type, filter_name: filter_value, filter_name: filter_value, ...}
Where:
Field | Description |
---|---|
rule_type | An identifier specifying the type of rule. Can be one of the following:-include : includes the tracks that match the filters into the subscription.-exclude : excludes the tracks that match the filters from the subscription. |
filter_name and filter_value | The filter_name must be one of the following:-all : the filter affects all tracks. Accepts only one value: true (matches all tracks)-kind : matches tracks of a given type. Accepts video , audio and data as values.-publisher : matches all tracks published by the Participant with the identity (case sensitive) or SID specified as value-track : matches tracks with the name (case sensitive) or SID specified as value. A rule containing multiple filters matches the set of tracks that comply with all of them. In other words, filters combine in a rule through a logical AND. Note also that the tracks published by a participant are never considered when evaluating such participant's filters. As a consequence, a participant cannot subscribe to her own tracks. |
Based on this, subscribe rules are specified as a JSON array containing up to 20 rules. For example:
_10Rules = [_10 {"type": "include", "all": true}, //rule_1_10 {"type": "exclude", "kind": "video"}, //rule_2_10 {"type": "include", "publisher": "Bob", "track": "screen"}, //rule_3_10 {"type": "include", "track": "MTXXXXXXXXXXXXXXXXXXXXXXXXXXX"}, //rule_4_10 ..._10 rule_20_10]
Remember that valid subscription rules comply with the following:
[]
) is not allowed.
"all"
filter must have a value of
true
. Notice that
this means
false
is not allowed.
“all”
filter cannot have any other filters.
"type"
field.
"kind"
filter is used, its value must be one of
audio
,
video
or
data
.
kind
s or
publisher
s, etc.)
When invalid rules are specified, the currently active rules will not be updated
and the POST will be answered with an HTTP 400
error response like the following:
_10{_10 "code": 53215,_10 "message": "Invalid Subscribe Rule(s)",_10 "more_info": "https://www.twilio.com/docs/errors/53215",_10 "status": 400_10}
For example, the following requests are invalid:
_10//Invalid because it's using an empty set_10Rules = []
_10//Invalid because it uses false as value of "all"_10Rules = [_10 {"type":"include", "all": false}_10]
_10//Invalid because it specifies a non supported kind_10Rules = [_10 {"type": "include", "all": true},_10 {"type": "exclude", "kind": "wideo"}_10]
_10//Invalid because it repeats the "kind" filter twice_10Rules = [_10 {"type": "include", "kind": "audio", "kind": "data"},_10]
_10//Invalid because an "all" filter is not compatible with any other filter_10Rules = [_10 {"type": "include", "all": "true", "kind": "data"},_10]
SubscribeRules
are enforced by Twilio using four main principles:
We define the Set of Subscribed Tracks (SetST) as the set of tracks a given participant should be subscribed to at any time. The SetST is computed by Twilio using Algebra of Sets based on the following algorithm:
include
rule we perform the union of the SetST with the set of
tracks matching the rule filters.
exclude
rule we perform the set difference of the SetST with
the set of tracks matching by the rule filters.
Let's illustrate this using an example. Imagine a Group Room with three participants named: Alice, Bob and Carl, who publish the tacks specified in the following table:
Alice (PTA) | Bob (PTB) | Carl (PTC) | |
---|---|---|---|
Audio Track | MTA_A alice-audio | MTB_A bob-audio | MTC_A carl-audio |
Video Track (cam) | MTA_C alice-cam | MTB_C bob-cam | MTC_C carl-cam |
Video Track (screen) | MTA_S screen | MTB_S screen | |
Data Track | MTC_D carl-data |
Notice that, for the sake of simplicity, we have assumed the following conventions:
MT
followed by the participant initial and by a
letter identifying the track nature (
_A
for audio,
_C
for webcam,
_S
for
screenshare and
_D
for data).
In this context, imagine that we POST the following rules to Alice's
/SubscribeRules
resource:
_10Rules = [_10 {"type": "include", "all": true},_10 {"type": "exclude", "kind": "video"},_10 {"type": "include", "publisher": "Bob", "track": "screen"}_10]
Then, the algorithm will compute the tracks Alice should subscribe to in the following way:
Alice's rules (applied in the specified order) | Tracks in the SetST |
---|---|
SetST is initialized to the empty set. | [] |
{"type": "include", "all": true} Includes all tracks (except Alice's ones.) | [MTB_A,MTB_C,MTB_S,MTC_A,MTC_C,MTC_D] |
{"type": "exclude", "kind": "video"} Excludes all video tracks. | [MTB_A,MTC_A,MTC_D] |
{"type": "include", "publisher": "Bob", "track": "screen"} Includes Bob's tracks named screen . | [MTB_A,MTC_A,MTC_D,MTB_S] Alice is finally subscribed to these Tracks. |
Still assuming the above specified Group Room scenario, consider the following examples that might be interesting to understand how the subscription algorithm works:
When POSTing to Alice's subscribe rules the following:
_10Rules = [_10 {"type": "include", "all": true}_10]
Alice will subscribe to all the tracks (except for her own). Hence, the SetST will be:
_10[MTB_A,MTB_C,MTB_S,MTC_A,MTC_C,MTC_D]
This happens because:
[]
When POSTing to Alice's subscribe rules the following:
_10Rules = [_10 {"type": "exclude", "all": true}_10]
Alice will subscribe to no tracks:
_10[] //The empty set
This happens because:
[]
When POSTing to Alice's subscribe rules the following:
_10Rules = [_10 {"type": "exclude", "kind": "video"}_10]
Alice's subscribed tracks will be:
_10[] //The empty set
This happens because:
[]
.
When POSTing to Alice's subscribe rules the following:
_10Rules = [_10 {"type": "include", "track": "alice-audio"}_10]
Alice's subscribed tracks will be:
_10[] //The empty set
This happens because:
[]
.
When POSTing to Alice's subscribe rules the following:
_10Rules = [_10 {"type": "include", "track": "screen"}_10]
Alice's subscribed tracks will be:
_10[MTB_S] //Bob's screen track
This happens because:
[]
.
screen
. There are two of them, one
owned by Alice. As filters do not consider the participant's own tracks, then
Alice subscribes to the union of
[MTB_S]
and the empty set. Filters containing
participant or track names are case sensitive.
When POSTing to Carl's subscribe rules the following:
_10Rules = [_10 {"type": "include", "all": true},_10 {"type": "exclude", "publisher": "PTB", "kind": "audio"},_10 {"type": "exclude", "kind": "video", "track": "screen"}_10]
Carl's subscribed tracks will be:
_10[MTA_A, MTA_C, MTB_C]
This happens because:
[]
.
[MTA_A,MTA_C,MTA_S,MTB_A,MTB_C,MTB_S]
PTB
is Bob's SID). That is,
MTB_A
is excluded.
screen
.
Hence,
MTA_S
and
MTB_S
are also excluded.
When POSTing to Alice's subscribe rules the following:
_10Rules = [_10 {"type": "include", "kind": "data"},_10 {"type": "exclude", "publisher": "Carl"}_10]
Alice's subscribed tracks will be:
_10[] //The empty set
This happens because:
[]
.
MTC_D
MTC_D
and
results in the empty set.
However, when POSTing
_10Rules = [_10 {"type": "exclude", "publisher": "Carl"},_10 {"type": "include", "kind": "data"}_10]
Alice's subscribed tracks will be:
_10[MTC_D]
This happens because:
[]
.
MTC_D
to the SetST.
The Track Subscription API is stateless. This means that it has no memory of rules or subscribed tracks. Every time a developer POSTs a set of new subscription rules, the previous rules are fully erased and replaced with new rules, which are then enforced using the algorithm described in the section above.
To illustrate this, and assuming the Group Room scenario described above, let's imagine that Carl wants to subscribe to all audio tracks and exclude the rest. POSTing the following rules will do it:
_10Rules = [_10 {"type": "include", "kind": "audio"}_10]
Imagine now that Carl, while keeping his current audio subscriptions, also wants to subscribe to Alice's screenshare. Carl could do it POSTing the following:
_10Rules = [_10 {"type": "include", "kind": "audio"},_10 {"type": "include", "track": "MTA_S"}_10]
Observe that if the first rule is omitted, given the stateless nature of the
Track Subscription API, Carl would be subscribed only to MTA_S
but not to
Alice's and Bob's audios.
If now Carl wants to stop receiving Alice's screen, but instead wants to see Bob's webcam while still receiving all the audios, the POST should contain something like this:
_10Rules = [_10 {"type": "include", "kind": "audio"},_10 {"type": "include", "track": "MTB_C"}_10]
As you can see, each POST "resets" the subscribe rules making it necessary to specify what should be included and excluded at all requests.
When developers POST subscribe rules to Twilio, those rules are enforced in a dynamic way. That means that the algorithm does not only execute at POST time, but it is executed every time there is change in the Room's available tracks. Hence, once the rules have been POSTed, Twilio guarantees that they are enforced at any time without requiring further developer intervention.
To illustrate this, let's imagine that the sequence of actions in our example room is the following:
In this scenario, imagine that the following subscribe rules are POSTed
to Alice's /SubscribedTracks
just after she joins:
_10Rules=[_10 {"type": "include", "kind": "audio"},_10 {"type": "include", "track": "screen"},_10 {"type": "exclude", "publisher": "Carl"},_10 {"type": "include", "kind": "data"}_10]
Just after the POST, Alice's subscribed tracks are:
_10[] //The empty set
This happens because Alice is alone in the room and cannot subscribe to her own published tracks, no matter what the subscribe rules are.
Following the sequence above, now Bob connects to the Room publishing his 3 tracks. At that moment, given the declarative nature of subscribe rules, Alice's subscribed tracks are re-evaluated to be:
_10[MTB_A, MTB_S]
Observe the above rules avoid using SIDs in the filters, we can create rules affecting Alice's subscriptions to Bob's tracks even before Bob connects to the room.
Next Carl joins and publishes audio and video tracks. Given that the third rule excludes Carl's tracks, Alice's subscribed tracks stay the same:
_10[MTB_A, MTB_S]
After that, Carl publishes his Data Track. As the fourth rule is including all
tracks with kind equal to data
, Alice's subscribed tracks evolve to:
_10[MTB_A, MTB_S, MTC_D]
At the fifth step, Bob leaves the room. Alice's subscriptions will be modified to be:
_10[MTC_D]
Last, when Carl leaves, Alice's will no be subscribed to any track any longer.
_10[] //The empty set
When a participant joins a Group Room, Twilio automatically feeds a subscription
rule to that participant. We call it the default_rule
:
_10{"type": "include", "all": true}
This happens automatically and only once at the time the participant connects. Twilio does this for enforcing a default "subscribe-to-all" model. This means that, if no further rules are provided, participants will connect to all the published tracks, which is consistent with Group Rooms default behavior prior to the existence of the Track Subscription API.
Thanks to this, Twilio guarantees backwards compatibility of all Group Room applications. However, this has a drawback. To understand why, let's use an example. Imagine that a developer wants Carl to just publish to the room but not to subscribe to anything. In that case, the developer may POST the following to Carl's rules:
_10Rules=[{"type":"exclude", "all": true}]
Indeed, this will remove the default rule with a new one enforcing a "subscribe-to-none" model. However this POST can only be sent after Carl connects. Hence, there is a race condition between the default rule, which tries to subscribe Carl to all the tracks, and the POST that tries to remove all subscriptions. This may degrade Carl's experience with some annoying subscriptions that appear and disappear.
To avoid this, Twilio client SDK APIs allow to override the default rule
at connect
time. Section Overriding defaults below is devoted to
explain how.
Twilio Video SDKs allows overriding the "subscribe-to-all" default_rule
at connect time and replace it with a "subscribe-to-none" one:
_10{"type": "exclude", "all": true}
This is achieved through the automaticSubscription
parameter as the
following code snippets illustrate.
JavaScript SDK (v2.0.0-beta12+ required)
_10const { connect } = require('twilio-video');_10connect(token, {_10 automaticSubscription: false,_10 name: 'my-room'_10});
iOS SDK (v.2.10.0+ required)
_10let connectOptions = TVIConnectOptions(token: accessToken) { (builder) in_10 builder.isAutomaticSubscriptionEnabled = false_10 builder.roomName = "my-room"_10}_10self.room = TwilioVideo.connect(with: connectOptions, delegate: self)
Android SDK (v.4.1.0+ required)
Java
_10ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)_10 .enableAutomaticSubscription(false)_10 .roomName("my-room")_10 .build();_10_10room = Video.connect(context, connectOptions, roomListener);
Kotlin
_10val connectOptions = ConnectOptions.Builder(accessToken)_10 .enableAutomaticSubscription(false)_10 .roomName("my-room")_10 .build()_10_10room = Video.connect(context, connectOptions, roomListener)
Every time subscriptions change Twilio sends events to the corresponding participant SDK. Developers must manage such events as part of their client application logic. There are three types of events:
Event type | Event description |
---|---|
subscribed | Fired when the Participant starts receiving media from a newly subscribed Track. Handling this event typically consists on rendering the received media (e.g. attaching to a video tag, etc.) |
unsubscribed | Fired when the Participant unsubscribes from a previously subscribed Track. Handling this event typically consists on adapting the GUI to stop rendering the track media (e.g. detaching from a video tag, etc.) |
error | Fired when the Participant should have subscribed to a Track but could not do it. This happens, for example, when the Participant does not support codecs of Tracks included by her subscribe rules. Handling this event typically requires informing the end-user and, eventually, taking the appropriate actions for minimizing the error impact. |
The following code snippet illustrates how to manage subscribe events in Twilio Video JavaScript SDK:
_37_37const { connect } = require('twilio-video');_37_37function subscribed(track) {_37 console.log('Subscribed to RemoteTrack:', track.sid);_37 //Code for starting track rendering goes here._37}_37_37function unsubscribed(track) {_37 console.log('Unsubscribed to RemoteTrack:', track.sid);_37 //Code for stopping track rendering goes here._37}_37_37function subscriptionFailed(error, publication) {_37 console.log('Failed to subscribe to RemoteTrack ${publication.trackSid}:', error);_37 //Code for managing subscribe errors goes here._37}_37_37function listenToSubscriptionEvents(publication) {_37 publication.on('subscribed', subscribed);_37 publication.on('unsubscribed', unsubscribed);_37 publication.on('subscriptionFailed', subscriptionFailed);_37}_37_37function participantConnected(participant) {_37 // Listen to subscription events of already published Tracks._37 participant.tracks.forEach(listenToSubscriptionEvents);_37 // Listen to subscription events of Tracks that are published later._37 room.on('trackPublished', listenToSubscriptionEvents);_37}_37_37connect('$token', { name: 'my-room' }).then(room => {_37 // Listen to events from RemoteParticipants currently in the Room._37 room.participants.forEach(participantConnected);_37 // Listen to events from RemoteParticipants that will join the Room._37 room.on('participantConnected', participantConnected);_37});
The following code snippet illustrates how to manage subscribe events in Twilio Video iOS SDK. For the sake of simplicity, we have only considered subscription event from video tracks. Handlers for audio and data tracks are equivalent but using their corresponding data types.
_35let options = TVIConnectOptions(token: accessToken)_35room = TwilioVideo.connect(with: options, delegate: self)_35_35func didConnect(to room: TVIRoom) {_35 // Handle subscription events for connected Participants_35 for remoteParticipant in room.remoteParticipants {_35 remoteParticipant.delegate = self_35 }_35}_35_35func room(_ room: TVIRoom, participantDidConnect participant: TVIRemoteParticipant) {_35 participant.delegate = self_35}_35_35func subscribed(to videoTrack: TVIRemoteVideoTrack,_35 publication: TVIRemoteVideoTrackPublication,_35 for participant: TVIRemoteParticipant) {_35 print("Subscribed to video track: \(publication.trackName)")_35 //Code for starting track rendering goes here._35}_35_35func unsubscribed(from videoTrack: TVIRemoteVideoTrack,_35 publication: TVIRemoteVideoTrackPublication,_35 for participant: TVIRemoteParticipant) {_35 print("Unsubscribed from video track: \(publication.trackName)")_35 //Code for stopping track rendering goes here._35}_35_35func failedToSubscribe(toVideoTrack publication: TVIRemoteVideoTrackPublication,_35 error: Error,_35 for participant: TVIRemoteParticipant) {_35 let errorText = String(describing: error)_35 print("Failed to subscribe to: \(publication.trackName), error: \(errorText)")_35 //Code for managing subscribe errors goes here._35}
The following code snippet illustrates how to manage subscribe events in Twilio Video Android SDK. For the sake of simplicity, we have only considered subscription event from video tracks. Callbacks for audio and data tracks are similar but using their corresponding data types.
Java
_42ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken).build();_42_42Room room = Video.connect(context, connectOptions, this);_42_42@Override_42public void onConnected(@NonNull Room room) {_42 for (RemoteParticipant remoteParticipant : room.getRemoteParticipants()) {_42 remoteParticipant.setListener(this);_42 }_42}_42_42@Override_42public void onParticipantConnected(@NonNull Room room,_42 @NonNull RemoteParticipant remoteParticipant) {_42 remoteParticipant.setListener(this);_42}_42_42@Override_42public void onVideoTrackSubscribed(@NonNull RemoteParticipant remoteParticipant,_42 @NonNull RemoteVideoTrackPublication remoteVideoTrackPublication,_42 @NonNull RemoteVideoTrack remoteVideoTrack) {_42 Log.i("Listener", "Subscribed to video track: " + remoteVideoTrack.getName());_42 // Code for starting track rendering goes here_42}_42_42@Override_42public void onVideoTrackUnsubscribed(@NonNull RemoteParticipant remoteParticipant,_42 @NonNull RemoteVideoTrackPublication remoteVideoTrackPublication,_42 @NonNull RemoteVideoTrack remoteVideoTrack) {_42 Log.i("Listener", "Unsubscribed from video track: " + remoteVideoTrack.getName());_42 // Code for stopping track rendering goes here_42}_42_42@Override_42public void onVideoTrackSubscriptionFailed(@NonNull RemoteParticipant remoteParticipant,_42 @NonNull RemoteVideoTrackPublication remoteVideoTrackPublication,_42 @NonNull TwilioException twilioException) {_42 Log.e("Listener", "Failed to subscribe to: "_42 + remoteVideoTrackPublication.getTrackName() + ", error: " +_42 twilioException.getMessage());_42 // Code for managing subscribe errors goes here._42}
Kotlin
_36val connectOptions = ConnectOptions.Builder(accessToken).build()_36_36val room = Video.connect(context, connectOptions, this)_36_36override fun onConnected(room: Room) {_36 for (remoteParticipant in room.remoteParticipants) {_36 remoteParticipant.setListener(this)_36 }_36}_36_36override fun onParticipantConnected(room: Room,_36 remoteParticipant: RemoteParticipant) {_36 remoteParticipant.setListener(this)_36}_36_36override fun onVideoTrackSubscribed(remoteParticipant: RemoteParticipant,_36 remoteVideoTrackPublication: RemoteVideoTrackPublication,_36 remoteVideoTrack: RemoteVideoTrack) {_36 Log.i("Listener", "Subscribed to video track: ${remoteVideoTrack.name}")_36 // Code for starting track rendering goes here_36}_36_36override fun onVideoTrackUnsubscribed(remoteParticipant: RemoteParticipant,_36 remoteVideoTrackPublication: RemoteVideoTrackPublication,_36 remoteVideoTrack: RemoteVideoTrack) {_36 Log.i("Listener", "Unsubscribed from video track: ${remoteVideoTrack.name}")_36 // Code for stopping track rendering goes here_36}_36_36override fun onVideoTrackSubscriptionFailed(remoteParticipant: RemoteParticipant,_36 remoteVideoTrackPublication: RemoteVideoTrackPublication,_36 twilioException: TwilioException) {_36 Log.e("Listener", "Failed to subscribe to:" +_36 "${remoteVideoTrackPublication.trackName}, error: ${twilioException.message}")_36 // Code for managing subscribe errors goes here._36}
Video contact centers are gaining popularity as an evolution of voice ones. We use this use-case as an example on how to implement a Group Application with static subscribe rules: that is, rules that do change over time. A typical contact center video room may involve the following roles:
The Group Room communication topology for this use-case is:
Representation of a video contact center where an agent is in helping a customer while being at the same time whispered by a supervisor.
In these types of scenarios where there are clearly established roles and topologies, we recommend the following implementation approach:
agent-video
and the customer
audio track could be named
customer-audio
. The specific chosen names are not
relevant. The important point is to comply with the naming convention in all
the video calls.
Based on this recommendation, tracks published in this application will look like this:
Agent | Customer | Supervisor | |
---|---|---|---|
Audio Track | MTA_A agent-audio | MTC_A customer-audio | MTS_A whisperer-audio |
Video Track (cam) | MTA_C agent-video | MTC_C customer-video | |
Video Track (screen) | MTC_S customer-screen |
For the sake of simplicity, we assume the following:
MT
followed by the participant initial and by a
letter identifying the track nature (
_A
for audio,
_C
for webcam,
_S
for
screenshare).
Agents subscribe to all the tracks published by the rest of participants. Due to this, the default "subscribe-to-all" model is enough. Hence, the application developer does not need add any additional rule:
_10Use default (i.e. "subscribe-to-all").
Supervisors also subscribe to all the published tracks and the default rule is also enough for them.
_10Use default (i.e. "subscribe-to-all").
Customers should just subscribe to the agent tracks. We recommend to do it in two steps:
Step 1: override default rule with "subscribe-to-none"
This step avoids race conditions between the default "subscribe-to-all" rule and POST setting the appropriate subscribe rules. See section Overriding the Default Rule for further information.
Step 2: POST the appropriate subscribe rules
Use the following code snippet where we assume that:
SKXXXX:your_api_key_secret
RMXXXX
The example above relies on some a prior knowledge about track names and participant roles for setting the subscribe rules at connect time. However, this is not always possible as there might be use-cases where the number of participants, their roles and their communication topology may dynamically change. For example, imagine a collaboration application where participants have full freedom to select the tracks they want to subscribe to at runtime. In this context, imagine a participant named Adam who connects with the following preferences:
The way in which the application signals the different events is out of the scope of this document. However, concentrating only on Track Subscription API calls, this is a possible solution. Notice that we assume that:
SKXXXX:your_api_key_secret
.
RMXXXX
.
For executing this example the following is required:
SKXXXX:your_api_key_secret
)
RMXXXX
)
PAXXXX
)
For executing this example the following is required:
SKXXXX:your_api_key_secret
)
RMXXXX
)
PAXXXX
)
For executing this example the following is required:
SKXXXX:your_api_key_secret
)
RMXXXX
)
PAXXXX
)
MTXXXX
)
There are no current known issues.