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 preferred audio or subtitle language

When the only relevant criteria for changing AUDIO or TEXT track variant is the language code the following API set is provided:

// Retrieves a list of available audio languages for the current media content.
// This function is typically used in scenarios where a media player or content delivery system supports multiple audio tracks for a single piece of media.
// It allows the application to determine which language options are available to the user.
// Returns a list of strings, where each string represents an available audio language. The format of these strings may vary depending
// on the underlying implementation (e.g., ISO 639-1 language codes like "en", "es".
// If no audio languages are available or the information cannot be retrieved, an empty list is returned.
player.getAvailableAudioLanguages(): List<String>

// Sets the preferred audio language for the media player.
// This function allows you to specify the language that the media player should prioritize when multiple audio tracks are available for the currently playing media.
// @param languageCode A String representing the desired audio language.
// This should be a valid IETF BCP 47 language code (e.g., "en" for English, "es" for Spanish, "fr-CA" for Canadian French).
// If an empty string or an invalid language code is provided, the behavior might be platform-dependent (e.g., it might revert to a default language or the previously set language).
// @example
// Set preferred audio language to English
// setPreferredAudioLanguage("en");
// Set preferred audio language to Spanish
// setPreferredAudioLanguage("es");
// Set preferred audio language to French (Canadian)
// setPreferredAudioLanguage("fr-CA");
player.setPreferredAudioLanguage(languageCode)

// Returns a list of available subtitle languages.
// This function retrieves a list of language codes representing the subtitle languages that are currently available for the media content.
// The language codes typically follow ISO 639-1 or ISO 639-2 standards (e.g., "en" for English, "es" for Spanish).
// The list might be empty if no subtitles are available or if the information hasn't been loaded yet.
player.getAvailableSubtitleLanguages(): List<String>

// Sets the preferred language for subtitles.
// This function allows you to specify a language code (e.g., "en" for English, "es" for Spanish) that the player should prioritize when selecting
// a subtitle track if multiple subtitle tracks are available.
// If a subtitle track in the preferred language is available, it will be automatically selected. If not, the player might fall back to a default
// subtitle track or no subtitles, depending on its implementation.
// @param languageCode A String representing the IETF BCP 47 language code (e.g., "en", "fr-CA", "es-419") for the preferred subtitle language.
// Passing an empty string or null might reset to the default behavior or have no effect, depending on the player's implementation.
player.setPreferredSubtitleLanguage(languageCode)

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)

tip

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)

info

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.