android13/external/exoplayer/tree_8e57d3715f9092d5ec54ebe2e538f34bfcc34479/docs/track-selection.md

title
Track selection

Track selection determines which of the available media tracks are played by the player. This process is configured by [TrackSelectionParameters][], which support many different options to specify constraints and overrides.

Information about existing tracks

The player needs to prepare the media to know which tracks are available for selection. You can listen to Player.Listener.onTracksInfoChanged to get notified about changes, which may happen

• When preparation completes
• When the available or selected tracks change
• When the playlist item changes

player.addListener(new Player.Listener() {
  @Override
  public void onTracksInfoChanged(TracksInfo tracksInfo) {
    // Update UI using current TracksInfo.
  }
});

{: .language-java}

You can also retrieve the current TracksInfo by calling player.getCurrentTracksInfo().

TracksInfo contains a list of TrackGroupInfos with information about the track type, format details, player support and selection status of each available track. Tracks are grouped together into one TrackGroup if they represent the same content that can be used interchangeably by the player (for example, all audio tracks of a single language, but with different bitrates).

for (TrackGroupInfo groupInfo : tracksInfo.getTrackGroupInfos()) {
  // Group level information.
  @C.TrackType int trackType = groupInfo.getTrackType();
  boolean trackInGroupIsSelected = groupInfo.isSelected();
  boolean trackInGroupIsSupported = groupInfo.isSupported();
  for (int i = 0; i < groupInfo.length; i++) {
    // Individual track information.
    boolean isSupported = groupInfo.isTrackSupported(i);
    boolean isSelected = groupInfo.isTrackSelected(i);
    Format trackFormat = groupInfo.getTrackFormat(i);
  }
}

{: .language-java}

• A track is 'supported' if the Player is able to decode and render its samples. Note that even if multiple track groups of the same type (for example multiple audio track groups) are supported, it only means that they are supported individually and the player is not necessarily able to play them at the same time.
• A track is 'selected' if the track selector chose this track for playback using the current TrackSelectionParameters. If multiple tracks within one track group are selected, the player uses these tracks for adaptive playback (for example, multiple video tracks with different bitrates). Note that only one of these tracks will be played at any one time. If you want to be notified of in-playback changes to the adaptive video track you can listen to Player.Listener.onVideoSizeChanged.

Modifying track selection parameters

The selection process can be configured by setting TrackSelectionParameters on the Player with Player.setTrackSelectionParameters. These updates can be done before and during playback. In most cases, it's advisable to obtain the current parameters and only modify the required aspects with the TrackSelectionParameters.Builder. The builder class also allows chaining to specify multiple options with one command:

player.setTrackSelectionParameters(
    player.getTrackSelectionParameters()
        .buildUpon()
        .setMaxVideoSizeSd()
        .setPreferredAudioLanguage("hu")
        .build());

{: .language-java}

Constraint based track selection

Most options in TrackSelectionParameters allow you to specify constraints, which are independent of the tracks that are actually available. Typical constraints are:

• Maximum or minimum video width, height, frame rate, or bitrate.
• Maximum audio channel count or bitrate.
• Preferred MIME types for video or audio.
• Preferred audio languages or role flags.
• Preferred text languages or role flags.

Note that ExoPlayer already applies sensible defaults for most of these values, for example restricting video resolution to the display size or preferring the audio language that matches the user's system Locale setting.

There are several benefits to using constraint based track selection instead of specifying specific tracks directly:

• You can specify constraints before knowing what tracks the media provides. This allows to immediately select the appropriate tracks for faster startup time and also simplifies track selection code as you don't have to listen for changes in the available tracks.
• Constraints can be applied consistently across all items in a playlist. For example, selecting an audio language based on user preference will automatically apply to the next playlist item too, whereas overriding a specific track will only apply to the current playlist item for which the track exists.

Selecting specific tracks

It's possible to specify in TrackSelectionParameters which of the currently available tracks should be selected. First, the player's currently available tracks should be queried using Player.getTracksInfo. Second, having identified which tracks to select, they can be set on TrackSelectionParameters using TrackSelectionOverrides. For example, to select the first track from a specific audioTrackGroup:

player.setTrackSelectionParameters(
    player.getTrackSelectionParameters()
        .buildUpon()
        .setOverrideForType(
            new TrackSelectionOverride(audioTrackGroup, /* trackIndex= */ 0))
        .build());

{: .language-java}

Note that a TrackSelectionOverride will only apply to media items that contain the TrackGroup specified in the override. Hence an override may not apply to a subsequent media item if that item contains different tracks.

Disabling track types or groups

Track types, like video, audio or text, can be disabled completely using TrackSelectionParameters.Builder.setTrackTypeDisabled. A disabled track type will be disabled for all media items:

player.setTrackSelectionParameters(
    player.getTrackSelectionParameters()
        .buildUpon()
        .setTrackTypeDisabled(C.TRACK_TYPE_VIDEO, /* disabled= */ true)
        .build());

{: .language-java}

Alternatively, it's possible to prevent the selection of tracks from a specific TrackGroup by specifying an empty override for that group:

player.setTrackSelectionParameters(
    player.getTrackSelectionParameters()
        .buildUpon()
        .addOverride(
            new TrackSelectionOverride(
                disabledTrackGroup, ImmutableList.of()))
        .build());

{: .language-java}

Customizing the track selector

Track selection is the responsibility of a TrackSelector, an instance of which can be provided whenever an ExoPlayer is built and later obtained with ExoPlayer.getTrackSelector().

DefaultTrackSelector trackSelector = new DefaultTrackSelector(context);
ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setTrackSelector(trackSelector)
        .build();

{: .language-java}

DefaultTrackSelector is a flexible TrackSelector suitable for most use cases. It uses the TrackSelectionParameters set in the Player, but also provides some advanced customization options that can be specified in the DefaultTrackSelector.ParametersBuilder:

trackSelector.setParameters(
    trackSelector
        .buildUponParameters()
        .setAllowVideoMixedMimeTypeAdaptiveness(true));

{: .language-java}

Tunneling

Tunneled playback can be enabled in cases where the combination of renderers and selected tracks supports it. This can be done by using DefaultTrackSelector.ParametersBuilder.setTunnelingEnabled(true).

[TrackSelectionParameters]: {{ site.exo_sdk }}/trackselection/TrackSelectionParameters.html