1--- 2title: Track selection 3--- 4 5Track selection determines which of the available media tracks are played by the 6player. This process is configured by [`TrackSelectionParameters`][], which 7support many different options to specify constraints and overrides. 8 9## Information about existing tracks 10 11The player needs to prepare the media to know which tracks are available for 12selection. You can listen to `Player.Listener.onTracksInfoChanged` to get 13notified about changes, which may happen 14 * When preparation completes 15 * When the available or selected tracks change 16 * When the playlist item changes 17 18~~~ 19player.addListener(new Player.Listener() { 20 @Override 21 public void onTracksInfoChanged(TracksInfo tracksInfo) { 22 // Update UI using current TracksInfo. 23 } 24}); 25~~~ 26{: .language-java} 27 28You can also retrieve the current `TracksInfo` by calling 29`player.getCurrentTracksInfo()`. 30 31`TracksInfo` contains a list of `TrackGroupInfo`s with information about the 32track type, format details, player support and selection status of each 33available track. Tracks are grouped together into one `TrackGroup` if they 34represent the same content that can be used interchangeably by the player (for 35example, all audio tracks of a single language, but with different bitrates). 36 37~~~ 38for (TrackGroupInfo groupInfo : tracksInfo.getTrackGroupInfos()) { 39 // Group level information. 40 @C.TrackType int trackType = groupInfo.getTrackType(); 41 boolean trackInGroupIsSelected = groupInfo.isSelected(); 42 boolean trackInGroupIsSupported = groupInfo.isSupported(); 43 for (int i = 0; i < groupInfo.length; i++) { 44 // Individual track information. 45 boolean isSupported = groupInfo.isTrackSupported(i); 46 boolean isSelected = groupInfo.isTrackSelected(i); 47 Format trackFormat = groupInfo.getTrackFormat(i); 48 } 49} 50~~~ 51{: .language-java} 52 53* A track is 'supported' if the `Player` is able to decode and render its 54 samples. Note that even if multiple track groups of the same type (for example 55 multiple audio track groups) are supported, it only means that they are 56 supported individually and the player is not necessarily able to play them at 57 the same time. 58* A track is 'selected' if the track selector chose this track for playback 59 using the current `TrackSelectionParameters`. If multiple tracks within one 60 track group are selected, the player uses these tracks for adaptive playback 61 (for example, multiple video tracks with different bitrates). Note that only 62 one of these tracks will be played at any one time. If you want to be notified 63 of in-playback changes to the adaptive video track you can listen to 64 `Player.Listener.onVideoSizeChanged`. 65 66## Modifying track selection parameters 67 68The selection process can be configured by setting `TrackSelectionParameters` on 69the `Player` with `Player.setTrackSelectionParameters`. These updates can be 70done before and during playback. In most cases, it's advisable to obtain the 71current parameters and only modify the required aspects with the 72`TrackSelectionParameters.Builder`. The builder class also allows chaining to 73specify multiple options with one command: 74 75~~~ 76player.setTrackSelectionParameters( 77 player.getTrackSelectionParameters() 78 .buildUpon() 79 .setMaxVideoSizeSd() 80 .setPreferredAudioLanguage("hu") 81 .build()); 82~~~ 83{: .language-java} 84 85### Constraint based track selection 86 87Most options in `TrackSelectionParameters` allow you to specify constraints, 88which are independent of the tracks that are actually available. Typical 89constraints are: 90 91 * Maximum or minimum video width, height, frame rate, or bitrate. 92 * Maximum audio channel count or bitrate. 93 * Preferred MIME types for video or audio. 94 * Preferred audio languages or role flags. 95 * Preferred text languages or role flags. 96 97Note that ExoPlayer already applies sensible defaults for most of these values, 98for example restricting video resolution to the display size or preferring the 99audio language that matches the user's system Locale setting. 100 101There are several benefits to using constraint based track selection instead of 102specifying specific tracks directly: 103 104* You can specify constraints before knowing what tracks the media provides. 105 This allows to immediately select the appropriate tracks for faster startup 106 time and also simplifies track selection code as you don't have to listen for 107 changes in the available tracks. 108* Constraints can be applied consistently across all items in a playlist. For 109 example, selecting an audio language based on user preference will 110 automatically apply to the next playlist item too, whereas overriding a 111 specific track will only apply to the current playlist item for which the 112 track exists. 113 114### Selecting specific tracks 115 116It's possible to specify in `TrackSelectionParameters` which of the currently 117available tracks should be selected. First, the player's currently available 118tracks should be queried using `Player.getTracksInfo`. Second, having identified 119which tracks to select, they can be set on `TrackSelectionParameters` using 120`TrackSelectionOverrides`. For example, to select the first track from a 121specific `audioTrackGroup`: 122 123~~~ 124player.setTrackSelectionParameters( 125 player.getTrackSelectionParameters() 126 .buildUpon() 127 .setOverrideForType( 128 new TrackSelectionOverride(audioTrackGroup, /* trackIndex= */ 0)) 129 .build()); 130~~~ 131{: .language-java} 132 133Note that a `TrackSelectionOverride` will only apply to media items that contain 134the `TrackGroup` specified in the override. Hence an override may not apply to 135a subsequent media item if that item contains different tracks. 136 137### Disabling track types or groups 138 139Track types, like video, audio or text, can be disabled completely using 140`TrackSelectionParameters.Builder.setTrackTypeDisabled`. A disabled track type 141will be disabled for all media items: 142 143~~~ 144player.setTrackSelectionParameters( 145 player.getTrackSelectionParameters() 146 .buildUpon() 147 .setTrackTypeDisabled(C.TRACK_TYPE_VIDEO, /* disabled= */ true) 148 .build()); 149~~~ 150{: .language-java} 151 152Alternatively, it's possible to prevent the selection of tracks from a specific 153`TrackGroup` by specifying an empty override for that group: 154 155~~~ 156player.setTrackSelectionParameters( 157 player.getTrackSelectionParameters() 158 .buildUpon() 159 .addOverride( 160 new TrackSelectionOverride( 161 disabledTrackGroup, ImmutableList.of())) 162 .build()); 163~~~ 164{: .language-java} 165 166## Customizing the track selector 167 168Track selection is the responsibility of a `TrackSelector`, an instance 169of which can be provided whenever an `ExoPlayer` is built and later obtained 170with `ExoPlayer.getTrackSelector()`. 171 172~~~ 173DefaultTrackSelector trackSelector = new DefaultTrackSelector(context); 174ExoPlayer player = 175 new ExoPlayer.Builder(context) 176 .setTrackSelector(trackSelector) 177 .build(); 178~~~ 179{: .language-java} 180 181`DefaultTrackSelector` is a flexible `TrackSelector` suitable for most use 182cases. It uses the `TrackSelectionParameters` set in the `Player`, but also 183provides some advanced customization options that can be specified in the 184`DefaultTrackSelector.ParametersBuilder`: 185 186~~~ 187trackSelector.setParameters( 188 trackSelector 189 .buildUponParameters() 190 .setAllowVideoMixedMimeTypeAdaptiveness(true)); 191~~~ 192{: .language-java} 193 194### Tunneling 195 196Tunneled playback can be enabled in cases where the combination of renderers and 197selected tracks supports it. This can be done by using 198`DefaultTrackSelector.ParametersBuilder.setTunnelingEnabled(true)`. 199 200[`TrackSelectionParameters`]: {{ site.exo_sdk }}/trackselection/TrackSelectionParameters.html 201