Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Using the Track Priority API


(warning)

Warning

This documentation 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, 2026(link takes you to an external page).

We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.


Overview

overview page anchor

Not all video tracks are equal. For example, in a webinar application the screen share track is more important than the webcams, while in a video collaboration service the dominant speaker has more relevance than the rest of the participants.

To account for this, Twilio has created the Track Priority API, which makes it possible to set the priority of Tracks. The priority of a Track can be set to any of the following values:

  • high
  • standard
  • low

Track priorities can be understood as the relative relevance of Tracks. This means that, from the Twilio perspective, any Track marked as high will be more important than any standard Track, which in turn will be more relevant that any low priority Track.

Currently, only the Network Bandwidth Profile API consumes Track priorities to determine which Tracks are more relevant from the bandwidth allocation perspective. In the future Twilio may use Track priorities for other further purposes.



The Track Priority API is only available in Group Rooms (including Small Group Rooms). The following table illustrates current support:

Twilio Video SDKTrack Priority API
JavaScript2.0.0+
Android5.8.0+
iOS3.4.0+

Publisher Track Priorities

publisher-track-priorities page anchor

The publisher Track priority is the priority given to a track by its publisher. By default, the publisher Track priority is standard. However, developers can specify a different priority at publish time. Once set, the publisher Track priority can be read both at the local and remote Track publications. Developers can also update the publisher Track priority using the setPriority primitive. In that case, all remote subscribers will be notified through an event. The following code snippets illustrate how this works:

JavaScript SDK (Required v2.0.0+)


_20
//You can set the publisher track priority at publish time
_20
const localTrackPublication = await room.localParticipant.publishTrack(localTrack, {
_20
priority: 'high' //choose among 'high', 'standard' or 'low'
_20
});
_20
//The publisher Track priority can also be read.
_20
assert.equal(localTrackPublication.priority, 'high');
_20
_20
//The publisher Track priority is propagated to the RemoteTrackPublication.
_20
remoteParticipant.on('trackPublished', remoteTrackPublication => {
_20
console.log(`RemoteTrackPublication with priority ${remoteTrackPublication.publishPriority}`);
_20
});
_20
_20
//You can also update the track priority of a published track
_20
localTrackPublication.setPriority('low')
_20
_20
//That change will fire an event in all subscribers indicating the updated priority
_20
remoteTrackPublication.on('publishPriorityChanged', priority => {
_20
console.log('The publisher has changed the priority this Track to "${priority}"');
_20
assert.equal(remoteTrackPublication.publishPriority, priority);
_20
});

Android SDK (Required v5.8.0+)


_18
// You can set the publisher track priority at publish time
_18
LocalTrackPublicationOptions localTrackPublicationOptions = new LocalTrackPublicationOptions(TrackPriority.HIGH);
_18
localParticipant.publishTrack(localVideoTrack, localTrackPublicationOptions);
_18
_18
// The publish priority is also represented in remote audio, video, and data track publications.
_18
remoteVideoTrackPublication.getPublishPriority();
_18
_18
// You can also update the track priority of a published track
_18
localVideoTrackPublication.setPriority(TrackPriority.STANDARD);
_18
_18
// That change will result in a RemoteParticipant.Listener callback
_18
@Override
_18
public void onVideoTrackPublishPriorityChanged(
_18
@NonNull final RemoteParticipant remoteParticipant,
_18
@NonNull final RemoteVideoTrackPublication remoteVideoTrackPublication,
_18
@NonNull final TrackPriority trackPriority) {
_18
Log.d(TAG, "The publisher has changed the priority of this Track to " + trackPriority)
_18
}

iOS SDK (Required v3.4.0+)


_16
// You can set the publisher track priority at publish time
_16
let localVideoTrackPublicationOptions = LocalTrackPublicationOptions(priority: .high)
_16
localParticipant.publishVideoTrack(localVideoTrack, publicationOptions: localVideoTrackPublicationOptions);
_16
_16
// The publish priority is also represented in remote audio, video, and data track publications.
_16
let publishPriority = remoteVideoTrackPublication.publishPriority
_16
_16
// You can also update the track priority of a published track
_16
localVideoTrackPublication.priority = .high
_16
_16
// That change will result in a RemoteParticipantDelegate callback
_16
extension ViewController : RemoteParticipantDelegate {
_16
func remoteParticipantDidChangeAudioTrackPublishPriority(participant: RemoteParticipant,
_16
priority: Track.Priority,
_16
publication: RemoteAudioTrackPublication) {}
_16
}


Subscriber Track Priorities

subscriber-track-priorities page anchor

As stated above, the publisher Track priority propagates to all remote subscribers. However, sometimes, there are use-cases where subscribers need to set their very specific priorities. To deal with this in a Group Room, we have introduced subscriber Track priorities: a mechanism that allows a subscriber to override the publisher Track priority. The following code snippets illustrate how this works:

JavaScript SDK (Required v2.0.0+)


_20
//You can set the publisher track priority at the publisher
_20
const localTrackPublication = await room.localParticipant.publishTrack(localTrack, {
_20
priority: 'low' //choose among 'high', 'standard' or 'low'
_20
});
_20
_20
//That priority is propagated to all subscribers
_20
assert.equal(remoteTrackPublication.priority, 'low');
_20
_20
//Subscribers can now override the publisher side priority on the remote Track
_20
remoteTrack.setPriority('high')
_20
_20
//This subscriber Track priority only affects that specific subscriber
_20
assert.equal(remoteTrack.priority,'high')
_20
//The overridden priority is still visible
_20
assert.equal(remoteTrackPublication.priority, 'low');
_20
_20
//We can revert back to the publisher priority
_20
remoteTrack.setPriority(null)
_20
assert.equal(remoteTrack.priority, null)
_20
assert.equal(remoteTrackPublication.priority, 'low');

Android SDK (Required v5.8.0+)


_12
// You can set the publisher track priority at publish time
_12
LocalTrackPublicationOptions localTrackPublicationOptions = new LocalTrackPublicationOptions(TrackPriority.LOW);
_12
localParticipant.publishTrack(localVideoTrack, localTrackPublicationOptions);
_12
_12
// That priority is propagated to all subscribers
_12
remoteVideoTrackPublication.getPublishPriority();
_12
_12
// Subscribers can now override the publisher side priority on the remote Track
_12
remoteVideoTrack.setPriority(TrackPriority.HIGH);
_12
_12
// We can revert back to the publisher priority
_12
remoteVideoTrack.setPriority(null);

iOS SDK (Required v3.4.0)


_12
// You can set the publisher track priority at publish time
_12
let localVideoTrackPublicationOptions = LocalTrackPublicationOptions(priority: .low)
_12
localParticipant.publishVideoTrack(localVideoTrack, publicationOptions: localVideoTrackPublicationOptions);
_12
_12
// That priority is propagated to all subscribers
_12
let publishPriority = remoteVideoTrackPublication.publishPriority
_12
_12
// Subscribers can now override the publisher side priority on the remote Track
_12
remoteVideoTrack.priority = .high
_12
_12
// We can revert back to the publisher priority
_12
remoteVideoTrack.priority = nil


Using Publisher and Subscriber Track Priorities

using-priorities page anchor

Developers can use publisher and subscriber Track priorities for setting the Track relevance. The difference among both are subtle but relevant:

  • Publisher Track priorities are designed to set the relevance of a track "for all the Room subscribers". For example, in a collaboration application a screenshare Track may be set to publisher Track priority high while all the webcams may be set to low . That would make the screen share to be (by default) much more relevant than the webcams for all the Participants.
  • Subscriber Track priorities are designed to modify the relevance of a track "for a specific subscriber". In the above mentioned application, a specific subscriber may be more interested on seeing the reaction of another participant to the presentation rather than on the screen share. In that case, developers can override the publisher Track priority for that specific subscriber. For example, when the end-user clicks on the webcam of her interest, the screen share can be set a subscriber Track priority low and the webcam a subscriber Track priority high . This would allow that end-user to enhance on her UI that specific webcam.

Hence, publisher Track priorities are useful for specifying the desired default relevance of tracks for an application, while subscriber Track priorities are a mechanism developers can use to customize priorities to the needs of specific end-users.


Rate this page: