com.google.android.exoplayer2.trackselection

Interface TrackSelection

All Known Implementing Classes:

AdaptiveTrackSelection, BaseTrackSelection, FixedTrackSelection, RandomTrackSelection

public interface TrackSelection

A track selection consisting of a static subset of selected tracks belonging to a TrackGroup, and a possibly varying individual selected track from the subset.

Tracks belonging to the subset are exposed in decreasing bandwidth order. The individual selected track may change as a result of calling updateSelectedTrack(long, long, long, List, MediaChunkIterator[]).

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	TrackSelection.Factory Factory for TrackSelection instances.

Method Summary

Modifier and Type	Method and Description
boolean	blacklist(int index, long blacklistDurationMs) Attempts to blacklist the track at the specified index in the selection, making it ineligible for selection by calls to updateSelectedTrack(long, long, long, List, MediaChunkIterator[]) for the specified period of time.
void	disable() Disables this track selection.
void	enable() Enables the track selection.
int	evaluateQueueSize(long playbackPositionUs, java.util.List<? extends MediaChunk> queue) May be called periodically by sources that load media in discrete MediaChunks and support discarding of buffered chunks in order to re-buffer using a different selected track.
Format	getFormat(int index) Returns the format of the track at a given index in the selection.
int	getIndexInTrackGroup(int index) Returns the index in the track group of the track at a given index in the selection.
Format	getSelectedFormat() Returns the Format of the individual selected track.
int	getSelectedIndex() Returns the index of the selected track.
int	getSelectedIndexInTrackGroup() Returns the index in the track group of the individual selected track.
java.lang.Object	getSelectionData() Returns optional data associated with the current track selection.
int	getSelectionReason() Returns the reason for the current track selection.
TrackGroup	getTrackGroup() Returns the TrackGroup to which the selected tracks belong.
int	indexOf(Format format) Returns the index in the selection of the track with the specified format.
int	indexOf(int indexInTrackGroup) Returns the index in the selection of the track with the specified index in the track group.
int	length() Returns the number of tracks in the selection.
void	onPlaybackSpeed(float speed) Called to notify the selection of the current playback speed.
default void	updateSelectedTrack(long playbackPositionUs, long bufferedDurationUs, long availableDurationUs) Deprecated. Use and implement updateSelectedTrack(long, long, long, List, MediaChunkIterator[]) instead.
default void	updateSelectedTrack(long playbackPositionUs, long bufferedDurationUs, long availableDurationUs, java.util.List<? extends MediaChunk> queue, MediaChunkIterator[] mediaChunkIterators) Updates the selected track for sources that load media in discrete MediaChunks.

Method Detail

enable

void enable()

Enables the track selection.

This method may not be called when the track selection is already enabled.

disable

void disable()

Disables this track selection.

This method may only be called when the track selection is already enabled.

getTrackGroup

TrackGroup getTrackGroup()

Returns the TrackGroup to which the selected tracks belong.

length

int length()

Returns the number of tracks in the selection.

getFormat

Format getFormat(int index)

Returns the format of the track at a given index in the selection.

Parameters:

index - The index in the selection.

Returns:

The format of the selected track.

getIndexInTrackGroup

int getIndexInTrackGroup(int index)

Returns the index in the track group of the track at a given index in the selection.

Parameters:

index - The index in the selection.

Returns:

The index of the selected track.

indexOf

int indexOf(Format format)

Returns the index in the selection of the track with the specified format. The format is located by identity so, for example, selection.indexOf(selection.getFormat(index)) == index even if multiple selected tracks have formats that contain the same values.

Parameters:

format - The format.

Returns:

The index in the selection, or C.INDEX_UNSET if the track with the specified format is not part of the selection.

indexOf

int indexOf(int indexInTrackGroup)

Returns the index in the selection of the track with the specified index in the track group.

Parameters:

indexInTrackGroup - The index in the track group.

Returns:

The index in the selection, or C.INDEX_UNSET if the track with the specified index is not part of the selection.

getSelectedFormat

Format getSelectedFormat()

Returns the Format of the individual selected track.

getSelectedIndexInTrackGroup

int getSelectedIndexInTrackGroup()

Returns the index in the track group of the individual selected track.

getSelectedIndex

int getSelectedIndex()

Returns the index of the selected track.

getSelectionReason

int getSelectionReason()

Returns the reason for the current track selection.

getSelectionData

@Nullable
java.lang.Object getSelectionData()

Returns optional data associated with the current track selection.

onPlaybackSpeed

void onPlaybackSpeed(float speed)

Called to notify the selection of the current playback speed. The playback speed may affect adaptive track selection.

Parameters:

speed - The playback speed.

updateSelectedTrack

@Deprecated
default void updateSelectedTrack(long playbackPositionUs,
                                             long bufferedDurationUs,
                                             long availableDurationUs)

Deprecated. Use and implement updateSelectedTrack(long, long, long, List, MediaChunkIterator[]) instead.

updateSelectedTrack

default void updateSelectedTrack(long playbackPositionUs,
                                 long bufferedDurationUs,
                                 long availableDurationUs,
                                 java.util.List<? extends MediaChunk> queue,
                                 MediaChunkIterator[] mediaChunkIterators)

Updates the selected track for sources that load media in discrete MediaChunks.

This method may only be called when the selection is enabled.

Parameters:

playbackPositionUs - The current playback position in microseconds. If playback of the period to which this track selection belongs has not yet started, the value will be the starting position in the period minus the duration of any media in previous periods still to be played.

bufferedDurationUs - The duration of media currently buffered from the current playback position, in microseconds. Note that the next load position can be calculated as (playbackPositionUs + bufferedDurationUs).

availableDurationUs - The duration of media available for buffering from the current playback position, in microseconds, or C.TIME_UNSET if media can be buffered to the end of the current period. Note that if not set to C.TIME_UNSET, the position up to which media is available for buffering can be calculated as (playbackPositionUs + availableDurationUs).

queue - The queue of already buffered MediaChunks. Must not be modified.

mediaChunkIterators - An array of MediaChunkIterators providing information about the sequence of upcoming media chunks for each track in the selection. All iterators start from the media chunk which will be loaded next if the respective track is selected. Note that this information may not be available for all tracks, and so some iterators may be empty.

evaluateQueueSize

int evaluateQueueSize(long playbackPositionUs,
                      java.util.List<? extends MediaChunk> queue)

May be called periodically by sources that load media in discrete MediaChunks and support discarding of buffered chunks in order to re-buffer using a different selected track. Returns the number of chunks that should be retained in the queue.

To avoid excessive re-buffering, implementations should normally return the size of the queue. An example of a case where a smaller value may be returned is if network conditions have improved dramatically, allowing chunks to be discarded and re-buffered in a track of significantly higher quality. Discarding chunks may allow faster switching to a higher quality track in this case. This method may only be called when the selection is enabled.

Parameters:

playbackPositionUs - The current playback position in microseconds. If playback of the period to which this track selection belongs has not yet started, the value will be the starting position in the period minus the duration of any media in previous periods still to be played.

queue - The queue of buffered MediaChunks. Must not be modified.

Returns:

The number of chunks to retain in the queue.

blacklist

boolean blacklist(int index,
                  long blacklistDurationMs)

Attempts to blacklist the track at the specified index in the selection, making it ineligible for selection by calls to updateSelectedTrack(long, long, long, List, MediaChunkIterator[]) for the specified period of time. Blacklisting will fail if all other tracks are currently blacklisted. If blacklisting the currently selected track, note that it will remain selected until the next call to updateSelectedTrack(long, long, long, List, MediaChunkIterator[]).

This method may only be called when the selection is enabled.

Parameters:

index - The index of the track in the selection.

blacklistDurationMs - The duration of time for which the track should be blacklisted, in milliseconds.

Returns:

Whether blacklisting was successful.