Track Selection
Track types
Each playback can have three types of tracks - AUDIO
, VIDEO
and TEXT
. These different track types are denoted using TrackVariantInfo.Type
.
//VIDEO Track type
val videoTrackType = TrackVariantInfo.Type.VIDEO
//AUDIO Track Type
val audioTrackType = TrackVariantInfo.Type.AUDIO
//TEXT Track type
val textTrackType = TrackVariantInfo.Type.TEXT
Tracks
Each elementary track of each type related to the playback is represented as a TrackVariantInfo
object. Each track is differentiated using bitrate, language, mimetype, etc. The metadata of the track can be obtained using the various properties of this object.
Property Name | Type | Description |
---|---|---|
id | String | The unique identifier of the track. |
type | Type | The type of the track. |
languageCode | String | Either a valid 2-letter ISO 639-1 language code or a normalized language code mapped to its macro-language equivalent by ExoPlayer (e.g., a 5-letter code). Note: ExoPlayer normalize language codes to ISO 639-2/T or ISO 639-2/B codes, but certain 3-letter codes are mapped to their broader macro-language equivalents. Example: Chinese (zh) Variants: cmn → zh-cmn, hsn → zh-hsn |
mimeType | String | Mime Type of the option (video/mp4, video/webm, audio/mp4, audio/eac3, text/ttml, text/webvtt etc.) |
bitRate | Int | The bitrate of the track (-1 if not applicable) |
channelCount | Int | The number of channels of the track (-1 if not applicable) |
codecs | String | The codecs used by the track (mp4a.40.2, avc1.64000D, etc.) |
sampleRate | Int | The sample rate of the track (-1 if not applicable) |
width | Int | The width of the track variant. Applicable only for video tracks. |
height | Int | The height of the track variant. Applicable only for video tracks. |
iso3LanguageCode | String | The iso3 standard language code for audio/text tracks. This code follows the 3-letter format defined by the ISO 639-2 or ISO 639-3 standard. |
Available Tracks
All the available tracks of each type of track can be obtained using the availableTrackVariants
API on the player.
This API returns an Array
of TrackVariantInfo
objects.
// get all video tracks
val availableVideoTracks = player.availableTrackVariants(TrackVariantInfo.Type.VIDEO)
//get all audio tracks
val availableAudioTracks = player.availableTrackVariants(TrackVariantInfo.Type.AUDIO)
//get all subtitle tracks
val availableTextTracks = player.availableTrackVariants(TrackVariantInfo.Type.TEXT)
Get active Track
The currently active track in each type can be obtained from the Player using the activeTrackVariant
API. This API returns the active track of any given Type as a TrackVariantInfo
object and TrackVariantInfo.UNKNOWN
if active variant is not known.
val activeSubtitleTrack = player.getActiveTrackVariant(TrackVariantInfo.Type.TEXT)
val activeAudioTrack = player.getActiveTrackVariant(TrackVariantInfo.Type.AUDIO)
val activeVideoTrack = player.getActiveTrackVariant(TrackVariantInfo.Type.VIDEO)
Set preferred Track
Any particular track can be enabled using setPreferredTrackVariant
API on the player. This API takes the preferred track parameter as a TrackVariantInfo
object.
Pass TrackVariantInfo.NONE
to clear all existing selection preferences.
//enable first subtitle track
player.setPreferredTrackVariant(TrackVariantInfo.Type.TEXT, availableTextTracks[0])
//disable subtitles
player.setPreferredTrackVariant(TrackVariantInfo.Type.TEXT, TrackVariantInfo.NONE)
//enable first audio track
player.setPreferredTrackVariant(TrackVariantInfo.Type.AUDIO, availableAudioTracks[0])
//enable first video track
player.setPreferredTrackVariant(TrackVariantInfo.Type.VIDEO, availableVideoTracks[0])
Set maximum / minimum bitrates
Configures the Player's variant adaptation logic with the passed maximum and minimum bitrate constraints.
const val MAX_BITRATE_BPS = 780_000 // use preferred value here
const val MIN_BITRATE_BPS = 140_000 // use preferred value here
player.setPreferredBitrateThresholds(MAX_BITRATE_BPS, MIN_BITRATE_BPS)
//pass (Integer.MAX_VALUE,0) to reset any capping
player.setPreferredBitrateThresholds(Integer.MAX_VALUE, 0)
Invoke the API only after the Player enters the LOADED
or STARTED
state.
Dolby® Atmos™
Audio MIME Types
Dolby® Atmos™ content uses the eac3-joc
MIME type, which stands for Enhanced AC-3 with Joint Object Coding. The player supports multiple audio codecs with the following hierarchy:
MIME Type | Audio format |
---|---|
eac3-joc | Dolby® Atmos™ |
eac3 | Dolby® Digital Plus |
mp4a.40.2 | Advanced Audio Coding (AAC) or Stereo |
Default Preference to Dolby Atmos
By default, the player will automatically start playing in Dolby® Atmos™ if the device supports it and the stream includes it.
Retrieving Available Mime Types
To get the available audio MIME types from the player:
val availableMimeTypes = player.availableMimeType(TrackVariantInfo.Type.AUDIO)
// Example output:
// ['eac3-joc', 'eac3', 'mp4a.40.2']
If it includes 'eac3-joc', then playback supports Dolby Atmos.
Handling Mid-Stream Codec Switching
To switch between Dolby® Atmos™, Dolby® Digital Plus and Stereo using setPreferredMimeTypes
which is set through API on the player. This API takes the preferred track parameter as a TrackVariantInfo
object.
val preferredMimeTypes = arrayOf("eac3-joc")
player?.setPreferredMimeTypes(TrackVariantInfo.Type.AUDIO,preferredMimeTypes)
Support
Currently, Dolby® Atmos™ is only supported for VOD (Video on Demand) content and Smart TV's.
Best Practices
Default to Dolby Atmos:
Always set setPreferredMimeTypes
to ['eac3-joc']
if Dolby® Atmos™ support is a priority for your app.