0
# Track Selection
1

2
Track selection in ExoPlayer determines which tracks (audio, video, text) are selected for playback from the available options. The DefaultTrackSelector provides adaptive capabilities for automatic track selection based on device capabilities and network conditions.
3

4
## TrackSelector Base Class
5

6
The abstract base class for all track selectors.
7

8
```java { .api }
9
public abstract class TrackSelector {
10
    /**
11
     * Initializes the track selector.
12
     * 
13
     * @param listener The InvalidationListener
14
     * @param bandwidthMeter The BandwidthMeter
15
     */
16
    public final void init(InvalidationListener listener, BandwidthMeter bandwidthMeter);
17
    
18
    /**
19
     * Selects tracks for the given mapped track info.
20
     * 
21
     * @param mappedTrackInfo The mapped track info
22
     * @param rendererCapabilities The renderer capabilities
23
     * @param mediaPeriodId The media period ID
24
     * @param timeline The timeline
25
     * @return The track selection result
26
     * @throws ExoPlaybackException If track selection fails
27
     */
28
    public abstract TrackSelectorResult selectTracks(MappedTrackInfo mappedTrackInfo, 
29
                                                   RendererCapabilities[] rendererCapabilities,
30
                                                   MediaPeriodId mediaPeriodId, 
31
                                                   Timeline timeline) throws ExoPlaybackException;
32
    
33
    /**
34
     * Called when track selections are activated.
35
     * 
36
     * @param info The track info
37
     * @param mediaPeriodId The media period ID
38
     */
39
    public void onSelectionActivated(Object info, MediaPeriodId mediaPeriodId);
40
    
41
    /**
42
     * Releases the track selector.
43
     */
44
    public void release();
45
    
46
    /**
47
     * Returns the current parameters.
48
     * 
49
     * @return The current parameters
50
     */
51
    public abstract TrackSelectionParameters getParameters();
52
    
53
    /**
54
     * Sets new parameters.
55
     * 
56
     * @param parameters The new parameters
57
     */
58
    public abstract void setParameters(TrackSelectionParameters parameters);
59
    
60
    /**
61
     * Returns whether parameter setting is supported.
62
     * 
63
     * @return Whether parameter setting is supported
64
     */
65
    public abstract boolean isSetParametersSupported();
66
}
67
```
68

69
## DefaultTrackSelector
70

71
The default track selector with adaptive capabilities and extensive configuration options.
72

73
```java { .api }
74
public class DefaultTrackSelector extends MappingTrackSelector {
75
    /**
76
     * Builder for DefaultTrackSelector.
77
     */
78
    public static final class Builder {
79
        /**
80
         * Creates a builder.
81
         * 
82
         * @param context The context
83
         */
84
        public Builder(Context context);
85
        
86
        /**
87
         * Sets whether to force the lowest bitrate.
88
         * 
89
         * @param forceLowestBitrate Whether to force lowest bitrate
90
         * @return This builder
91
         */
92
        public Builder setForceLowestBitrate(boolean forceLowestBitrate);
93
        
94
        /**
95
         * Sets whether to force the highest supported bitrate.
96
         * 
97
         * @param forceHighestSupportedBitrate Whether to force highest supported bitrate
98
         * @return This builder
99
         */
100
        public Builder setForceHighestSupportedBitrate(boolean forceHighestSupportedBitrate);
101
        
102
        /**
103
         * Sets whether tunneling is enabled.
104
         * 
105
         * @param tunnelingEnabled Whether tunneling is enabled
106
         * @return This builder
107
         */
108
        public Builder setTunnelingEnabled(boolean tunnelingEnabled);
109
        
110
        /**
111
         * Builds the DefaultTrackSelector.
112
         * 
113
         * @return The built DefaultTrackSelector
114
         */
115
        public DefaultTrackSelector build();
116
    }
117
    
118
    /**
119
     * Sets the parameters for track selection.
120
     * 
121
     * @param parameters The parameters
122
     */
123
    public void setParameters(Parameters parameters);
124
    
125
    /**
126
     * Gets the current parameters.
127
     * 
128
     * @return The current parameters
129
     */
130
    public Parameters getParameters();
131
    
132
    /**
133
     * Creates a parameters builder based on current parameters.
134
     * 
135
     * @return A parameters builder
136
     */
137
    public Parameters.Builder buildUponParameters();
138
    
139
    /**
140
     * Gets information about currently mapped tracks.
141
     * 
142
     * @return The mapped track info, or null if not available
143
     */
144
    @Nullable public MappedTrackInfo getCurrentMappedTrackInfo();
145
}
146
```
147

148
## Track Selection Parameters
149

150
Configuration parameters for track selection behavior.
151

152
```java { .api }
153
public static final class Parameters extends TrackSelectionParameters {
154
    /**
155
     * Builder for Parameters.
156
     */
157
    public static final class Builder extends TrackSelectionParameters.Builder {
158
        /**
159
         * Creates a builder.
160
         * 
161
         * @param context The context
162
         */
163
        public Builder(Context context);
164
        
165
        /**
166
         * Creates a builder from existing parameters.
167
         * 
168
         * @param initialValues The initial parameter values
169
         */
170
        public Builder(Parameters initialValues);
171
        
172
        // Video parameters
173
        public Builder setMaxVideoSizeSd();
174
        public Builder clearVideoSizeConstraints();
175
        public Builder setMaxVideoSize(int maxVideoWidth, int maxVideoHeight);
176
        public Builder setMaxVideoFrameRate(int maxVideoFrameRate);
177
        public Builder setMaxVideoBitrate(int maxVideoBitrate);
178
        public Builder setMinVideoSize(int minVideoWidth, int minVideoHeight);
179
        public Builder setMinVideoFrameRate(int minVideoFrameRate);
180
        public Builder setMinVideoBitrate(int minVideoBitrate);
181
        public Builder setViewportSizeToPhysicalDisplaySize(Context context, boolean viewportOrientationMayChange);
182
        public Builder clearViewportSizeConstraints();
183
        public Builder setViewportSize(int viewportWidth, int viewportHeight, boolean viewportOrientationMayChange);
184
        public Builder setPreferredVideoMimeType(@Nullable String mimeType);
185
        public Builder setPreferredVideoMimeTypes(String... mimeTypes);
186
        public Builder setPreferredVideoRoleFlags(@C.RoleFlags int preferredVideoRoleFlags);
187
        
188
        // Audio parameters
189
        public Builder setMaxAudioChannelCount(int maxAudioChannelCount);
190
        public Builder setMaxAudioBitrate(int maxAudioBitrate);
191
        public Builder setPreferredAudioLanguage(@Nullable String preferredAudioLanguage);
192
        public Builder setPreferredAudioLanguages(String... preferredAudioLanguages);
193
        public Builder setPreferredAudioMimeType(@Nullable String mimeType);
194
        public Builder setPreferredAudioMimeTypes(String... mimeTypes);
195
        public Builder setPreferredAudioRoleFlags(@C.RoleFlags int preferredAudioRoleFlags);
196
        
197
        // Text parameters
198
        public Builder setPreferredTextLanguage(@Nullable String preferredTextLanguage);
199
        public Builder setPreferredTextLanguages(String... preferredTextLanguages);
200
        public Builder setPreferredTextRoleFlags(@C.RoleFlags int preferredTextRoleFlags);
201
        public Builder setIgnoredTextSelectionFlags(@C.SelectionFlags int ignoredTextSelectionFlags);
202
        public Builder setSelectUndeterminedTextLanguage(boolean selectUndeterminedTextLanguage);
203
        
204
        // General parameters
205
        public Builder setForceLowestBitrate(boolean forceLowestBitrate);
206
        public Builder setForceHighestSupportedBitrate(boolean forceHighestSupportedBitrate);
207
        public Builder addOverride(TrackSelectionOverride override);
208
        public Builder setOverrideForType(TrackSelectionOverride override);
209
        public Builder clearOverride(TrackGroup trackGroup);
210
        public Builder clearOverridesOfType(@C.TrackType int trackType);
211
        public Builder setDisabledTrackTypes(Set<Integer> disabledTrackTypes);
212
        public Builder setTrackTypeDisabled(@C.TrackType int trackType, boolean disabled);
213
        public Builder setTunnelingEnabled(boolean tunnelingEnabled);
214
        public Builder setAllowMultipleAdaptiveSelections(boolean allowMultipleAdaptiveSelections);
215
        
216
        /**
217
         * Builds the Parameters.
218
         * 
219
         * @return The built Parameters
220
         */
221
        public Parameters build();
222
    }
223
    
224
    // Video constraints
225
    public final int maxVideoWidth;
226
    public final int maxVideoHeight;
227
    public final int maxVideoFrameRate;
228
    public final int maxVideoBitrate;
229
    public final int minVideoWidth;
230
    public final int minVideoHeight;
231
    public final int minVideoFrameRate;
232
    public final int minVideoBitrate;
233
    public final int viewportWidth;
234
    public final int viewportHeight;
235
    public final boolean viewportOrientationMayChange;
236
    public final ImmutableList<String> preferredVideoMimeTypes;
237
    @C.RoleFlags public final int preferredVideoRoleFlags;
238
    
239
    // Audio constraints
240
    public final int maxAudioChannelCount;
241
    public final int maxAudioBitrate;
242
    public final ImmutableList<String> preferredAudioLanguages;
243
    public final ImmutableList<String> preferredAudioMimeTypes;
244
    @C.RoleFlags public final int preferredAudioRoleFlags;
245
    
246
    // Text constraints
247
    public final ImmutableList<String> preferredTextLanguages;
248
    @C.RoleFlags public final int preferredTextRoleFlags;
249
    @C.SelectionFlags public final int ignoredTextSelectionFlags;
250
    public final boolean selectUndeterminedTextLanguage;
251
    
252
    // General selection constraints
253
    public final boolean forceLowestBitrate;
254
    public final boolean forceHighestSupportedBitrate;
255
    public final ImmutableMap<TrackGroup, TrackSelectionOverride> overrides;
256
    public final ImmutableSet<Integer> disabledTrackTypes;
257
    public final boolean tunnelingEnabled;
258
    public final boolean allowMultipleAdaptiveSelections;
259
}
260
```
261

262
## ExoTrackSelection Interface
263

264
Interface for track selections with ExoPlayer-specific functionality.
265

266
```java { .api }
267
public interface ExoTrackSelection extends TrackSelection {
268
    /**
269
     * Called when the selection is enabled.
270
     * 
271
     * @param mediaPeriodId The media period ID
272
     * @param positionUs The position in microseconds
273
     */
274
    void enable();
275
    
276
    /**
277
     * Called when playback starts.
278
     */
279
    void start();
280
    
281
    /**
282
     * Called when the playback speed changes.
283
     * 
284
     * @param playbackSpeed The new playback speed
285
     */
286
    void onPlaybackSpeed(float playbackSpeed);
287
    
288
    /**
289
     * Updates the selected track for the current playback position.
290
     * 
291
     * @param playbackPositionUs The playback position in microseconds
292
     * @param bufferedDurationUs The buffered duration in microseconds
293
     * @param availableDurationUs The available duration in microseconds
294
     * @param queue The queue of loaded media chunks
295
     * @param mediaChunkIterators Iterators for obtaining future chunks
296
     */
297
    void updateSelectedTrack(long playbackPositionUs, long bufferedDurationUs, long availableDurationUs,
298
                           List<? extends MediaChunk> queue, MediaChunkIterator[] mediaChunkIterators);
299
    
300
    /**
301
     * Returns whether ongoing loads should be canceled.
302
     * 
303
     * @param playbackPositionUs The playback position in microseconds
304
     * @param loadingChunk The currently loading chunk
305
     * @param queue The queue of loaded chunks
306
     * @return Whether to cancel the load
307
     */
308
    boolean shouldCancelChunkLoad(long playbackPositionUs, Chunk loadingChunk, List<? extends MediaChunk> queue);
309
    
310
    /**
311
     * Blacklists a track for the specified duration.
312
     * 
313
     * @param trackIndex The index of the track to blacklist
314
     * @param blacklistDurationMs The blacklist duration in milliseconds
315
     */
316
    boolean blacklist(int trackIndex, long blacklistDurationMs);
317
    
318
    /**
319
     * Returns the latest bitrate estimate.
320
     * 
321
     * @return The bitrate estimate in bits per second
322
     */
323
    long getLatestBitrateEstimate();
324
}
325
```
326

327
## Usage Examples
328

329
### Basic Track Selector Setup
330

331
```java
332
// Create default track selector
333
DefaultTrackSelector trackSelector = new DefaultTrackSelector.Builder(context).build();
334

335
// Use with ExoPlayer
336
ExoPlayer player = new ExoPlayer.Builder(context)
337
    .setTrackSelector(trackSelector)
338
    .build();
339
```
340

341
### Configuring Track Selection Parameters
342

343
```java
344
DefaultTrackSelector trackSelector = new DefaultTrackSelector.Builder(context).build();
345

346
// Configure parameters
347
DefaultTrackSelector.Parameters.Builder parametersBuilder = trackSelector.buildUponParameters();
348

349
// Video constraints
350
parametersBuilder
351
    .setMaxVideoSizeSd()  // Limit to SD resolution
352
    .setMaxVideoBitrate(2_000_000)  // 2 Mbps max
353
    .setPreferredVideoMimeType(MimeTypes.VIDEO_H264);  // Prefer H.264
354

355
// Audio constraints  
356
parametersBuilder
357
    .setMaxAudioChannelCount(2)  // Stereo max
358
    .setPreferredAudioLanguage("en")  // Prefer English
359
    .setMaxAudioBitrate(128_000);  // 128 kbps max
360

361
// Text constraints
362
parametersBuilder
363
    .setPreferredTextLanguage("en")  // Prefer English subtitles
364
    .setSelectUndeterminedTextLanguage(false);  // Don't select undetermined language
365

366
// Apply parameters
367
trackSelector.setParameters(parametersBuilder.build());
368
```
369

370
### Manual Track Selection
371

372
```java
373
// Get mapped track info
374
MappedTrackInfo mappedTrackInfo = trackSelector.getCurrentMappedTrackInfo();
375
if (mappedTrackInfo != null) {
376
    // Find video renderer
377
    for (int rendererIndex = 0; rendererIndex < mappedTrackInfo.getRendererCount(); rendererIndex++) {
378
        if (mappedTrackInfo.getRendererType(rendererIndex) == C.TRACK_TYPE_VIDEO) {
379
            TrackGroupArray trackGroups = mappedTrackInfo.getTrackGroups(rendererIndex);
380
            
381
            // Create override for specific track
382
            TrackGroup trackGroup = trackGroups.get(0);  // First track group
383
            List<Integer> trackIndices = Arrays.asList(0);  // First track in group
384
            
385
            TrackSelectionOverride override = new TrackSelectionOverride(trackGroup, trackIndices);
386
            
387
            // Apply override
388
            DefaultTrackSelector.Parameters newParameters = trackSelector.buildUponParameters()
389
                .setOverrideForType(override)
390
                .build();
391
                
392
            trackSelector.setParameters(newParameters);
393
            break;
394
        }
395
    }
396
}
397
```
398

399
### Adaptive Bitrate Configuration
400

401
```java
402
// Force lowest bitrate (for testing or poor network)
403
DefaultTrackSelector.Parameters lowBitrateParams = trackSelector.buildUponParameters()
404
    .setForceLowestBitrate(true)
405
    .build();
406
trackSelector.setParameters(lowBitrateParams);
407

408
// Force highest supported bitrate
409
DefaultTrackSelector.Parameters highBitrateParams = trackSelector.buildUponParameters()
410
    .setForceHighestSupportedBitrate(true)
411
    .build();
412
trackSelector.setParameters(highBitrateParams);
413

414
// Custom constraints
415
DefaultTrackSelector.Parameters customParams = trackSelector.buildUponParameters()
416
    .setMaxVideoBitrate(1_000_000)  // 1 Mbps max
417
    .setMinVideoBitrate(500_000)    // 500 kbps min
418
    .build();
419
trackSelector.setParameters(customParams);
420
```
421

422
### Language and Accessibility Preferences
423

424
```java
425
DefaultTrackSelector.Parameters params = trackSelector.buildUponParameters()
426
    // Multiple preferred audio languages (in order of preference)
427
    .setPreferredAudioLanguages("en", "es", "fr")
428
    
429
    // Multiple preferred text languages
430
    .setPreferredTextLanguages("en", "es")
431
    
432
    // Prefer audio descriptions for accessibility
433
    .setPreferredAudioRoleFlags(C.ROLE_FLAG_DESCRIBES_VIDEO)
434
    
435
    // Prefer SDH subtitles
436
    .setPreferredTextRoleFlags(C.ROLE_FLAG_DESCRIBES_MUSIC_AND_SOUND)
437
    
438
    .build();
439
    
440
trackSelector.setParameters(params);
441
```
442

443
### Disabling Track Types
444

445
```java
446
// Disable text tracks (subtitles/captions)
447
DefaultTrackSelector.Parameters noTextParams = trackSelector.buildUponParameters()
448
    .setTrackTypeDisabled(C.TRACK_TYPE_TEXT, true)
449
    .build();
450
trackSelector.setParameters(noTextParams);
451

452
// Disable multiple track types
453
Set<Integer> disabledTypes = new HashSet<>();
454
disabledTypes.add(C.TRACK_TYPE_TEXT);
455
disabledTypes.add(C.TRACK_TYPE_METADATA);
456

457
DefaultTrackSelector.Parameters params = trackSelector.buildUponParameters()
458
    .setDisabledTrackTypes(disabledTypes)
459
    .build();
460
trackSelector.setParameters(params);
461
```
462

463
### Viewport-Based Selection
464

465
```java
466
// Set viewport size for adaptive selection
467
DefaultTrackSelector.Parameters params = trackSelector.buildUponParameters()
468
    .setViewportSizeToPhysicalDisplaySize(context, true)  // Use device display size
469
    .build();
470
trackSelector.setParameters(params);
471

472
// Custom viewport size
473
DefaultTrackSelector.Parameters customViewportParams = trackSelector.buildUponParameters()
474
    .setViewportSize(1920, 1080, false)  // 1080p viewport
475
    .build();
476
trackSelector.setParameters(customViewportParams);
477
```