Class TrackSelector
- java.lang.Object
-
- com.google.android.exoplayer2.trackselection.TrackSelector
-
- Direct Known Subclasses:
MappingTrackSelector
public abstract class TrackSelector extends Object
The component of anExoPlayer
responsible for selecting tracks to be consumed by each of the player'sRenderer
s. TheDefaultTrackSelector
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(InvalidationListener, BandwidthMeter)
. - When the player needs to make a track selection it will call
selectTracks(RendererCapabilities[], TrackGroupArray, MediaPeriodId, Timeline)
. 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(Object)
. - If the track selector wishes to indicate to the player that selections it has previously
made are invalid, it can do so by calling
TrackSelector.InvalidationListener.onTrackSelectionsInvalidated()
on theTrackSelector.InvalidationListener
that was passed toinit(InvalidationListener, BandwidthMeter)
. A track selector may wish to do this if its configuration has changed, for example if it now wishes to prefer audio tracks in a particular language. This will trigger the player to make new track selections. Note that the player will have to re-buffer in the case that the new track selection for the currently playing period differs from the one that was invalidated. Implementing subclasses can trigger invalidation by callinginvalidate()
, which will callTrackSelector.InvalidationListener.onTrackSelectionsInvalidated()
.
Renderer configuration
TheTrackSelectorResult
returned byselectTracks(RendererCapabilities[], TrackGroupArray, MediaPeriodId, Timeline)
contains not onlyTrackSelection
s for each renderer, but alsoRendererConfiguration
s 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 calls made by the player into the track selector are on the player's internal playback thread. The track selector may callTrackSelector.InvalidationListener.onTrackSelectionsInvalidated()
from any thread.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
TrackSelector.InvalidationListener
Notified when selections previously made by aTrackSelector
are no longer valid.
-
Constructor Summary
Constructors Constructor Description TrackSelector()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description protected BandwidthMeter
getBandwidthMeter()
Returns a bandwidth meter which can be used by track selections to select tracks.TrackSelectionParameters
getParameters()
Returns the current parameters for track selection.void
init(TrackSelector.InvalidationListener listener, BandwidthMeter bandwidthMeter)
Called by the player to initialize the selector.protected void
invalidate()
CallsTrackSelector.InvalidationListener.onTrackSelectionsInvalidated()
to invalidate all previously generated track selections.boolean
isSetParametersSupported()
Returns if thisTrackSelector
supportssetParameters(TrackSelectionParameters)
.abstract void
onSelectionActivated(Object info)
Called by the player when aTrackSelectorResult
previously generated byselectTracks(RendererCapabilities[], TrackGroupArray, MediaPeriodId, Timeline)
is activated.abstract TrackSelectorResult
selectTracks(RendererCapabilities[] rendererCapabilities, TrackGroupArray trackGroups, MediaSource.MediaPeriodId periodId, Timeline timeline)
Called by the player to perform a track selection.void
setParameters(TrackSelectionParameters parameters)
Called by the player to provide parameters for track selection.
-
-
-
Method Detail
-
init
public final void init(TrackSelector.InvalidationListener listener, BandwidthMeter bandwidthMeter)
Called by the player to initialize the selector.- Parameters:
listener
- An invalidation listener that the selector can call to indicate that selections it has previously made are no longer valid.bandwidthMeter
- A bandwidth meter which can be used by track selections to select tracks.
-
selectTracks
public abstract TrackSelectorResult selectTracks(RendererCapabilities[] rendererCapabilities, TrackGroupArray trackGroups, MediaSource.MediaPeriodId periodId, Timeline timeline) throws ExoPlaybackException
Called by the player to perform a track selection.- Parameters:
rendererCapabilities
- TheRendererCapabilities
of the renderers for which tracks are to be selected.trackGroups
- The available track groups.periodId
- TheMediaSource.MediaPeriodId
of the period for which tracks are to be selected.timeline
- TheTimeline
holding the period for which tracks are to be selected.- Returns:
- A
TrackSelectorResult
describing the track selections. - Throws:
ExoPlaybackException
- If an error occurs selecting tracks.
-
onSelectionActivated
public abstract void onSelectionActivated(@Nullable Object info)
Called by the player when aTrackSelectorResult
previously generated byselectTracks(RendererCapabilities[], TrackGroupArray, MediaPeriodId, Timeline)
is activated.- Parameters:
info
- The value ofTrackSelectorResult.info
in the activated selection.
-
getParameters
public TrackSelectionParameters getParameters()
Returns the current parameters for track selection.
-
setParameters
public void setParameters(TrackSelectionParameters parameters)
Called by the player to provide parameters for track selection.Only supported if
isSetParametersSupported()
returns true.- Parameters:
parameters
- The parameters for track selection.
-
isSetParametersSupported
public boolean isSetParametersSupported()
Returns if thisTrackSelector
supportssetParameters(TrackSelectionParameters)
.The same value is always returned for a given
TrackSelector
instance.
-
invalidate
protected final void invalidate()
CallsTrackSelector.InvalidationListener.onTrackSelectionsInvalidated()
to invalidate all previously generated track selections.
-
getBandwidthMeter
protected final BandwidthMeter getBandwidthMeter()
Returns a bandwidth meter which can be used by track selections to select tracks. Must only be called afterinit(InvalidationListener, BandwidthMeter)
has been called.
-
-