Skip to main content
Version: 6.13.0

How to programmatically select a video track quality

This article describes how you can use the API to select a video track quality. If you select a specific quality, you overrule the ABR algorithm.

The VideoTrack API, which is a sub-API of the MediaTrack API, can be used to implement this functionality. Implementing this functionality is a common use-case for developers who want to build their own UI to toggle a specific video quality.

SDKs

Web SDKAndroid SDKiOS SDKtvOS SDKAndroid TV SDKChromecast SDK
YesYesYesYesYesYes

Code examples

The code examples below show how to implement selecting video track qualities across SDKs.

Web SDK

The Web SDK leverages the MediaTrack API.

// enable a specific video track quality
player.videoTracks[0].targetQuality =
player.videoTracks[0].qualities[indexOfRequestedVideoTrackQuality];

// do ABR on a set of qualities
player.videoTracks[0].targetQuality = [
player.videoTracks[0].qualities[indexOfRequestedVideoTrackQuality1],
player.videoTracks[0].qualities[indexOfRequestedVideoTrackQuality2]
];

// set to default ABR algorithm
player.videoTracks[0].targetQuality = null;
Android (TV) SDK

The Android SDK leverages the MediaTrack API.

// enable a specific video track quality
theoplayer.getPlayer().getVideoTracks().getItem(0).setTargetQuality(theoplayer.getPlayer().getVideoTracks().getItem(0).getQualities().getItem(indexOfRequestedVideoTrackQuality));

// do ABR on a set of qualities
ArrayList<VideoQuality> selectedVideoQualities = new ArrayList<>();
selectedVideoQualities.add(theoplayer.getPlayer().getVideoTracks().getItem(0).getQualities().getItem(0));
selectedVideoQualities.add(theoplayer.getPlayer().getVideoTracks().getItem(0).getQualities().getItem(1));
theoplayer.getPlayer().getVideoTracks().getItem(0).setTargetQualities(selectedVideoQualities); // ABR algorithm only executed to qualities belonging to selectedVideoQualities

// set to default ABR algorithm
theoplayer.getPlayer().getVideoTracks().getItem(0).setTargetQualities(Collections.emptyList());
iOS (/tvOS) SDK

The iOS SDK leverages the ABR API. The underlying AVFoundation stack, which THEOplayer has to use, brings along the technical limitation that you cannot select a specific video quality. Instead, you can set a maximum resolution or bitrate.

// set preferred peak bitrate
self.theoplayer.abr.preferredPeakBitRate = 200000

// self.theoplayer.abr.preferredPeakBitRate = nil // removes any bitrate limitation

// preferredMaximumResolution supported starting from iOS 11 and above
// self.theoplayer.abr.preferredMaximumResolution = CGSize(width: 1280, height: 720)
// self.theoplayer.abr.preferredMaximumResolution = CGSize.zero // removes any resolution limitation

Remarks