AdaptiveTrackSelection

Artifact: androidx.media3:media3-exoplayer

View Source

---

Kotlin |Java

@UnstableApi
public class AdaptiveTrackSelection extends BaseTrackSelection

java.lang.Object
↳	androidx.media3.exoplayer.trackselection.BaseTrackSelection
	↳	androidx.media3.exoplayer.trackselection.AdaptiveTrackSelection

---

A bandwidth based adaptive ExoTrackSelection, whose selected track is updated to be the one of highest quality given the current network conditions and the state of the buffer.

Summary

Nested types
public final class AdaptiveTrackSelection.AdaptationCheckpoint Checkpoint to determine allocated bandwidth.
public class AdaptiveTrackSelection.Factory implements ExoTrackSelection.Factory Factory for AdaptiveTrackSelection instances.

Constants
static final float	DEFAULT_BANDWIDTH_FRACTION = 0.7f
static final float	DEFAULT_BUFFERED_FRACTION_TO_LIVE_EDGE_FOR_QUALITY_INCREASE = 0.75f
static final int	DEFAULT_MAX_DURATION_FOR_QUALITY_DECREASE_MS = 25000
static final int	DEFAULT_MAX_HEIGHT_TO_DISCARD = 719
static final int	DEFAULT_MAX_WIDTH_TO_DISCARD = 1279
static final int	DEFAULT_MIN_DURATION_FOR_QUALITY_INCREASE_MS = 10000
static final int	DEFAULT_MIN_DURATION_TO_RETAIN_AFTER_DISCARD_MS = 25000

Public fields
long	latestBitrateEstimate
int	selectedIndex

Protected fields
final long	minDurationToRetainAfterDiscardUs

Public constructors
AdaptiveTrackSelection(     TrackGroup group,     int[] tracks,     BandwidthMeter bandwidthMeter )

Protected constructors

AdaptiveTrackSelection(     TrackGroup group,     int[] tracks,     @TrackSelection.Type int type,     BandwidthMeter bandwidthMeter,     long minDurationForQualityIncreaseMs,     long maxDurationForQualityDecreaseMs,     long minDurationToRetainAfterDiscardMs,     int maxWidthToDiscard,     int maxHeightToDiscard,     float bandwidthFraction,     float bufferedFractionToLiveEdgeForQualityIncrease,     List<AdaptiveTrackSelection.AdaptationCheckpoint> adaptationCheckpoints,     Clock clock )

Public methods
void	@CallSuper disable() Disables this track selection.
void	@CallSuper enable() Enables the track selection.
int	evaluateQueueSize(long playbackPositionUs, List<MediaChunk> queue) Returns the number of chunks that should be retained in the queue.
long	getLatestBitrateEstimate() Returns the most recent bitrate estimate utilised for track selection.
int	getSelectedIndex() Returns the index of the selected track.
@Nullable Object	getSelectionData() Returns optional data associated with the current track selection.
int	@C.SelectionReason getSelectionReason() Returns the reason for the current track selection.
void	onPlaybackSpeed(float playbackSpeed) Called to notify the selection of the current playback speed.
void	updateSelectedTrack(     long playbackPositionUs,     long bufferedDurationUs,     long availableDurationUs,     List<MediaChunk> queue,     MediaChunkIterator[] mediaChunkIterators ) Updates the selected track for sources that load media in discrete MediaChunks.

Protected methods
boolean	canSelectFormat(Format format, int trackBitrate, long effectiveBitrate) Called when updating the selected track to determine whether a candidate track can be selected.
long	getMinDurationToRetainAfterDiscardUs() Called from evaluateQueueSize to determine the minimum duration of buffer to retain after discarding chunks.
boolean	shouldEvaluateQueueSize(long nowMs, List<MediaChunk> queue) Called from evaluateQueueSize to determine whether an evaluation should be performed.

Inherited Constants
From androidx.media3.exoplayer.trackselection.TrackSelection static final int TYPE_CUSTOM_BASE = 10000 The first value that can be used for application specific track selection types. static final int TYPE_UNSET = 0 An unspecified track selection type.

Inherited fields

From androidx.media3.exoplayer.trackselection.BaseTrackSelection final TrackGroup group The selected TrackGroup. final int length The number of selected tracks within the TrackGroup. boolean playWhenReady The current value of whether playback will proceed when ready. final int[] tracks The indices of the selected tracks in group, in order of decreasing bandwidth. final int @TrackSelection.Type type The type of the selection.

Inherited methods
From androidx.media3.exoplayer.trackselection.BaseTrackSelection boolean equals(@Nullable Object obj) boolean excludeTrack(int index, long exclusionDurationMs) Attempts to exclude the track at the specified index in the selection, making it ineligible for selection by calls to updateSelectedTrack for the specified period of time. final Format getFormat(int index) Returns the format of the track at a given index in the selection. final int getIndexInTrackGroup(int index) Returns the index in the track group of the track at a given index in the selection. final boolean getPlayWhenReady() Returns whether the playback using this track selection will proceed when ready. final Format getSelectedFormat() Returns the Format of the individual selected track. final int getSelectedIndexInTrackGroup() Returns the index in the track group of the individual selected track. final TrackGroup getTrackGroup() Returns the TrackGroup to which the selected tracks belong. final int getType() Returns an integer specifying the type of the selection, or TYPE_UNSET if not specified. int hashCode() final int indexOf(Format format) Returns the index in the selection of the track with the specified format. final int indexOf(int indexInTrackGroup) Returns the index in the selection of the track with the specified index in the track group. boolean isTrackExcluded(int index, long nowMs) Returns whether the track at the specified index in the selection is excluded. final int length() Returns the number of tracks in the selection. void @CallSuper onPlayWhenReadyChanged(boolean playWhenReady) Called to notify when the playback is paused or resumed.
From androidx.media3.exoplayer.trackselection.ExoTrackSelection void onDiscontinuity() Called to notify the selection of a position discontinuity. void onRebuffer() Called to notify when a rebuffer occurred. boolean shouldCancelChunkLoad(     long playbackPositionUs,     Chunk loadingChunk,     List<MediaChunk> queue ) Returns whether an ongoing load of a chunk should be canceled.

Constants

DEFAULT_BANDWIDTH_FRACTION

public static final float DEFAULT_BANDWIDTH_FRACTION = 0.7f

DEFAULT_BUFFERED_FRACTION_TO_LIVE_EDGE_FOR_QUALITY_INCREASE

public static final float DEFAULT_BUFFERED_FRACTION_TO_LIVE_EDGE_FOR_QUALITY_INCREASE = 0.75f

DEFAULT_MAX_DURATION_FOR_QUALITY_DECREASE_MS

public static final int DEFAULT_MAX_DURATION_FOR_QUALITY_DECREASE_MS = 25000

DEFAULT_MAX_HEIGHT_TO_DISCARD

public static final int DEFAULT_MAX_HEIGHT_TO_DISCARD = 719

DEFAULT_MAX_WIDTH_TO_DISCARD

public static final int DEFAULT_MAX_WIDTH_TO_DISCARD = 1279

DEFAULT_MIN_DURATION_FOR_QUALITY_INCREASE_MS

public static final int DEFAULT_MIN_DURATION_FOR_QUALITY_INCREASE_MS = 10000

DEFAULT_MIN_DURATION_TO_RETAIN_AFTER_DISCARD_MS

public static final int DEFAULT_MIN_DURATION_TO_RETAIN_AFTER_DISCARD_MS = 25000

Public fields

latestBitrateEstimate

public long latestBitrateEstimate

selectedIndex

public int selectedIndex

Protected fields

minDurationToRetainAfterDiscardUs

protected final long minDurationToRetainAfterDiscardUs

Public constructors

AdaptiveTrackSelection

public AdaptiveTrackSelection(
    TrackGroup group,
    int[] tracks,
    BandwidthMeter bandwidthMeter
)

Parameters
TrackGroup group	The TrackGroup.
int[] tracks	The indices of the selected tracks within the TrackGroup. Must not be empty. May be in any order.
BandwidthMeter bandwidthMeter	Provides an estimate of the currently available bandwidth.

Protected constructors

AdaptiveTrackSelection

protected AdaptiveTrackSelection(
    TrackGroup group,
    int[] tracks,
    @TrackSelection.Type int type,
    BandwidthMeter bandwidthMeter,
    long minDurationForQualityIncreaseMs,
    long maxDurationForQualityDecreaseMs,
    long minDurationToRetainAfterDiscardMs,
    int maxWidthToDiscard,
    int maxHeightToDiscard,
    float bandwidthFraction,
    float bufferedFractionToLiveEdgeForQualityIncrease,
    List<AdaptiveTrackSelection.AdaptationCheckpoint> adaptationCheckpoints,
    Clock clock
)

Parameters
TrackGroup group	The TrackGroup.
int[] tracks	The indices of the selected tracks within the TrackGroup. Must not be empty. May be in any order.
@TrackSelection.Type int type	The type that will be returned from getType.
BandwidthMeter bandwidthMeter	Provides an estimate of the currently available bandwidth.
long minDurationForQualityIncreaseMs	The minimum duration of buffered data required for the selected track to switch to one of higher quality.
long maxDurationForQualityDecreaseMs	The maximum duration of buffered data required for the selected track to switch to one of lower quality.
long minDurationToRetainAfterDiscardMs	When switching to a video track of higher quality, the selection may indicate that media already buffered at the lower quality can be discarded to speed up the switch. This is the minimum duration of media that must be retained at the lower quality. It must be at least minDurationForQualityIncreaseMs.
int maxWidthToDiscard	The maximum video width that the selector may discard from the buffer to speed up switching to a higher quality.
int maxHeightToDiscard	The maximum video height that the selector may discard from the buffer to speed up switching to a higher quality.
float bandwidthFraction	The fraction of the available bandwidth that the selection should consider available for use. Setting to a value less than 1 is recommended to account for inaccuracies in the bandwidth estimator.
float bufferedFractionToLiveEdgeForQualityIncrease	For live streaming, the fraction of the duration from current playback position to the live edge that has to be buffered before the selected track can be switched to one of higher quality. This parameter is only applied when the playback position is closer to the live edge than minDurationForQualityIncreaseMs, which would otherwise prevent switching to a higher quality from happening.
List<AdaptiveTrackSelection.AdaptationCheckpoint> adaptationCheckpoints	The checkpoints that can be used to calculate available bandwidth for this selection.
Clock clock	The Clock.

Public methods

disable

@CallSuper
public void disable()

Disables this track selection. No further dynamic changes via updateSelectedTrack, evaluateQueueSize or shouldCancelChunkLoad will happen after this call.

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

enable

@CallSuper
public void enable()

Enables the track selection. Dynamic changes via updateSelectedTrack, evaluateQueueSize or shouldCancelChunkLoad will only happen after this call.

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

evaluateQueueSize

public int evaluateQueueSize(long playbackPositionUs, List<MediaChunk> queue)

Returns the number of chunks that should be retained in the queue.

May be called by sources that load media in discrete MediaChunks and support discarding of buffered chunks.

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.

Note that even if the source supports discarding of buffered chunks, the actual number of discarded chunks is not guaranteed. The source will call updateSelectedTrack with the updated queue of chunks before loading a new chunk to allow switching to another quality.

This method will only be called when the selection is enabled and none of the MediaChunks in the queue are currently loading.

Parameters
long 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.
List<MediaChunk> queue	The queue of buffered MediaChunks. Must not be modified.

Returns
int	The number of chunks to retain in the queue.

getLatestBitrateEstimate

public long getLatestBitrateEstimate()

Returns the most recent bitrate estimate utilised for track selection.

The default behavior is to return RATE_UNSET_INT, indicating that the bitrate estimate was not computed for the track selection decision.

getSelectedIndex

public int getSelectedIndex()

Returns the index of the selected track.

getSelectionData

public @Nullable Object getSelectionData()

Returns optional data associated with the current track selection.

getSelectionReason

@C.SelectionReason
public int getSelectionReason()

Returns the reason for the current track selection.

onPlaybackSpeed

public void onPlaybackSpeed(float playbackSpeed)

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

Parameters
float playbackSpeed	The factor by which playback is sped up.

updateSelectedTrack

public void updateSelectedTrack(
    long playbackPositionUs,
    long bufferedDurationUs,
    long availableDurationUs,
    List<MediaChunk> queue,
    MediaChunkIterator[] mediaChunkIterators
)

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

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

Parameters
long 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.
long 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).
long availableDurationUs	The duration of media available for buffering from the current playback position, in microseconds, or TIME_UNSET if media can be buffered to the end of the current period. Note that if not set to TIME_UNSET, the position up to which media is available for buffering can be calculated as (playbackPositionUs + availableDurationUs).
List<MediaChunk> queue	The queue of already buffered MediaChunks. Must not be modified.
MediaChunkIterator[] 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.

Protected methods

canSelectFormat

protected boolean canSelectFormat(Format format, int trackBitrate, long effectiveBitrate)

Called when updating the selected track to determine whether a candidate track can be selected.

Parameters
Format format	The Format of the candidate track.
int trackBitrate	The estimated bitrate of the track. May differ from bitrate if a more accurate estimate of the current track bitrate is available.
long effectiveBitrate	The bitrate available to this selection.

Returns
boolean	Whether this Format can be selected.

getMinDurationToRetainAfterDiscardUs

protected long getMinDurationToRetainAfterDiscardUs()

Called from evaluateQueueSize to determine the minimum duration of buffer to retain after discarding chunks.

Returns
long	The minimum duration of buffer to retain after discarding chunks, in microseconds.

shouldEvaluateQueueSize

protected boolean shouldEvaluateQueueSize(long nowMs, List<MediaChunk> queue)

Called from evaluateQueueSize to determine whether an evaluation should be performed.

Parameters
long nowMs	The current value of elapsedRealtime.
List<MediaChunk> queue	The queue of buffered MediaChunks. Must not be modified.

Returns
boolean	Whether an evaluation should be performed.