@UnstableApi
abstract class TrackSelector

Known direct subclasses
MappingTrackSelector

Base class for TrackSelectors that first establish a mapping between TrackGroups and Renderers, and then from that mapping create a ExoTrackSelection for each renderer.
Known indirect subclasses
DefaultTrackSelector

A default TrackSelector suitable for most use cases.
FakeTrackSelector

A fake MappingTrackSelector that returns FakeTrackSelections.

The component of an ExoPlayer responsible for selecting tracks to be consumed by each of the player's Renderers. The DefaultTrackSelector implementation should be suitable for most use cases.

Interactions with the player

The following interactions occur between the player and its track selector during playback.
  • When the player is created it will initialize the track selector by calling init.
  • When the player needs to make a track selection it will call selectTracks. This typically occurs at the start of playback, when the player starts to buffer a new period of the media being played, and when the track selector invalidates its previous selections.
  • The player may perform a track selection well in advance of the selected tracks becoming active, where active is defined to mean that the renderers are actually consuming media corresponding to the selection that was made. For example when playing media containing multiple periods, the track selection for a period is made when the player starts to buffer that period. Hence if the player's buffering policy is to maintain a 30 second buffer, the selection will occur approximately 30 seconds in advance of it becoming active. In fact the selection may never become active, for example if the user seeks to some other period of the media during the 30 second gap. The player indicates to the track selector when a selection it has previously made becomes active by calling onSelectionActivated.
  • When the track selector's configuration changes (for example, if it now wishes to prefer audio tracks in a particular language) or its previous selections become invalid, it can trigger invalidation by calling invalidate. This invokes onTrackSelectionsInvalidated on the InvalidationListener that was passed to init. When handling this callback, if parameters is not null, the listener must call onParametersActivated to activate the updated parameters before triggering the player to make new track selections. Note that the player will have to re-buffer if the new track selection for the currently playing period differs from the one that was invalidated.
  • When the player is released, it will release the track selector by calling release.

Track selection parameters

Track selection parameters can be retrieved and modified on the application thread by calling getParameters and setParameters respectively (if supported, as indicated by isSetParametersSupported). Modifying parameters on the application thread triggers the invalidation flow described above, ensuring that the updated parameters are activated and applied on the playback thread.

Renderer configuration

The TrackSelectorResult returned by selectTracks contains not only TrackSelections for each renderer, but also RendererConfigurations defining configuration parameters that the renderers should apply when consuming the corresponding media. Whilst it may seem counter- intuitive for a track selector to also specify renderer configuration information, in practice the two are tightly bound together. It may only be possible to play a certain combination tracks if the renderers are configured in a particular way. Equally, it may only be possible to configure renderers in a particular way if certain tracks are selected. Hence it makes sense to determine the track selection and corresponding renderer configurations in a single step.

Threading model

All methods must be called on the same playback thread, except for those specifically documented to be called on a separate application thread.

Summary

Nested types

Factory for creating track selectors from contexts.

Notified when selections previously made by a TrackSelector are no longer valid.

Public constructors

Public functions
TrackSelectionParameters!

Returns the current parameters for track selection.
RendererCapabilities.Listener?

Returns the RendererCapabilities.Listener that the concrete instance uses to listen to the renderer capabilities changes.
Unit
@CallSuper
init(
    listener: TrackSelector.InvalidationListener!,
    bandwidthMeter: BandwidthMeter!
)

Called by the player to initialize the selector.
Boolean

Returns if this TrackSelector supports setParameters.
Unit

Called by the player when track selection parameters become active for subsequent track selections made by selectTracks.
abstract Unit

Called by the player when a TrackSelectorResult previously generated by selectTracks is activated.
Unit

Called by the player to release the selector.
abstract TrackSelectorResult!
selectTracks(
    rendererCapabilities: Array<RendererCapabilities!>!,
    trackGroups: TrackGroupArray!,
    periodId: MediaSource.MediaPeriodId!,
    timeline: Timeline!
)

Called by the player to perform a track selection.
Unit

Called by the player to set the AudioAttributes that will be used for playback.
Unit

Called by the player to provide parameters for track selection.

Protected functions
Unit

Calls onTrackSelectionsInvalidated to invalidate all previously generated track selections.
Unit

Calls onRendererCapabilitiesChanged to invalidate all previously generated track selections because a renderer's capabilities have changed.

Protected properties
BandwidthMeter?

Public constructors

TrackSelector

TrackSelector()

Public functions

getParameters

fun getParameters(): TrackSelectionParameters!

Returns the current parameters for track selection.

This method must be called from the application thread.

getRendererCapabilitiesListener

fun getRendererCapabilitiesListener(): RendererCapabilities.Listener?

Returns the RendererCapabilities.Listener that the concrete instance uses to listen to the renderer capabilities changes. May be null if the implementation does not listen to the renderer capabilities changes.

init

@CallSuper
fun init(
    listener: TrackSelector.InvalidationListener!,
    bandwidthMeter: BandwidthMeter!
): Unit

Called by the player to initialize the selector.

This method must be called from the application thread.

Parameters
listener: TrackSelector.InvalidationListener!

An invalidation listener that the selector can call to indicate that selections it has previously made are no longer valid.
bandwidthMeter: BandwidthMeter!

A bandwidth meter which can be used by track selections to select tracks.

isSetParametersSupported

fun isSetParametersSupported(): Boolean

Returns if this TrackSelector supports setParameters.

The same value is always returned for a given TrackSelector instance.

This method must be called from the application thread.

onParametersActivated

fun onParametersActivated(parameters: TrackSelectionParameters?): Unit

Called by the player when track selection parameters become active for subsequent track selections made by selectTracks.

Parameters
parameters: TrackSelectionParameters?

The activated track selection parameters, or null if no new parameters need to be activated.

onSelectionActivated

abstract fun onSelectionActivated(info: Any?): Unit

Called by the player when a TrackSelectorResult previously generated by selectTracks is activated.

Parameters
info: Any?

The value of info in the activated selection.

release

@CallSuper
fun release(): Unit

Called by the player to release the selector. The selector cannot be used until init is called again.

selectTracks

abstract fun selectTracks(
    rendererCapabilities: Array<RendererCapabilities!>!,
    trackGroups: TrackGroupArray!,
    periodId: MediaSource.MediaPeriodId!,
    timeline: Timeline!
): TrackSelectorResult!

Called by the player to perform a track selection.

Parameters
rendererCapabilities: Array<RendererCapabilities!>!

The RendererCapabilities of the renderers for which tracks are to be selected.
trackGroups: TrackGroupArray!

The available track groups.
periodId: MediaSource.MediaPeriodId!

The MediaPeriodId of the period for which tracks are to be selected.
timeline: Timeline!

The Timeline holding the period for which tracks are to be selected.
Returns
TrackSelectorResult!

A TrackSelectorResult describing the track selections.
Throws
androidx.media3.exoplayer.ExoPlaybackException

If an error occurs selecting tracks.

setAudioAttributes

fun setAudioAttributes(audioAttributes: AudioAttributes!): Unit

Called by the player to set the AudioAttributes that will be used for playback.

setParameters

fun setParameters(parameters: TrackSelectionParameters!): Unit

Called by the player to provide parameters for track selection.

Only supported if isSetParametersSupported returns true.

This method must be called from the application thread.

Parameters
parameters: TrackSelectionParameters!

The parameters for track selection.

Protected functions

invalidate

protected fun invalidate(parameters: TrackSelectionParameters?): Unit

Calls onTrackSelectionsInvalidated to invalidate all previously generated track selections.

This method can be called from both the application and the playback thread.

Parameters
parameters: TrackSelectionParameters?

The track selection parameters, or null to re-evaluate selections without applying new parameters.

invalidateForRendererCapabilitiesChange

protected fun invalidateForRendererCapabilitiesChange(renderer: Renderer!): Unit

Calls onRendererCapabilitiesChanged to invalidate all previously generated track selections because a renderer's capabilities have changed.

Parameters
renderer: Renderer!

The renderer whose capabilities changed.

Protected properties

bandwidthMeter

protected val bandwidthMeter: BandwidthMeter?