AdaptiveTrackSelection

@UnstableApi
class AdaptiveTrackSelection : BaseTrackSelection

kotlin.Any
   ↳ 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

Checkpoint to determine allocated bandwidth.

Factory for AdaptiveTrackSelection instances.

Constants
const Float
const Float
const Int
const Int
const Int
const Int
const Int

Public constructors
AdaptiveTrackSelection(
    group: TrackGroup!,
    tracks: IntArray!,
    bandwidthMeter: BandwidthMeter!
)

Protected constructors
AdaptiveTrackSelection(
    group: TrackGroup!,
    tracks: IntArray!,
    @TrackSelection.Type type: Int,
    bandwidthMeter: BandwidthMeter!,
    minDurationForQualityIncreaseMs: Long,
    maxDurationForQualityDecreaseMs: Long,
    minDurationToRetainAfterDiscardMs: Long,
    maxWidthToDiscard: Int,
    maxHeightToDiscard: Int,
    bandwidthFraction: Float,
    bufferedFractionToLiveEdgeForQualityIncrease: Float,
    adaptationCheckpoints: (Mutable)List<AdaptiveTrackSelection.AdaptationCheckpoint!>!,
    clock: Clock!
)

Public functions
Unit

Disables this track selection.
Unit

Enables the track selection.
Int
evaluateQueueSize(
    playbackPositionUs: Long,
    queue: (Mutable)List<MediaChunk!>!
)

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

Returns optional data associated with the current track selection.
Int

Returns the reason for the current track selection.
Unit
onPlaybackSpeed(playbackSpeed: Float)

Called to notify the selection of the current playback speed.
Unit
updateSelectedTrack(
    playbackPositionUs: Long,
    bufferedDurationUs: Long,
    availableDurationUs: Long,
    queue: (Mutable)List<MediaChunk!>!,
    mediaChunkIterators: Array<MediaChunkIterator!>!
)

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

Protected functions
Boolean
canSelectFormat(format: Format!, trackBitrate: Int, effectiveBitrate: Long)

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

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

Public properties
Long
Int

Protected properties
Long

Inherited Constants
From androidx.media3.exoplayer.trackselection.TrackSelection
const Int

The first value that can be used for application specific track selection types.
const Int

An unspecified track selection type.

Inherited functions
From androidx.media3.exoplayer.trackselection.BaseTrackSelection
Boolean
equals(obj: Any?)
Boolean
excludeTrack(index: Int, exclusionDurationMs: Long)

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.
Format!
getFormat(index: Int)

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

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

Returns the Format of the individual selected track.
Int

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

Returns the TrackGroup to which the selected tracks belong.
Int
Int
indexOf(format: Format!)

Returns the index in the selection of the track with the specified format.
Int
indexOf(indexInTrackGroup: Int)

Returns the index in the selection of the track with the specified index in the track group.
Boolean
isTrackExcluded(index: Int, nowMs: Long)

Returns whether the track at the specified index in the selection is excluded.
Int

Returns the number of tracks in the selection.
Unit

Called to notify when the playback is paused or resumed.
From androidx.media3.exoplayer.trackselection.ExoTrackSelection
Unit

Called to notify the selection of a position discontinuity.
Unit

Called to notify when a rebuffer occurred.
Boolean
shouldCancelChunkLoad(
    playbackPositionUs: Long,
    loadingChunk: Chunk!,
    queue: (Mutable)List<MediaChunk!>!
)

Returns whether an ongoing load of a chunk should be canceled.

Inherited properties
From androidx.media3.exoplayer.trackselection.BaseTrackSelection
TrackGroup!

The selected TrackGroup.
Int

The number of selected tracks within the TrackGroup.
Boolean

The current value of whether playback will proceed when ready.
IntArray<Int>!

The indices of the selected tracks in group, in order of decreasing bandwidth.
Int

The type of the selection.

Constants

DEFAULT_BANDWIDTH_FRACTION

const val DEFAULT_BANDWIDTH_FRACTION = 0.7f: Float

DEFAULT_BUFFERED_FRACTION_TO_LIVE_EDGE_FOR_QUALITY_INCREASE

const val DEFAULT_BUFFERED_FRACTION_TO_LIVE_EDGE_FOR_QUALITY_INCREASE = 0.75f: Float

DEFAULT_MAX_DURATION_FOR_QUALITY_DECREASE_MS

const val DEFAULT_MAX_DURATION_FOR_QUALITY_DECREASE_MS = 25000: Int

DEFAULT_MAX_HEIGHT_TO_DISCARD

const val DEFAULT_MAX_HEIGHT_TO_DISCARD = 719: Int

DEFAULT_MAX_WIDTH_TO_DISCARD

const val DEFAULT_MAX_WIDTH_TO_DISCARD = 1279: Int

DEFAULT_MIN_DURATION_FOR_QUALITY_INCREASE_MS

const val DEFAULT_MIN_DURATION_FOR_QUALITY_INCREASE_MS = 10000: Int

DEFAULT_MIN_DURATION_TO_RETAIN_AFTER_DISCARD_MS

const val DEFAULT_MIN_DURATION_TO_RETAIN_AFTER_DISCARD_MS = 25000: Int

Public constructors

AdaptiveTrackSelection

AdaptiveTrackSelection(
    group: TrackGroup!,
    tracks: IntArray!,
    bandwidthMeter: BandwidthMeter!
)
Parameters
group: TrackGroup!

The TrackGroup.
tracks: IntArray!

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(
    group: TrackGroup!,
    tracks: IntArray!,
    @TrackSelection.Type type: Int,
    bandwidthMeter: BandwidthMeter!,
    minDurationForQualityIncreaseMs: Long,
    maxDurationForQualityDecreaseMs: Long,
    minDurationToRetainAfterDiscardMs: Long,
    maxWidthToDiscard: Int,
    maxHeightToDiscard: Int,
    bandwidthFraction: Float,
    bufferedFractionToLiveEdgeForQualityIncrease: Float,
    adaptationCheckpoints: (Mutable)List<AdaptiveTrackSelection.AdaptationCheckpoint!>!,
    clock: Clock!
)
Parameters
group: TrackGroup!

The TrackGroup.
tracks: IntArray!

The indices of the selected tracks within the TrackGroup. Must not be empty. May be in any order.
@TrackSelection.Type type: Int

The type that will be returned from getType.
bandwidthMeter: BandwidthMeter!

Provides an estimate of the currently available bandwidth.
minDurationForQualityIncreaseMs: Long

The minimum duration of buffered data required for the selected track to switch to one of higher quality.
maxDurationForQualityDecreaseMs: Long

The maximum duration of buffered data required for the selected track to switch to one of lower quality.
minDurationToRetainAfterDiscardMs: Long

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.
maxWidthToDiscard: Int

The maximum video width that the selector may discard from the buffer to speed up switching to a higher quality.
maxHeightToDiscard: Int

The maximum video height that the selector may discard from the buffer to speed up switching to a higher quality.
bandwidthFraction: Float

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.
bufferedFractionToLiveEdgeForQualityIncrease: Float

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.
adaptationCheckpoints: (Mutable)List<AdaptiveTrackSelection.AdaptationCheckpoint!>!

The checkpoints that can be used to calculate available bandwidth for this selection.
clock: Clock!

The Clock.

Public functions

disable

@CallSuper
fun disable(): Unit

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
fun enable(): Unit

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

fun evaluateQueueSize(
    playbackPositionUs: Long,
    queue: (Mutable)List<MediaChunk!>!
): Int

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
playbackPositionUs: Long

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: (Mutable)List<MediaChunk!>!

The queue of buffered MediaChunks. Must not be modified.
Returns
Int

The number of chunks to retain in the queue.

getSelectionData

fun getSelectionData(): Any?

Returns optional data associated with the current track selection.

getSelectionReason

@C.SelectionReason
fun getSelectionReason(): Int

Returns the reason for the current track selection.

onPlaybackSpeed

fun onPlaybackSpeed(playbackSpeed: Float): Unit

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

Parameters
playbackSpeed: Float

The factor by which playback is sped up.

updateSelectedTrack

fun updateSelectedTrack(
    playbackPositionUs: Long,
    bufferedDurationUs: Long,
    availableDurationUs: Long,
    queue: (Mutable)List<MediaChunk!>!,
    mediaChunkIterators: Array<MediaChunkIterator!>!
): Unit

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

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

Parameters
playbackPositionUs: Long

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: Long

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: Long

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).
queue: (Mutable)List<MediaChunk!>!

The queue of already buffered MediaChunks. Must not be modified.
mediaChunkIterators: Array<MediaChunkIterator!>!

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 functions

canSelectFormat

protected fun canSelectFormat(format: Format!, trackBitrate: Int, effectiveBitrate: Long): Boolean

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

Parameters
format: Format!

The Format of the candidate track.
trackBitrate: Int

The estimated bitrate of the track. May differ from bitrate if a more accurate estimate of the current track bitrate is available.
effectiveBitrate: Long

The bitrate available to this selection.
Returns
Boolean

Whether this Format can be selected.

shouldEvaluateQueueSize

protected fun shouldEvaluateQueueSize(nowMs: Long, queue: (Mutable)List<MediaChunk!>!): Boolean

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

Parameters
nowMs: Long

The current value of elapsedRealtime.
queue: (Mutable)List<MediaChunk!>!

The queue of buffered MediaChunks. Must not be modified.
Returns
Boolean

Whether an evaluation should be performed.

Public properties

latestBitrateEstimate

val latestBitrateEstimate: Long

selectedIndex

val selectedIndex: Int

Protected properties

minDurationToRetainAfterDiscardUs

protected val minDurationToRetainAfterDiscardUs: Long