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  TrackGroup group = groupInfo.getTrackGroup();
44  for (int i = 0; i < group.length; i++) {
45    // Individual track information.
46    boolean isSupported = groupInfo.isTrackSupported(i);
47    boolean isSelected = groupInfo.isTrackSelected(i);
48    Format trackFormat = group.getFormat(i);
49  }
50}
51~~~
52{: .language-java}
53
54* A track is 'supported' if the `Player` is able to decode and render its
55  samples. Note that even if multiple track groups of the same type (for example
56  multiple audio track groups) are supported, it only means that they are
57  supported individually and the player is not necessarily able to play them at
58  the same time.
59* A track is 'selected' if the track selector chose this track for playback
60  using the current `TrackSelectionParameters`. If multiple tracks within one
61  track group are selected, the player uses these tracks for adaptive playback
62  (for example, multiple video tracks with different bitrates). Note that only
63  one of these tracks will be played at any one time. If you want to be notified
64  of in-playback changes to the adaptive video track you can listen to
65  `Player.Listener.onVideoSizeChanged`.
66
67## Modifying track selection parameters
68
69The selection process can be configured by setting `TrackSelectionParameters` on
70the `Player` with `Player.setTrackSelectionParameters`. These updates can be
71done before and during playback. In most cases, it's advisable to obtain the
72current parameters and only modify the required aspects with the
73`TrackSelectionParameters.Builder`. The builder class also allows chaining to
74specify multiple options with one command:
75
76~~~
77player.setTrackSelectionParameters(
78    player.getTrackSelectionParameters()
79        .buildUpon()
80        .setMaxVideoSizeSd()
81        .setPreferredAudioLanguage("hu")
82        .build());
83~~~
84{: .language-java}
85
86### Constraint based track selection
87
88Most options in `TrackSelectionParameters` allow you to specify constraints,
89which are independent of the tracks that are actually available. Typical
90constraints are:
91
92 * Maximum or minimum video width, height, frame rate, or bitrate.
93 * Maximum audio channel count or bitrate.
94 * Preferred MIME types for video or audio.
95 * Preferred audio languages or role flags.
96 * Preferred text languages or role flags.
97
98Note that ExoPlayer already applies sensible defaults for most of these values,
99for example restricting video resolution to the display size or preferring the
100audio language that matches the user's system Locale setting.
101
102There are several benefits to using constraint based track selection instead of
103specifying specific tracks directly:
104
105* You can specify constraints before knowing what tracks the media provides.
106  This allows to immediately select the appropriate tracks for faster startup
107  time and also simplifies track selection code as you don't have to listen for
108  changes in the available tracks.
109* Constraints can be applied consistently across all items in a playlist. For
110  example, selecting an audio language based on user preference will
111  automatically apply to the next playlist item too, whereas overriding a
112  specific track will only apply to the current playlist item for which the
113  track exists.
114
115### Selecting specific tracks
116
117It's possible to specify specific tracks in `TrackSelectionParameters` that
118should be selected for the current set of tracks. Note that a change in the
119available tracks, for example when changing items in a playlist, will also
120invalidate such a track override.
121
122The simplest way to specify track overrides is to specify the `TrackGroup` that
123should be selected for its track type. For example, you can specify an audio
124track group to select this audio group and prevent any other audio track groups
125from being selected:
126
127~~~
128TrackSelectionOverrides overrides =
129    new TrackSelectionOverrides.Builder()
130        .setOverrideForType(new TrackSelectionOverride(audioTrackGroup))
131        .build();
132player.setTrackSelectionParameters(
133    player.getTrackSelectionParameters()
134        .buildUpon().setTrackSelectionOverrides(overrides).build());
135~~~
136{: .language-java}
137
138### Disabling track types or groups
139
140Track types, like video, audio or text, can be disabled completely by using
141`TrackSelectionParameters.Builder.setDisabledTrackTypes`. This will apply
142unconditionally and will also affect other playlist items.
143
144~~~
145player.setTrackSelectionParameters(
146    player.getTrackSelectionParameters()
147        .buildUpon()
148        .setDisabledTrackTypes(ImmutableSet.of(C.TRACK_TYPE_VIDEO))
149        .build());
150~~~
151{: .language-java}
152
153Alternatively, it's possible to prevent the selection of track groups for the
154current playlist item only by specifying empty overrides for these groups:
155
156~~~
157TrackSelectionOverrides overrides =
158    new TrackSelectionOverrides.Builder()
159        .addOverride(
160             new TrackSelectionOverride(
161                disabledTrackGroup,
162                /* select no tracks for this group */ ImmutableList.of()))
163        .build();
164player.setTrackSelectionParameters(
165    player.getTrackSelectionParameters()
166        .buildUpon().setTrackSelectionOverrides(overrides).build());
167~~~
168{: .language-java}
169
170## Customizing the track selector
171
172Track selection is the responsibility of a `TrackSelector`, an instance
173of which can be provided whenever an `ExoPlayer` is built and later obtained
174with `ExoPlayer.getTrackSelector()`.
175
176~~~
177DefaultTrackSelector trackSelector = new DefaultTrackSelector(context);
178ExoPlayer player =
179    new ExoPlayer.Builder(context)
180        .setTrackSelector(trackSelector)
181        .build();
182~~~
183{: .language-java}
184
185`DefaultTrackSelector` is a flexible `TrackSelector` suitable for most use
186cases. It uses the `TrackSelectionParameters` set in the `Player`, but also
187provides some advanced customization options that can be specified in the
188`DefaultTrackSelector.ParametersBuilder`:
189
190~~~
191trackSelector.setParameters(
192    trackSelector
193        .buildUponParameters()
194        .setAllowVideoMixedMimeTypeAdaptiveness(true));
195~~~
196{: .language-java}
197
198### Tunneling
199
200Tunneled playback can be enabled in cases where the combination of renderers and
201selected tracks supports it. This can be done by using
202`DefaultTrackSelector.ParametersBuilder.setTunnelingEnabled(true)`.
203
204[`TrackSelectionParameters`]: {{ site.exo_sdk }}/trackselection/TrackSelectionParameters.html
205