DefaultLoadControl

@UnstableApi
public class DefaultLoadControl implements LoadControl

The default LoadControl implementation.

Summary

Nested types
public final class DefaultLoadControl.Builder

Builder for DefaultLoadControl.

Constants
static final int

A default size in bytes for an audio buffer.
static final int

The default back buffer duration in milliseconds.
static final int

The default duration of media that must be buffered for playback to resume after a rebuffer, in milliseconds.
static final int

The default duration of media that must be buffered for playback to start or resume following a user action such as a seek, in milliseconds.
static final int

A default size in bytes for a camera motion buffer.
static final int

A default size in bytes for an image buffer.
static final int

The default maximum duration of media that the player will attempt to buffer, in milliseconds.
static final int

A default size in bytes for a metadata buffer.
static final int

The default minimum duration of media that the player will attempt to ensure is buffered at all times, in milliseconds.
static final int

The buffer size in bytes that will be used as a minimum target buffer in all cases.
static final int

A default size in bytes for a muxed buffer (e.g. containing video, audio and text).
static final boolean

The default prioritization of buffer time constraints over size constraints.
static final boolean

The default for whether the back buffer is retained from the previous keyframe.
static final int

The default target buffer size in bytes.
static final int

A default size in bytes for a text buffer.
static final int

A default size in bytes for a video buffer.

Public constructors

Constructs a new instance, using the DEFAULT_* constants defined in this class.

Protected constructors
DefaultLoadControl(
    DefaultAllocator allocator,
    int minBufferMs,
    int maxBufferMs,
    int bufferForPlaybackMs,
    int bufferForPlaybackAfterRebufferMs,
    int targetBufferBytes,
    boolean prioritizeTimeOverSizeThresholds,
    int backBufferDurationMs,
    boolean retainBackBufferFromKeyframe
)

Public methods
Allocator

Returns the Allocator that should be used to obtain media buffer allocations.
long

Returns the duration of media to retain in the buffer prior to the current playback position, for fast backward seeking.
void
onPrepared(PlayerId playerId)

Called by the player when prepared with a new source.
void
onReleased(PlayerId playerId)

Called by the player when released.
void
onStopped(PlayerId playerId)

Called by the player when stopped.
void
onTracksSelected(
    LoadControl.Parameters parameters,
    TrackGroupArray trackGroups,
    @NullableType ExoTrackSelection[] trackSelections
)

Called by the player when a track selection occurs.
boolean

Returns whether media should be retained from the keyframe before the current playback position minus getBackBufferDurationUs, rather than any sample before or at that position.
boolean

Called by the player to determine whether it should continue to load the source.
boolean
shouldContinuePreloading(
    Timeline timeline,
    MediaSource.MediaPeriodId mediaPeriodId,
    long bufferedDurationUs
)

Called to determine whether preloading should be continued.
boolean

Called repeatedly by the player when it's loading the source, has yet to start playback, and has the minimum amount of data necessary for playback to be started.

Protected methods
int
calculateTargetBufferBytes(
    @NullableType ExoTrackSelection[] trackSelectionArray
)

Calculate target buffer size in bytes based on the selected tracks.
final int
@InlineMe(replacement = "this.calculateTargetBufferBytes(trackSelectionArray)")
calculateTargetBufferBytes(
    Renderer[] renderers,
    ExoTrackSelection[] trackSelectionArray
)

This method is deprecated.

Use calculateTargetBufferBytes instead.

Inherited Constants
From androidx.media3.exoplayer.LoadControl
static final MediaSource.MediaPeriodId

This field is deprecated.

Used as a placeholder when MediaPeriodId is unknown.

Inherited methods
From androidx.media3.exoplayer.LoadControl
long

This method is deprecated.

Implements getBackBufferDurationUs instead.
void

This method is deprecated.

Use onPrepared instead.
void

This method is deprecated.

Implement onReleased instead.
void

This method is deprecated.

Implement onStopped instead.
void
onTracksSelected(
    Renderer[] renderers,
    TrackGroupArray trackGroups,
    @NullableType ExoTrackSelection[] trackSelections
)

This method is deprecated.

Implement onTracksSelected instead.
void
onTracksSelected(
    Timeline timeline,
    MediaSource.MediaPeriodId mediaPeriodId,
    Renderer[] renderers,
    TrackGroupArray trackGroups,
    @NullableType ExoTrackSelection[] trackSelections
)

This method is deprecated.

Implement onTracksSelected instead.
void
onTracksSelected(
    PlayerId playerId,
    Timeline timeline,
    MediaSource.MediaPeriodId mediaPeriodId,
    Renderer[] renderers,
    TrackGroupArray trackGroups,
    @NullableType ExoTrackSelection[] trackSelections
)

This method is deprecated.

Implement onTracksSelected instead.
boolean

This method is deprecated.

Implements retainBackBufferFromKeyframe instead.
boolean
shouldContinueLoading(
    long playbackPositionUs,
    long bufferedDurationUs,
    float playbackSpeed
)

This method is deprecated.

Implement shouldContinueLoading instead.
boolean
shouldStartPlayback(
    long bufferedDurationUs,
    float playbackSpeed,
    boolean rebuffering,
    long targetLiveOffsetUs
)

This method is deprecated.

Implement shouldStartPlayback instead.
boolean
shouldStartPlayback(
    Timeline timeline,
    MediaSource.MediaPeriodId mediaPeriodId,
    long bufferedDurationUs,
    float playbackSpeed,
    boolean rebuffering,
    long targetLiveOffsetUs
)

This method is deprecated.

Implement shouldStartPlayback instead.

Constants

DEFAULT_AUDIO_BUFFER_SIZE

public static final int DEFAULT_AUDIO_BUFFER_SIZE = 13107200

A default size in bytes for an audio buffer.

DEFAULT_BACK_BUFFER_DURATION_MS

public static final int DEFAULT_BACK_BUFFER_DURATION_MS = 0

The default back buffer duration in milliseconds.

DEFAULT_BUFFER_FOR_PLAYBACK_AFTER_REBUFFER_MS

public static final int DEFAULT_BUFFER_FOR_PLAYBACK_AFTER_REBUFFER_MS = 5000

The default duration of media that must be buffered for playback to resume after a rebuffer, in milliseconds. A rebuffer is defined to be caused by buffer depletion rather than a user action.

DEFAULT_BUFFER_FOR_PLAYBACK_MS

public static final int DEFAULT_BUFFER_FOR_PLAYBACK_MS = 2500

The default duration of media that must be buffered for playback to start or resume following a user action such as a seek, in milliseconds.

DEFAULT_CAMERA_MOTION_BUFFER_SIZE

public static final int DEFAULT_CAMERA_MOTION_BUFFER_SIZE = 131072

A default size in bytes for a camera motion buffer.

DEFAULT_IMAGE_BUFFER_SIZE

public static final int DEFAULT_IMAGE_BUFFER_SIZE = 131072

A default size in bytes for an image buffer.

DEFAULT_MAX_BUFFER_MS

public static final int DEFAULT_MAX_BUFFER_MS = 50000

The default maximum duration of media that the player will attempt to buffer, in milliseconds.

DEFAULT_METADATA_BUFFER_SIZE

public static final int DEFAULT_METADATA_BUFFER_SIZE = 131072

A default size in bytes for a metadata buffer.

DEFAULT_MIN_BUFFER_MS

public static final int DEFAULT_MIN_BUFFER_MS = 50000

The default minimum duration of media that the player will attempt to ensure is buffered at all times, in milliseconds.

DEFAULT_MIN_BUFFER_SIZE

public static final int DEFAULT_MIN_BUFFER_SIZE = 13107200

The buffer size in bytes that will be used as a minimum target buffer in all cases. This is also the default target buffer before tracks are selected.

DEFAULT_MUXED_BUFFER_SIZE

public static final int DEFAULT_MUXED_BUFFER_SIZE = 144310272

A default size in bytes for a muxed buffer (e.g. containing video, audio and text).

DEFAULT_PRIORITIZE_TIME_OVER_SIZE_THRESHOLDS

public static final boolean DEFAULT_PRIORITIZE_TIME_OVER_SIZE_THRESHOLDS = false

The default prioritization of buffer time constraints over size constraints.

DEFAULT_RETAIN_BACK_BUFFER_FROM_KEYFRAME

public static final boolean DEFAULT_RETAIN_BACK_BUFFER_FROM_KEYFRAME = false

The default for whether the back buffer is retained from the previous keyframe.

DEFAULT_TARGET_BUFFER_BYTES

public static final int DEFAULT_TARGET_BUFFER_BYTES = -1

The default target buffer size in bytes. The value (LENGTH_UNSET) means that the load control will calculate the target buffer size based on the selected tracks.

DEFAULT_TEXT_BUFFER_SIZE

public static final int DEFAULT_TEXT_BUFFER_SIZE = 131072

A default size in bytes for a text buffer.

DEFAULT_VIDEO_BUFFER_SIZE

public static final int DEFAULT_VIDEO_BUFFER_SIZE = 131072000

A default size in bytes for a video buffer.

Public constructors

DefaultLoadControl

public DefaultLoadControl()

Constructs a new instance, using the DEFAULT_* constants defined in this class.

Protected constructors

DefaultLoadControl

protected DefaultLoadControl(
    DefaultAllocator allocator,
    int minBufferMs,
    int maxBufferMs,
    int bufferForPlaybackMs,
    int bufferForPlaybackAfterRebufferMs,
    int targetBufferBytes,
    boolean prioritizeTimeOverSizeThresholds,
    int backBufferDurationMs,
    boolean retainBackBufferFromKeyframe
)

Public methods

getAllocator

public Allocator getAllocator()

Returns the Allocator that should be used to obtain media buffer allocations.

getBackBufferDurationUs

public long getBackBufferDurationUs(PlayerId playerId)

Returns the duration of media to retain in the buffer prior to the current playback position, for fast backward seeking.

Note: If retainBackBufferFromKeyframe is false then seeking in the back-buffer will only be fast if the back-buffer contains a keyframe prior to the seek position.

Note: Implementations should return a single value. Dynamic changes to the back-buffer are not currently supported.

Parameters
PlayerId playerId

The ID of the player that requests the back buffer duration.
Returns
long

The duration of media to retain in the buffer prior to the current playback position, in microseconds.

onPrepared

public void onPrepared(PlayerId playerId)

Called by the player when prepared with a new source.

Parameters
PlayerId playerId

The ID of the player that prepared a new source.

onReleased

public void onReleased(PlayerId playerId)

Called by the player when released.

Parameters
PlayerId playerId

The ID of the player that was released.

onStopped

public void onStopped(PlayerId playerId)

Called by the player when stopped.

Parameters
PlayerId playerId

The ID of the player that was stopped.

onTracksSelected

public void onTracksSelected(
    LoadControl.Parameters parameters,
    TrackGroupArray trackGroups,
    @NullableType ExoTrackSelection[] trackSelections
)

Called by the player when a track selection occurs.

Parameters
LoadControl.Parameters parameters

containing the ID of the player, the current in ExoPlayer, and the MediaPeriod for which the selection was made. Will be EMPTY_MEDIA_PERIOD_ID when timeline is empty.
TrackGroupArray trackGroups

The TrackGroups from which the selection was made.
@NullableType ExoTrackSelection[] trackSelections

The track selections that were made.

retainBackBufferFromKeyframe

public boolean retainBackBufferFromKeyframe(PlayerId playerId)

Returns whether media should be retained from the keyframe before the current playback position minus getBackBufferDurationUs, rather than any sample before or at that position.

Warning: Returning true will cause the back-buffer size to depend on the spacing of keyframes in the media being played. Returning true is not recommended unless you control the media and are comfortable with the back-buffer size exceeding getBackBufferDurationUs by as much as the maximum duration between adjacent keyframes in the media.

Note: Implementations should return a single value. Dynamic changes to the back-buffer are not currently supported.

Parameters
PlayerId playerId

The ID of the player that requests whether to retain the back buffer from key frame.
Returns
boolean

Whether media should be retained from the keyframe before the current playback position minus getBackBufferDurationUs, rather than any sample before or at that position.

shouldContinueLoading

public boolean shouldContinueLoading(LoadControl.Parameters parameters)

Called by the player to determine whether it should continue to load the source. If this method returns true, the MediaPeriod identified in the most recent onTracksSelected call will continue being loaded.

Parameters
LoadControl.Parameters parameters

Information about the playback context and the MediaPeriod that will continue to load if this method returns true.
Returns
boolean

Whether the loading should continue.

shouldContinuePreloading

public boolean shouldContinuePreloading(
    Timeline timeline,
    MediaSource.MediaPeriodId mediaPeriodId,
    long bufferedDurationUs
)

Called to determine whether preloading should be continued. If this method returns true, the presented period will continue to load media.

Parameters
Timeline timeline

The Timeline containing the preload period that can be looked up with MediaPeriodId.periodUid.
MediaSource.MediaPeriodId mediaPeriodId

The MediaPeriodId of the preloading period.
long bufferedDurationUs

The duration of media currently buffered by the preload period.
Returns
boolean

Whether the preloading should continue for the given period.

shouldStartPlayback

public boolean shouldStartPlayback(LoadControl.Parameters parameters)

Called repeatedly by the player when it's loading the source, has yet to start playback, and has the minimum amount of data necessary for playback to be started. The value returned determines whether playback is actually started. The load control may opt to return false until some condition has been met (e.g. a certain amount of media is buffered).

Parameters
LoadControl.Parameters parameters

Information about the playback context and the MediaPeriod that will start playing if this method returns true.
Returns
boolean

Whether playback should be allowed to start or resume.

Protected methods

calculateTargetBufferBytes

protected int calculateTargetBufferBytes(
    @NullableType ExoTrackSelection[] trackSelectionArray
)

Calculate target buffer size in bytes based on the selected tracks. The player will try not to exceed this target buffer. Only used when targetBufferBytes is LENGTH_UNSET.

Parameters
@NullableType ExoTrackSelection[] trackSelectionArray

The selected tracks.
Returns
int

The target buffer size in bytes.

calculateTargetBufferBytes

@InlineMe(replacement = "this.calculateTargetBufferBytes(trackSelectionArray)")
protected final int calculateTargetBufferBytes(
    Renderer[] renderers,
    ExoTrackSelection[] trackSelectionArray
)