Track Subscriptions

Overview

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:

• Define a Participant's Track subscribe rules.
• Enumerate a Participant's subscribed Tracks.

The Track Subscription API is only available in Group Rooms. Check the SDK Compatibility section below for further compatibility information.

Contents

• SDK Compatibility
• Communication Topologies in Group Rooms
• URI Schemes
• The SubscribedTrack Instance Resource
  • Resource Properties
  • Get a Subscribed Track (HTTP GET)
• The SubscribedTracks List Resource
  • Get a Participant's Subscribed Track List (HTTP GET)
• The SubscribeRules Resource
  • Resource Properties
  • Get a Participant's Subscribe Rules (HTTP GET)
  • Modify a Participant's Subscribe Rules (HTTP POST)
• Understanding Subscribe Rules
  • Specifying Subscribe Rules
  • Subscribe Rules Semantics
• Managing Track Subscriptions with Twilio Client SDKs
  • Overriding the Default Rule
  • Managing SDK Subscribe Events
• Examples
  • Video Contact Center: Setting Static Subscribe Rules
  • Collaborative Video: Updating Subscribe Rules Dynamically
  • Fetching a Participant's Subscribe Rules
  • Fetching a Participant's Subscribed Track List
  • Fetching a Participant's Subscribed Track Instance
• Known Issues

SDK Compatibility

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:

For further information on how to manage client side subscription events and errors check the Managing Track Subscriptions with Twilio Client SDKs section below.

Communication Topologies in Group Rooms

Twilio Group Rooms media communications work though a publish/subscribe model that relies on the following principles:

• When a participant publishes an audio, video or data track such track is assigned a SID and the client SDK starts sending the media bitstream to Twilio.
• When a participant subscribes to a track, Twilio clones and forwards the track bitstream to that participant.

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:

• Subscribe-to-all: each participant subscribes to all the published tracks. This is the default in Group Rooms. It is commonly used in collaboration applications where participants communicate with all the rest.
• Subscribe-to-one: participants subscribe only to a presenter's tracks. This is often used in single-presenter webinars where viewers cannot contribute to the presentation.
• Subscribe-to-some: where participants subscribe to the tracks published by a set of speakers. It is common in collaborative presentations or in presentations where viewers can temporarily become presenters.
• Whisperers: some participants (i.e. the whisperers) subscribe to all, but can only be listened/viewed by some. Whisperers are common to train and supervise video contact center agents.
• etc.

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.

URI Schemes

For the sake of simplicity, we define the Participant Resource URI as:

PARTICIPANT_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

The SubscribedTrack Instance Resource

A SubscribedTrack instance is a Participant's resource that represents the subscription such Participant has for a given Track.

Resource URI

PARTICIPANT_URI/SubscribedTracks/{TrackSid}/

Resource Properties

This resource has the following properties:

Get a Subscribed Track (HTTP GET)

Retrieves the SubscribedTrack instance resource associated to the specified Participant and TrackSid.

Other HTTP Methods

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

The SubscribedTracks list resource represents the subscriptions of a given Participant in a Group Room.

Resource URI

PARTICIPANT_URI/SubscribedTracks

Get a Participant's Subscribed Track List (HTTP GET)

Retrieves the list of subscribed tracks associated to the specified Participant with paging data.

Other HTTP Methods

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

The SubscribeRules resource is a singleton resource that represents the subscribe rules that are enforced on a given Participant.

Resource URI

PARTICIPANT_URI/SubscribeRules

Resource Properties

This resource has the following properties:

Get a Participant's Subscribe Rules (HTTP GET)

Returns the subscribe rules of the specified Participant.

Modify a Participant's Subscribe Rules (HTTP POST)

Updates the subscribe rules of the specified Participant. The following parameters are supported:

For a deeper understanding on how subscribe rules work, see the Understanding Subscribe Rules section below.

Other HTTP Methods

This resource does not support PUT or DELETE.

Understanding Subscribe Rules

Subscribe rules can be set:

• At Participant connect time. In this case they apply since the very beginning overriding the default "subscribe-to-all" policy. See section Overriding the Default Rule for further information.
• After the Participant is connected. In this case, they can modify subscriptions dynamically. See section Modify a Participant's Subscribe Rules (HTTP POST) for further information.

Specifying Subscribe Rules

A subscription rule instance is a JSON with the following structure:

{"type": rule_type, filter_name: filter_value, filter_name: filter_value, ...}

Where:

Based on this, subscribe rules are specified as a JSON array containing up to 20 rules. For example:

Rules = [
  {"type": "include", "all": true},                              //rule_1
  {"type": "exclude", "kind": "video"},                          //rule_2
  {"type": "include", "publisher": "Bob", "track": "screen"},    //rule_3
  {"type": "include", "track": "MTXXXXXXXXXXXXXXXXXXXXXXXXXXX"}, //rule_4
  ...
  rule_20
]

Remember that valid subscription rules comply with the following:

• The maximum number of rules that can be specified is 20.
• An empty set of rules (i.e. []) is not allowed.
• A rule containing the "all" filter must have a value of true. Notice that this means false is not allowed.
• A rule having an “all” filter cannot have any other filters.
• A rule must contain a "type" field.
• If the "kind" filter is used, its value must be one of audio, video or data.
• A rule cannot contain several times the same filter (e.g. specify two different kinds or publishers, 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:

{
  "code": 53215,
  "message": "Invalid Subscribe Rule(s)",
  "more_info": "https://www.twilio.com/docs/errors/53215",
  "status": 400
}

For example, the following requests are invalid:

//Invalid because it's using an empty set
Rules = []

//Invalid because it uses false as value of "all"
Rules = [
  {"type":"include", "all": false}
]

//Invalid because it specifies a non supported kind
Rules = [
  {"type": "include", "all": true},
  {"type": "exclude", "kind": "wideo"}
]

//Invalid because it repeats the "kind" filter twice
Rules = [
  {"type": "include", "kind": "audio", "kind": "data"},
]

//Invalid because an "all" filter is not compatible with any other filter
Rules = [
  {"type": "include", "all": "true", "kind": "data"},
]

Subscribe Rules Semantics

SubscribeRules are enforced by Twilio using four main principles:

1. Subscribe Rules semantics are based on Algebra of Sets.
2. Subscribe Rules are stateless.
3. Subscribe Rules are enforced declaratively.
4. Subscribe Rules are initialized with a “subscribe-to-all” rule.

1. Subscribe Rules Semantics are based on Algebra of Sets

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:

• The SetST is initialized to the empty set.
• The subscribe rules are applied to the SetST using Algebra of Sets in the order provided such that:
• For any include rule we perform the union of the SetST with the set of tracks matching the rule filters.
• For any exclude rule we perform the set difference of the SetST with the set of tracks matching by the rule filters.
• Participants are subscribed to all the tracks remaining in SetST after all the rules have been evaluated.

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:

Notice that, for the sake of simplicity, we have assumed the following conventions:

• Track SIDs have the prefix 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).
• Track names are specified under their corresponding SIDs.

In this context, imagine that we POST the following rules to Alice's /SubscribeRules resource:

Rules = [
  {"type": "include", "all": true},                              
  {"type": "exclude", "kind": "video"},                          
  {"type": "include", "publisher": "Bob", "track": "screen"}
]

Then, the algorithm will compute the tracks Alice should subscribe to in the following way:

Still assuming the above specified Group Room scenario, consider the following examples that might be interesting to understand how the subscription algorithm works:

Example: Subscribe-to-all

When POSTing to Alice's subscribe rules the following:

Rules = [
  {"type": "include", "all": true}
]

Alice will subscribe to all the tracks (except for her own). Hence, the SetST will be:

[MTB_A,MTB_C,MTB_S,MTC_A,MTC_C,MTC_D]

This happens because:

• The SetST is initialized to the empty set []
• The rule includes all the published tracks (except for her own)

Example: Subscribe-to-none

When POSTing to Alice's subscribe rules the following:

Rules = [
  {"type": "exclude", "all": true}
]

Alice will subscribe to no tracks:

[] //The empty set

This happens because:

• The SetST is initialized to the empty set []
• The rules excludes all the tracks from the empty set, which is still the empty set.

Example: Single exclude rules

When POSTing to Alice’s subscribe rules the following:

Rules = [
  {"type": "exclude", "kind": "video"}
]

Alice’s subscribed tracks will be:

[] //The empty set

This happens because:

• The SetST is initialized to the empty set [].
• The single rule excludes the video tracks from the empty set, which is still an empty set.

Example: include own tracks

When POSTing to Alice’s subscribe rules the following:

Rules = [
    {"type": "include", "track": "alice-audio"}
]

Alice’s subscribed tracks will be:

[] //The empty set

This happens because:

• The SetST is initialized to the empty set [].
• Including a participant’s own tracks will have no effect as rule filters never consider own published tracks. Hence the rule filter only matches the empty set and the union of two empty sets is still the empty set.

Example: Including tracks by name

When POSTing to Alice’s subscribe rules the following:

Rules = [
  {"type": "include", "track": "screen"}
]

Alice’s subscribed tracks will be:

[MTB_S] //Bob's screen track

This happens because:

• The SetST is initialized to the empty set [].
• The rule includes all tracks named 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.

Example: Working with multiple filters

When POSTing to Carl’s subscribe rules the following:

Rules = [
  {"type": "include", "all": true},
  {"type": "exclude", "publisher": "PTB", "kind": "audio"},
  {"type": "exclude", "kind": "video", "track": "screen"}
]

Carl’s subscribed tracks will be:

[MTA_A, MTA_C, MTB_C]

This happens because:

• The SetST is initialized to the empty set [].
• The first rule includes all tracks, except Carl’s ones: [MTA_A,MTA_C,MTA_S,MTB_A,MTB_C,MTB_S]
• Given that filters intersect (i.e. you can read them as being connected through a logical AND), the second rule excludes all audio tracks published by Bob (we assume PTB is Bob's SID). That is, MTB_A is excluded.
• The third rule further excludes all video tracks named screen. Hence, MTA_S and MTB_S are also excluded.

Example: Considering rule order

When POSTing to Alice’s subscribe rules the following:

Rules = [
  {"type": "include", "kind": "data"},
  {"type": "exclude", "publisher": "Carl"}
]

Alice’s subscribed tracks will be:

[] //The empty set

This happens because:

• The SetST is initialized to the empty set [].
• The first rule includes MTC_D
• The second rule excludes all of Carl’s tracks, which removes MTC_D and results in the empty set.

However, when POSTing

Rules = [
  {"type": "exclude", "publisher": "Carl"},  
  {"type": "include", "kind": "data"}
]

Alice’s subscribed tracks will be:

[MTC_D]

This happens because:

• The SetST is initialized to the empty set [].
• The first excludes Carl’s tracks from the empty set, which is still the empty set.
• The third rule adds MTC_D to the SetST.

2. Subscribe Rules are stateless

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:

Rules = [
  {"type": "include", "kind": "audio"}
]

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:

Rules = [
  {"type": "include", "kind": "audio"},
  {"type": "include", "track": "MTA_S"}
]

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:

Rules = [
  {"type": "include", "kind": "audio"},
  {"type": "include", "track": "MTB_C"}
]

As you can see, each POST “resets” the subscribe rules making it necessary to specify what should be included and excluded at all requests.

3. Subscribe Rules are enforced declaratively

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:

1. First Alice joins the room and publishes her 3 tracks.
2. Second Bob joins publishing his 3 tracks
3. Third Carl joins also publishing his audio and video tracks.
4. Fourth Carl publishes his data track
5. Then Bob leaves unpublishing his tracks.
6. Finally Carl also leaves.

In this scenario, imagine that the following subscribe rules are POSTed to Alice’s /SubscribedTracks just after she joins:

Rules=[
  {"type": "include", "kind": "audio"},
  {"type": "include", "track": "screen"},
  {"type": "exclude", "publisher": "Carl"},
  {"type": "include", "kind": "data"}
]

Just after the POST, Alice’s subscribed tracks are:

[] //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:

[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:

[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:

[MTB_A, MTB_S, MTC_D]

At the fifth step, Bob leaves the room. Alice’s subscriptions will be modified to be:

[MTC_D]

Last, when Carl leaves, Alice’s will no be subscribed to any track any longer.

[] //The empty set

4. Subscribe Rules are initialized with a “subscribe-to-all” rule

When a participant joins a Group Room, Twilio automatically feeds a subscription rule to that participant. We call it the default_rule:

{"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:

Rules=[{"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.

Managing Track Subscriptions with Twilio Client SDKs

Overriding the Default Rule

Twilio Video SDKs allows overriding the "subscribe-to-all" default_rule at connect time and replace it with a "subscribe-to-none" one:

{"type": "exclude", "all": true}

This is achieved through the automaticSubscription parameter as the following code snippets illustrate.

JavaScript SDK (v2.0.0-beta12+ required)

const { connect } = require('twilio-video');
connect(token, {
  automaticSubscription: false,
  name: 'my-room'
});

iOS SDK (v.2.10.0+ required)

let connectOptions = TVIConnectOptions(token: accessToken) { (builder) in
    builder.isAutomaticSubscriptionEnabled = false
    builder.roomName = "my-room"
}
self.room = TwilioVideo.connect(with: connectOptions, delegate: self)

Android SDK (v.4.1.0+ required)

Java

ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)
        .enableAutomaticSubscription(false)
        .roomName("my-room")
        .build();

room = Video.connect(context, connectOptions, roomListener);

Kotlin

val connectOptions = ConnectOptions.Builder(accessToken)
        .enableAutomaticSubscription(false)
        .roomName("my-room")
        .build()

room = Video.connect(context, connectOptions, roomListener)

Managing SDK Subscribe Events

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:

Managing Subscribe Events in JavaScript (v.1.18.0+ required)

The following code snippet illustrates how to manage subscribe events in Twilio Video JavaScript SDK:

const { connect } = require('twilio-video');

function subscribed(track) {
  console.log('Subscribed to RemoteTrack:', track.sid);
  //Code for starting track rendering goes here.
}

function unsubscribed(track) {
  console.log('Unsubscribed to RemoteTrack:', track.sid);
  //Code for stopping track rendering goes here.
}

function subscriptionFailed(error, publication) {
  console.log('Failed to subscribe to RemoteTrack ${publication.trackSid}:', error);
  //Code for managing subscribe errors goes here.
}

function listenToSubscriptionEvents(publication) {
  publication.on('subscribed', subscribed);
  publication.on('unsubscribed', unsubscribed);  
  publication.on('subscriptionFailed', subscriptionFailed);
}

function participantConnected(participant) {
  // Listen to subscription events of already published Tracks.
  participant.tracks.forEach(listenToSubscriptionEvents);
  // Listen to subscription events of Tracks that are published later.
  room.on('trackPublished', listenToSubscriptionEvents);
}

connect('$token', { name: 'my-room' }).then(room => {
  // Listen to events from RemoteParticipants currently in the Room.
  room.participants.forEach(participantConnected);
  // Listen to  events from RemoteParticipants that will join the Room.
  room.on('participantConnected', participantConnected);
});

Managing Subscribe Events in iOS (v.2.4.0+ required)

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.

let options = TVIConnectOptions(token: accessToken)
room = TwilioVideo.connect(with: options, delegate: self)

func didConnect(to room: TVIRoom) {
    // Handle subscription events for connected Participants
    for remoteParticipant in room.remoteParticipants {
        remoteParticipant.delegate = self
    }
}

func room(_ room: TVIRoom, participantDidConnect participant: TVIRemoteParticipant) {
    participant.delegate = self
}

func subscribed(to videoTrack: TVIRemoteVideoTrack,
                  publication: TVIRemoteVideoTrackPublication,
              for participant: TVIRemoteParticipant) {
    print("Subscribed to video track: \(publication.trackName)")
    //Code for starting track rendering goes here.
}

func unsubscribed(from videoTrack: TVIRemoteVideoTrack,
                  publication: TVIRemoteVideoTrackPublication,
                  for participant: TVIRemoteParticipant) {
    print("Unsubscribed from video track: \(publication.trackName)")
    //Code for stopping track rendering goes here.
}

func failedToSubscribe(toVideoTrack publication: TVIRemoteVideoTrackPublication,
                       error: Error,
                       for participant: TVIRemoteParticipant) {
    let errorText = String(describing: error)
    print("Failed to subscribe to: \(publication.trackName), error: \(errorText)")
    //Code for managing subscribe errors goes here.
}

Managing Subscribe Events in Android (v.3.0.0+ required)

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

ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken).build();

Room room = Video.connect(context, connectOptions, this);

@Override
public void onConnected(@NonNull Room room) {
    for (RemoteParticipant remoteParticipant : room.getRemoteParticipants()) {
        remoteParticipant.setListener(this);
    }
}

@Override
public void onParticipantConnected(@NonNull Room room,
                                    @NonNull RemoteParticipant remoteParticipant) {
    remoteParticipant.setListener(this);
}

@Override
public void onVideoTrackSubscribed(@NonNull RemoteParticipant remoteParticipant,
                                    @NonNull RemoteVideoTrackPublication remoteVideoTrackPublication,
                                    @NonNull RemoteVideoTrack remoteVideoTrack) {
    Log.i("Listener", "Subscribed to video track: " + remoteVideoTrack.getName());
    // Code for starting track rendering goes here
}

@Override
public void onVideoTrackUnsubscribed(@NonNull RemoteParticipant remoteParticipant,
                                      @NonNull RemoteVideoTrackPublication remoteVideoTrackPublication,
                                      @NonNull RemoteVideoTrack remoteVideoTrack) {
    Log.i("Listener", "Unsubscribed from video track: " + remoteVideoTrack.getName());
    // Code for stopping track rendering goes here
}

@Override
public void onVideoTrackSubscriptionFailed(@NonNull RemoteParticipant remoteParticipant,
                                            @NonNull RemoteVideoTrackPublication remoteVideoTrackPublication,
                                            @NonNull TwilioException twilioException) {
    Log.e("Listener", "Failed to subscribe to: "
            + remoteVideoTrackPublication.getTrackName() + ", error: " +
            twilioException.getMessage());
    // Code for managing subscribe errors goes here.
}

Kotlin

val connectOptions = ConnectOptions.Builder(accessToken).build()

val room = Video.connect(context, connectOptions, this)

override fun onConnected(room: Room) {
    for (remoteParticipant in room.remoteParticipants) {
        remoteParticipant.setListener(this)
    }
}

override fun onParticipantConnected(room: Room,
                                    remoteParticipant: RemoteParticipant) {
    remoteParticipant.setListener(this)
}

override fun onVideoTrackSubscribed(remoteParticipant: RemoteParticipant,
                                    remoteVideoTrackPublication: RemoteVideoTrackPublication,
                                    remoteVideoTrack: RemoteVideoTrack) {
    Log.i("Listener", "Subscribed to video track: ${remoteVideoTrack.name}")
    // Code for starting track rendering goes here
}

override fun onVideoTrackUnsubscribed(remoteParticipant: RemoteParticipant,
                                      remoteVideoTrackPublication: RemoteVideoTrackPublication,
                                      remoteVideoTrack: RemoteVideoTrack) {
    Log.i("Listener", "Unsubscribed from video track: ${remoteVideoTrack.name}")
    // Code for stopping track rendering goes here
}

override fun onVideoTrackSubscriptionFailed(remoteParticipant: RemoteParticipant,
                                            remoteVideoTrackPublication: RemoteVideoTrackPublication,
                                            twilioException: TwilioException) {
    Log.e("Listener", "Failed to subscribe to:" +
            "${remoteVideoTrackPublication.trackName}, error: ${twilioException.message}")
    // Code for managing subscribe errors goes here.
}

Examples

Video Contact Center: Setting Static Subscribe Rules

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:

• Agent, who assists contact center customers.
• Customer, who video calls asking for support.
• Supervisor, who trains Agents. In traditional voice contact centers this type of role is sometimes called a “whisperer”: a participant who listens to all but can only be listened by the agent.

The Group Room communication topology for this use-case is:

• The agent should subscribe to all tracks both the one of customer and the ones of the supervisor.
• The customer should subscribe to the agent's audio and video. However, supervisor should be hidden for her.
• The supervisor should subscribe to all the tracks.

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:

• Developers should follow a fixed naming convention for their tracks. For example, the agent webcam track could be named 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.
• The application developer can use the above-mentioned naming convention for setting the appropriate subscribe rules at connect time.

Based on this recommendation, tracks published in this application will look like this:

For the sake of simplicity, we assume the following:

• Track SIDs have the prefix MT followed by the participant initial and by a letter identifying the track nature (_A for audio, _C for webcam, _S for screenshare).
• Track names are specified under their corresponding SIDs. Due to be above-mentioned naming convention, all room instances keep those track names.

Agent's Subscribe Rules

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:

Use default (i.e. "subscribe-to-all").

Supervisor's Subscribe Rules

Supervisors also subscribe to all the published tracks and the default rule is also enough for them.

Use default (i.e. "subscribe-to-all").

Customer's Subscribe Rules

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:

• The Twilio Access Key SID and Secret are SKXXXX:your_api_key_secret
• The Room SID is RMXXXX

Collaborative Video: Updating Subscribe Rules Dynamically

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:

1. At connect time Adam wants to receive all the tracks (default behavior).
2. After a while, Adam notices his bandwidth consumption is too high and decides to unsubscribe from all video tracks.
3. Later, a video screenshare track with SID MTXXXX is published to the room and Adam subscribes to it.
4. John, another participant, is in a noisy place and his audio track is annoying. Adam decides to unsubscribe from it.

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:

• The Twilio credentials are SKXXXX:your_api_key_secret.
• The Room SID is RMXXXX.

Fetching a Participant's Subscribe Rules

For executing this example the following is required:

• The Twilio Access Key SID and Secret (SKXXXX:your_api_key_secret)
• The Room SID or name (RMXXXX)
• The Participant SID or identity (PAXXXX)

Fetching a Participant's Subscribed Track List

For executing this example the following is required:

• The Twilio Access Key SID and Secret (SKXXXX:your_api_key_secret)
• The Room SID or name (RMXXXX)
• The Participant SID or identity (PAXXXX)

Fetching a Participant's Subscribed Track Instance

For executing this example the following is required:

• The Twilio Access Key SID and Secret (SKXXXX:your_api_key_secret)
• The Room SID or name (RMXXXX)
• The Participant SID or identity (PAXXXX)
• The subscribed Track SID (MTXXXX)

Known Issues

There are no current known issues.