com.google.android.exoplayer2.trackselection

Class DefaultTrackSelector

java.lang.Object

com.google.android.exoplayer2.trackselection.TrackSelector

com.google.android.exoplayer2.trackselection.MappingTrackSelector

com.google.android.exoplayer2.trackselection.DefaultTrackSelector

public class DefaultTrackSelector
extends MappingTrackSelector

A default TrackSelector suitable for most use cases. Track selections are made according to configurable DefaultTrackSelector.Parameters, which can be set by calling setParameters(Parameters).

Modifying parameters

To modify only some aspects of the parameters currently used by a selector, it's possible to obtain a DefaultTrackSelector.ParametersBuilder initialized with the current DefaultTrackSelector.Parameters. The desired modifications can be made on the builder, and the resulting DefaultTrackSelector.Parameters can then be built and set on the selector. For example the following code modifies the parameters to restrict video track selections to SD, and to prefer German audio tracks:

 // Build on the current parameters.
 Parameters currentParameters = trackSelector.getParameters();
 // Build the resulting parameters.
 Parameters newParameters = currentParameters
     .buildUpon()
     .setMaxVideoSizeSd()
     .setPreferredAudioLanguage("deu")
     .build();
 // Set the new parameters.
 trackSelector.setParameters(newParameters);
 

Convenience methods and chaining allow this to be written more concisely as:

 trackSelector.setParameters(
     trackSelector
         .buildUponParameters()
         .setMaxVideoSizeSd()
         .setPreferredAudioLanguage("deu"));
 

Selection DefaultTrackSelector.Parameters support many different options, some of which are described below.

Track selection overrides

Track selection overrides can be used to select specific tracks. To specify an override for a renderer, it's first necessary to obtain the tracks that have been mapped to it:

 MappedTrackInfo mappedTrackInfo = trackSelector.getCurrentMappedTrackInfo();
 TrackGroupArray rendererTrackGroups = mappedTrackInfo == null ? null
     : mappedTrackInfo.getTrackGroups(rendererIndex);
 

If rendererTrackGroups is null then there aren't any currently mapped tracks, and so setting an override isn't possible. Note that a Player.EventListener registered on the player can be used to determine when the current tracks (and therefore the mapping) changes. If rendererTrackGroups is non-null then an override can be set. The next step is to query the properties of the available tracks to determine the groupIndex and the trackIndices within the group it that should be selected. The override can then be specified using DefaultTrackSelector.ParametersBuilder.setSelectionOverride(int, com.google.android.exoplayer2.source.TrackGroupArray, com.google.android.exoplayer2.trackselection.DefaultTrackSelector.SelectionOverride):

 SelectionOverride selectionOverride = new SelectionOverride(groupIndex, trackIndices);
 trackSelector.setParameters(
     trackSelector
         .buildUponParameters()
         .setSelectionOverride(rendererIndex, rendererTrackGroups, selectionOverride));
 

Disabling renderers

Renderers can be disabled using DefaultTrackSelector.ParametersBuilder.setRendererDisabled(int, boolean). Disabling a renderer differs from setting a null override because the renderer is disabled unconditionally, whereas a null override is applied only when the track groups available to the renderer match the TrackGroupArray for which it was specified.

Constraint based track selection

Whilst track selection overrides make it possible to select specific tracks, the recommended way of controlling which tracks are selected is by specifying constraints. For example consider the case of wanting to restrict video track selections to SD, and preferring German audio tracks. Track selection overrides could be used to select specific tracks meeting these criteria, however a simpler and more flexible approach is to specify these constraints directly:

 trackSelector.setParameters(
     trackSelector
         .buildUponParameters()
         .setMaxVideoSizeSd()
         .setPreferredAudioLanguage("deu"));
 

There are several benefits to using constraint based track selection instead of specific track overrides:

• You can specify constraints before knowing what tracks the media provides. This can simplify track selection code (e.g. you don't have to listen for changes in the available tracks before configuring the selector).
• Constraints can be applied consistently across all periods in a complex piece of media, even if those periods contain different tracks. In contrast, a specific track override is only applied to periods whose tracks match those for which the override was set.

Tunneling

Tunneled playback can be enabled in cases where the combination of renderers and selected tracks support it. Tunneled playback is enabled by passing an audio session ID to DefaultTrackSelector.ParametersBuilder.setTunnelingAudioSessionId(int).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DefaultTrackSelector.Parameters Constraint parameters for DefaultTrackSelector.
static class	DefaultTrackSelector.ParametersBuilder A builder for DefaultTrackSelector.Parameters.
static class	DefaultTrackSelector.SelectionOverride A track selection override.

Nested classes/interfaces inherited from class com.google.android.exoplayer2.trackselection.MappingTrackSelector

MappingTrackSelector.MappedTrackInfo

Nested classes/interfaces inherited from class com.google.android.exoplayer2.trackselection.TrackSelector

TrackSelector.InvalidationListener

Constructor Summary

Constructors

Constructor and Description
DefaultTrackSelector() Constructs an instance that does not support adaptive track selection.
DefaultTrackSelector(BandwidthMeter bandwidthMeter) Constructs an instance that supports adaptive track selection.
DefaultTrackSelector(TrackSelection.Factory adaptiveTrackSelectionFactory) Constructs an instance that uses a factory to create adaptive track selections.

Method Summary

Modifier and Type	Method and Description
DefaultTrackSelector.ParametersBuilder	buildUponParameters() Returns a new DefaultTrackSelector.ParametersBuilder initialized with the current selection parameters.
void	clearSelectionOverride(int rendererIndex, TrackGroupArray groups) Deprecated. Use DefaultTrackSelector.ParametersBuilder.clearSelectionOverride(int, TrackGroupArray).
void	clearSelectionOverrides() Deprecated. Use DefaultTrackSelector.ParametersBuilder.clearSelectionOverrides().
void	clearSelectionOverrides(int rendererIndex) Deprecated. Use DefaultTrackSelector.ParametersBuilder.clearSelectionOverrides(int).
protected static boolean	formatHasLanguage(Format format, java.lang.String language) Returns whether a Format specifies a particular language, or false if language is null.
protected static boolean	formatHasNoLanguage(Format format) Returns whether a Format does not define a language.
DefaultTrackSelector.Parameters	getParameters() Gets the current selection parameters.
boolean	getRendererDisabled(int rendererIndex) Deprecated. Use DefaultTrackSelector.Parameters.getRendererDisabled(int). *
DefaultTrackSelector.SelectionOverride	getSelectionOverride(int rendererIndex, TrackGroupArray groups) Deprecated. Use DefaultTrackSelector.Parameters.getSelectionOverride(int, TrackGroupArray).
boolean	hasSelectionOverride(int rendererIndex, TrackGroupArray groups) Deprecated. Use DefaultTrackSelector.Parameters.hasSelectionOverride(int, TrackGroupArray). *
protected static boolean	isSupported(int formatSupport, boolean allowExceedsCapabilities) Applies the RendererCapabilities.FORMAT_SUPPORT_MASK to a value obtained from RendererCapabilities.supportsFormat(Format), returning true if the result is RendererCapabilities.FORMAT_HANDLED or if allowExceedsCapabilities is set and the result is RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES.
protected TrackSelection[]	selectAllTracks(MappingTrackSelector.MappedTrackInfo mappedTrackInfo, int[][][] rendererFormatSupports, int[] rendererMixedMimeTypeAdaptationSupports, DefaultTrackSelector.Parameters params) Called from MappingTrackSelector.selectTracks(MappedTrackInfo, int[][][], int[]) to make a track selection for each renderer, prior to overrides and disabled flags being applied.
protected TrackSelection	selectAudioTrack(TrackGroupArray groups, int[][] formatSupports, int mixedMimeTypeAdaptationSupports, DefaultTrackSelector.Parameters params, TrackSelection.Factory adaptiveTrackSelectionFactory) Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for an audio renderer.
protected TrackSelection	selectOtherTrack(int trackType, TrackGroupArray groups, int[][] formatSupport, DefaultTrackSelector.Parameters params) Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for a renderer whose type is neither video, audio or text.
protected TrackSelection	selectTextTrack(TrackGroupArray groups, int[][] formatSupport, DefaultTrackSelector.Parameters params) Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for a text renderer.
protected android.util.Pair<RendererConfiguration[],TrackSelection[]>	selectTracks(MappingTrackSelector.MappedTrackInfo mappedTrackInfo, int[][][] rendererFormatSupports, int[] rendererMixedMimeTypeAdaptationSupports) Given mapped track information, returns a track selection and configuration for each renderer.
protected TrackSelection	selectVideoTrack(TrackGroupArray groups, int[][] formatSupports, int mixedMimeTypeAdaptationSupports, DefaultTrackSelector.Parameters params, TrackSelection.Factory adaptiveTrackSelectionFactory) Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for a video renderer.
void	setParameters(DefaultTrackSelector.Parameters parameters) Atomically sets the provided parameters for track selection.
void	setParameters(DefaultTrackSelector.ParametersBuilder parametersBuilder) Atomically sets the provided parameters for track selection.
void	setRendererDisabled(int rendererIndex, boolean disabled) Deprecated. Use DefaultTrackSelector.ParametersBuilder.setRendererDisabled(int, boolean).
void	setSelectionOverride(int rendererIndex, TrackGroupArray groups, DefaultTrackSelector.SelectionOverride override) Deprecated. Use setSelectionOverride(int, TrackGroupArray, SelectionOverride).
void	setTunnelingAudioSessionId(int tunnelingAudioSessionId) Deprecated. Use DefaultTrackSelector.ParametersBuilder.setTunnelingAudioSessionId(int).

Methods inherited from class com.google.android.exoplayer2.trackselection.MappingTrackSelector

getCurrentMappedTrackInfo, onSelectionActivated, selectTracks

Methods inherited from class com.google.android.exoplayer2.trackselection.TrackSelector

init, invalidate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultTrackSelector

public DefaultTrackSelector()

Constructs an instance that does not support adaptive track selection.

DefaultTrackSelector

public DefaultTrackSelector(BandwidthMeter bandwidthMeter)

Constructs an instance that supports adaptive track selection. Adaptive track selections use the provided BandwidthMeter to determine which individual track should be used during playback.

Parameters:

bandwidthMeter - The BandwidthMeter.

DefaultTrackSelector

public DefaultTrackSelector(@Nullable
                            TrackSelection.Factory adaptiveTrackSelectionFactory)

Constructs an instance that uses a factory to create adaptive track selections.

Parameters:

adaptiveTrackSelectionFactory - A factory for adaptive TrackSelections, or null if the selector should not support adaptive tracks.

Method Detail

setParameters

public void setParameters(DefaultTrackSelector.Parameters parameters)

Atomically sets the provided parameters for track selection.

Parameters:

parameters - The parameters for track selection.

setParameters

public void setParameters(DefaultTrackSelector.ParametersBuilder parametersBuilder)

Atomically sets the provided parameters for track selection.

Parameters:

parametersBuilder - A builder from which to obtain the parameters for track selection.

getParameters

public DefaultTrackSelector.Parameters getParameters()

Gets the current selection parameters.

Returns:

The current selection parameters.

buildUponParameters

public DefaultTrackSelector.ParametersBuilder buildUponParameters()

Returns a new DefaultTrackSelector.ParametersBuilder initialized with the current selection parameters.

setRendererDisabled

@Deprecated
public final void setRendererDisabled(int rendererIndex,
                                                  boolean disabled)

Deprecated. Use DefaultTrackSelector.ParametersBuilder.setRendererDisabled(int, boolean).

getRendererDisabled

@Deprecated
public final boolean getRendererDisabled(int rendererIndex)

Deprecated. Use DefaultTrackSelector.Parameters.getRendererDisabled(int). *

setSelectionOverride

@Deprecated
public final void setSelectionOverride(int rendererIndex,
                                                   TrackGroupArray groups,
                                                   DefaultTrackSelector.SelectionOverride override)

Deprecated. Use setSelectionOverride(int, TrackGroupArray, SelectionOverride).

hasSelectionOverride

@Deprecated
public final boolean hasSelectionOverride(int rendererIndex,
                                                      TrackGroupArray groups)

Deprecated. Use DefaultTrackSelector.Parameters.hasSelectionOverride(int, TrackGroupArray). *

getSelectionOverride

@Deprecated
 @Nullable
public final DefaultTrackSelector.SelectionOverride getSelectionOverride(int rendererIndex,
                                                                                                TrackGroupArray groups)

Deprecated. Use DefaultTrackSelector.Parameters.getSelectionOverride(int, TrackGroupArray).

clearSelectionOverride

@Deprecated
public final void clearSelectionOverride(int rendererIndex,
                                                     TrackGroupArray groups)

Deprecated. Use DefaultTrackSelector.ParametersBuilder.clearSelectionOverride(int, TrackGroupArray).

clearSelectionOverrides

@Deprecated
public final void clearSelectionOverrides(int rendererIndex)

Deprecated. Use DefaultTrackSelector.ParametersBuilder.clearSelectionOverrides(int).

clearSelectionOverrides

@Deprecated
public final void clearSelectionOverrides()

Deprecated. Use DefaultTrackSelector.ParametersBuilder.clearSelectionOverrides().

setTunnelingAudioSessionId

@Deprecated
public void setTunnelingAudioSessionId(int tunnelingAudioSessionId)

Deprecated. Use DefaultTrackSelector.ParametersBuilder.setTunnelingAudioSessionId(int).

selectTracks

protected final android.util.Pair<RendererConfiguration[],TrackSelection[]> selectTracks(MappingTrackSelector.MappedTrackInfo mappedTrackInfo,
                                                                                         int[][][] rendererFormatSupports,
                                                                                         int[] rendererMixedMimeTypeAdaptationSupports)
                                                                                  throws ExoPlaybackException

Description copied from class: MappingTrackSelector

Given mapped track information, returns a track selection and configuration for each renderer.

Specified by:

selectTracks in class MappingTrackSelector

Parameters:

mappedTrackInfo - Mapped track information.

rendererFormatSupports - The result of RendererCapabilities.supportsFormat(com.google.android.exoplayer2.Format) for each mapped track, indexed by renderer, track group and track (in that order).

rendererMixedMimeTypeAdaptationSupports - The result of RendererCapabilities.supportsMixedMimeTypeAdaptation() for each renderer.

Returns:

A pair consisting of the track selections and configurations for each renderer. A null configuration indicates the renderer should be disabled, in which case the track selection will also be null. A track selection may also be null for a non-disabled renderer if RendererCapabilities.getTrackType() is C.TRACK_TYPE_NONE.

Throws:

ExoPlaybackException - If an error occurs while selecting the tracks.

selectAllTracks

protected TrackSelection[] selectAllTracks(MappingTrackSelector.MappedTrackInfo mappedTrackInfo,
                                           int[][][] rendererFormatSupports,
                                           int[] rendererMixedMimeTypeAdaptationSupports,
                                           DefaultTrackSelector.Parameters params)
                                    throws ExoPlaybackException

Called from MappingTrackSelector.selectTracks(MappedTrackInfo, int[][][], int[]) to make a track selection for each renderer, prior to overrides and disabled flags being applied.

The implementation should not account for overrides and disabled flags. Track selections generated by this method will be overridden to account for these properties.

Parameters:

mappedTrackInfo - Mapped track information.

rendererFormatSupports - The result of RendererCapabilities.supportsFormat(com.google.android.exoplayer2.Format) for each mapped track, indexed by renderer, track group and track (in that order).

rendererMixedMimeTypeAdaptationSupports - The result of RendererCapabilities.supportsMixedMimeTypeAdaptation() for each renderer.

Returns:

Track selections for each renderer. A null selection indicates the renderer should be disabled, unless RendererCapabilities#getTrackType()} is C.TRACK_TYPE_NONE.

Throws:

ExoPlaybackException - If an error occurs while selecting the tracks.

selectVideoTrack

@Nullable
protected TrackSelection selectVideoTrack(TrackGroupArray groups,
                                                    int[][] formatSupports,
                                                    int mixedMimeTypeAdaptationSupports,
                                                    DefaultTrackSelector.Parameters params,
                                                    @Nullable
                                                    TrackSelection.Factory adaptiveTrackSelectionFactory)
                                             throws ExoPlaybackException

Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for a video renderer.

Parameters:

groups - The TrackGroupArray mapped to the renderer.

formatSupports - The result of RendererCapabilities.supportsFormat(com.google.android.exoplayer2.Format) for each mapped track, indexed by track group index and track index (in that order).

mixedMimeTypeAdaptationSupports - The result of RendererCapabilities.supportsMixedMimeTypeAdaptation() for the renderer.

params - The selector's current constraint parameters.

adaptiveTrackSelectionFactory - A factory for generating adaptive track selections, or null if a fixed track selection is required.

Returns:

The TrackSelection for the renderer, or null if no selection was made.

Throws:

ExoPlaybackException - If an error occurs while selecting the tracks.

selectAudioTrack

@Nullable
protected TrackSelection selectAudioTrack(TrackGroupArray groups,
                                                    int[][] formatSupports,
                                                    int mixedMimeTypeAdaptationSupports,
                                                    DefaultTrackSelector.Parameters params,
                                                    @Nullable
                                                    TrackSelection.Factory adaptiveTrackSelectionFactory)
                                             throws ExoPlaybackException

Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for an audio renderer.

Parameters:

groups - The TrackGroupArray mapped to the renderer.

formatSupports - The result of RendererCapabilities.supportsFormat(com.google.android.exoplayer2.Format) for each mapped track, indexed by track group index and track index (in that order).

mixedMimeTypeAdaptationSupports - The result of RendererCapabilities.supportsMixedMimeTypeAdaptation() for the renderer.

params - The selector's current constraint parameters.

adaptiveTrackSelectionFactory - A factory for generating adaptive track selections, or null if a fixed track selection is required.

Returns:

The TrackSelection for the renderer, or null if no selection was made.

Throws:

ExoPlaybackException - If an error occurs while selecting the tracks.

selectTextTrack

@Nullable
protected TrackSelection selectTextTrack(TrackGroupArray groups,
                                                   int[][] formatSupport,
                                                   DefaultTrackSelector.Parameters params)
                                            throws ExoPlaybackException

Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for a text renderer.

Parameters:

groups - The TrackGroupArray mapped to the renderer.

formatSupport - The result of RendererCapabilities.supportsFormat(com.google.android.exoplayer2.Format) for each mapped track, indexed by track group index and track index (in that order).

params - The selector's current constraint parameters.

Returns:

The TrackSelection for the renderer, or null if no selection was made.

Throws:

ExoPlaybackException - If an error occurs while selecting the tracks.

selectOtherTrack

@Nullable
protected TrackSelection selectOtherTrack(int trackType,
                                                    TrackGroupArray groups,
                                                    int[][] formatSupport,
                                                    DefaultTrackSelector.Parameters params)
                                             throws ExoPlaybackException

Called by #selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters) to create a TrackSelection for a renderer whose type is neither video, audio or text.

Parameters:

trackType - The type of the renderer.

groups - The TrackGroupArray mapped to the renderer.

formatSupport - The result of RendererCapabilities.supportsFormat(com.google.android.exoplayer2.Format) for each mapped track, indexed by track group index and track index (in that order).

params - The selector's current constraint parameters.

Returns:

The TrackSelection for the renderer, or null if no selection was made.

Throws:

ExoPlaybackException - If an error occurs while selecting the tracks.

isSupported

protected static boolean isSupported(int formatSupport,
                                     boolean allowExceedsCapabilities)

Applies the RendererCapabilities.FORMAT_SUPPORT_MASK to a value obtained from RendererCapabilities.supportsFormat(Format), returning true if the result is RendererCapabilities.FORMAT_HANDLED or if allowExceedsCapabilities is set and the result is RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES.

Parameters:

formatSupport - A value obtained from RendererCapabilities.supportsFormat(Format).

allowExceedsCapabilities - Whether to return true if the format support component of the value is RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES.

Returns:

True if the format support component is RendererCapabilities.FORMAT_HANDLED, or if allowExceedsCapabilities is set and the format support component is RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES.

formatHasNoLanguage

protected static boolean formatHasNoLanguage(Format format)

Returns whether a Format does not define a language.

Parameters:

format - The Format.

Returns:

Whether the Format does not define a language.

formatHasLanguage

protected static boolean formatHasLanguage(Format format,
                                           @Nullable
                                           java.lang.String language)

Returns whether a Format specifies a particular language, or false if language is null.

Parameters:

format - The Format.

language - The language.

Returns:

Whether the format specifies the language, or false if language is null.