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.
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.
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 SDK | Track Priority API |
---|---|
JavaScript | 2.0.0+ |
Android | 5.8.0+ |
iOS | 3.4.0+ |
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+)
1//You can set the publisher track priority at publish time2const localTrackPublication = await room.localParticipant.publishTrack(localTrack, {3priority: 'high' //choose among 'high', 'standard' or 'low'4});5//The publisher Track priority can also be read.6assert.equal(localTrackPublication.priority, 'high');78//The publisher Track priority is propagated to the RemoteTrackPublication.9remoteParticipant.on('trackPublished', remoteTrackPublication => {10console.log(`RemoteTrackPublication with priority ${remoteTrackPublication.publishPriority}`);11});1213//You can also update the track priority of a published track14localTrackPublication.setPriority('low')1516//That change will fire an event in all subscribers indicating the updated priority17remoteTrackPublication.on('publishPriorityChanged', priority => {18console.log('The publisher has changed the priority this Track to "${priority}"');19assert.equal(remoteTrackPublication.publishPriority, priority);20});
Android SDK (Required v5.8.0+)
1// You can set the publisher track priority at publish time2LocalTrackPublicationOptions localTrackPublicationOptions = new LocalTrackPublicationOptions(TrackPriority.HIGH);3localParticipant.publishTrack(localVideoTrack, localTrackPublicationOptions);45// The publish priority is also represented in remote audio, video, and data track publications.6remoteVideoTrackPublication.getPublishPriority();78// You can also update the track priority of a published track9localVideoTrackPublication.setPriority(TrackPriority.STANDARD);1011// That change will result in a RemoteParticipant.Listener callback12@Override13public void onVideoTrackPublishPriorityChanged(14@NonNull final RemoteParticipant remoteParticipant,15@NonNull final RemoteVideoTrackPublication remoteVideoTrackPublication,16@NonNull final TrackPriority trackPriority) {17Log.d(TAG, "The publisher has changed the priority of this Track to " + trackPriority)18}
iOS SDK (Required v3.4.0+)
1// You can set the publisher track priority at publish time2let localVideoTrackPublicationOptions = LocalTrackPublicationOptions(priority: .high)3localParticipant.publishVideoTrack(localVideoTrack, publicationOptions: localVideoTrackPublicationOptions);45// The publish priority is also represented in remote audio, video, and data track publications.6let publishPriority = remoteVideoTrackPublication.publishPriority78// You can also update the track priority of a published track9localVideoTrackPublication.priority = .high1011// That change will result in a RemoteParticipantDelegate callback12extension ViewController : RemoteParticipantDelegate {13func remoteParticipantDidChangeAudioTrackPublishPriority(participant: RemoteParticipant,14priority: Track.Priority,15publication: RemoteAudioTrackPublication) {}16}
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+)
1//You can set the publisher track priority at the publisher2const localTrackPublication = await room.localParticipant.publishTrack(localTrack, {3priority: 'low' //choose among 'high', 'standard' or 'low'4});56//That priority is propagated to all subscribers7assert.equal(remoteTrackPublication.priority, 'low');89//Subscribers can now override the publisher side priority on the remote Track10remoteTrack.setPriority('high')1112//This subscriber Track priority only affects that specific subscriber13assert.equal(remoteTrack.priority,'high')14//The overridden priority is still visible15assert.equal(remoteTrackPublication.priority, 'low');1617//We can revert back to the publisher priority18remoteTrack.setPriority(null)19assert.equal(remoteTrack.priority, null)20assert.equal(remoteTrackPublication.priority, 'low');
Android SDK (Required v5.8.0+)
1// You can set the publisher track priority at publish time2LocalTrackPublicationOptions localTrackPublicationOptions = new LocalTrackPublicationOptions(TrackPriority.LOW);3localParticipant.publishTrack(localVideoTrack, localTrackPublicationOptions);45// That priority is propagated to all subscribers6remoteVideoTrackPublication.getPublishPriority();78// Subscribers can now override the publisher side priority on the remote Track9remoteVideoTrack.setPriority(TrackPriority.HIGH);1011// We can revert back to the publisher priority12remoteVideoTrack.setPriority(null);
iOS SDK (Required v3.4.0)
1// You can set the publisher track priority at publish time2let localVideoTrackPublicationOptions = LocalTrackPublicationOptions(priority: .low)3localParticipant.publishVideoTrack(localVideoTrack, publicationOptions: localVideoTrackPublicationOptions);45// That priority is propagated to all subscribers6let publishPriority = remoteVideoTrackPublication.publishPriority78// Subscribers can now override the publisher side priority on the remote Track9remoteVideoTrack.priority = .high1011// We can revert back to the publisher priority12remoteVideoTrack.priority = nil
Developers can use publisher and subscriber Track priorities for setting the Track relevance. The difference among both are subtle but relevant:
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.
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.