VideoFrameReleaseControl

@UnstableApi
public final class VideoFrameReleaseControl

Controls the releasing of video frames.

Summary

Nested types
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@UnstableApi
@IntDef(value = )
public annotation VideoFrameReleaseControl.FrameReleaseAction

The frame release action returned by getFrameReleaseAction.

Per FrameReleaseAction metadata.

Decides whether a frame should be forced to be released, or dropped.

Constants
static final int

Signals a frame should be dropped.
static final int

Signals that a frame should be ignored.
static final int

Signals a frame should be released immediately.
static final int

Signals a frame should be scheduled for release.
static final int

Signals that a frame should be skipped.
static final int

Signals that a frame should not be released and the renderer should try again later.

Public constructors
VideoFrameReleaseControl(
    Context applicationContext,
    VideoFrameReleaseControl.FrameTimingEvaluator frameTimingEvaluator,
    long allowedJoiningTimeMs
)

Creates an instance.

Public methods
void

Allows the frame control to indicate the first frame can be released before this instance is started.
int
@VideoFrameReleaseControl.FrameReleaseAction
getFrameReleaseAction(
    long presentationTimeUs,
    long positionUs,
    long elapsedRealtimeUs,
    long outputStreamStartPositionUs,
    boolean isLastFrame,
    VideoFrameReleaseControl.FrameReleaseInfo frameReleaseInfo
)

Returns a FrameReleaseAction for a video frame which instructs a renderer what to do with the frame.
boolean
isReady(boolean rendererOtherwiseReady)

Whether the release control is ready to start playback.
void
join(boolean renderNextFrameImmediately)

Joins the release control to a new stream.
void

Called when the renderer is disabled.
void
onEnabled(boolean releaseFirstFrameBeforeStarted)

Called when the renderer is enabled.
boolean

Called when a frame has been released.
void

Called when the renderer processed a stream change.
void

Called when the renderer is started.
void

Called when the renderer is stopped.
void

Resets the release control.
void
setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy int changeFrameRateStrategy
)

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.
void
setClock(Clock clock)

Sets the clock that will be used.
void
setFrameRate(float frameRate)

Sets the frame rate.
void

Called when the display surface changed.
void
setPlaybackSpeed(@FloatRange(from = 0, fromInclusive = false) float speed)

Sets the playback speed.

Constants

FRAME_RELEASE_DROP

public static final int FRAME_RELEASE_DROP = 2

Signals a frame should be dropped.

FRAME_RELEASE_IGNORE

public static final int FRAME_RELEASE_IGNORE = 4

Signals that a frame should be ignored.

FRAME_RELEASE_IMMEDIATELY

public static final int FRAME_RELEASE_IMMEDIATELY = 0

Signals a frame should be released immediately.

FRAME_RELEASE_SCHEDULED

public static final int FRAME_RELEASE_SCHEDULED = 1

Signals a frame should be scheduled for release. The release timestamp will be returned by getReleaseTimeNs.

FRAME_RELEASE_SKIP

public static final int FRAME_RELEASE_SKIP = 3

Signals that a frame should be skipped.

FRAME_RELEASE_TRY_AGAIN_LATER

public static final int FRAME_RELEASE_TRY_AGAIN_LATER = 5

Signals that a frame should not be released and the renderer should try again later.

Public constructors

VideoFrameReleaseControl

public VideoFrameReleaseControl(
    Context applicationContext,
    VideoFrameReleaseControl.FrameTimingEvaluator frameTimingEvaluator,
    long allowedJoiningTimeMs
)

Creates an instance.

Parameters
Context applicationContext

The application context.
VideoFrameReleaseControl.FrameTimingEvaluator frameTimingEvaluator

The FrameTimingEvaluator that will assist in frame release actions.
long allowedJoiningTimeMs

The maximum duration in milliseconds for which the renderer can attempt to seamlessly join an ongoing playback.

Public methods

allowReleaseFirstFrameBeforeStarted

public void allowReleaseFirstFrameBeforeStarted()

Allows the frame control to indicate the first frame can be released before this instance is started.

getFrameReleaseAction

@VideoFrameReleaseControl.FrameReleaseAction
public int getFrameReleaseAction(
    long presentationTimeUs,
    long positionUs,
    long elapsedRealtimeUs,
    long outputStreamStartPositionUs,
    boolean isLastFrame,
    VideoFrameReleaseControl.FrameReleaseInfo frameReleaseInfo
)

Returns a FrameReleaseAction for a video frame which instructs a renderer what to do with the frame.

Parameters
long presentationTimeUs

The presentation time of the video frame, in microseconds.
long positionUs

The current playback position, in microseconds.
long elapsedRealtimeUs

elapsedRealtime in microseconds, taken approximately at the time the playback position was positionUs.
long outputStreamStartPositionUs

The stream's start position, in microseconds.
boolean isLastFrame

Whether the frame is known to contain the last frame of the current stream.
VideoFrameReleaseControl.FrameReleaseInfo frameReleaseInfo

A FrameReleaseInfo that will be filled with detailed data only if the method returns FRAME_RELEASE_IMMEDIATELY or FRAME_RELEASE_SCHEDULED.
Returns
int

A FrameReleaseAction that should instruct the renderer whether to release the frame or not.
Throws
androidx.media3.exoplayer.ExoPlaybackException

isReady

public boolean isReady(boolean rendererOtherwiseReady)

Whether the release control is ready to start playback.

The renderer should be ready if and only if the release control is ready.

Parameters
boolean rendererOtherwiseReady

Whether the renderer is ready except for the release control.
Returns
boolean

Whether the release control is ready.

join

public void join(boolean renderNextFrameImmediately)

Joins the release control to a new stream.

The release control will pretend to be ready for a short time even if the first frame hasn't been rendered yet to avoid interrupting an ongoing playback.

Parameters
boolean renderNextFrameImmediately

Whether the next frame should be released as soon as possible or only at its preferred scheduled release time.

onDisabled

public void onDisabled()

Called when the renderer is disabled.

onEnabled

public void onEnabled(boolean releaseFirstFrameBeforeStarted)

Called when the renderer is enabled.

onFrameReleasedIsFirstFrame

public boolean onFrameReleasedIsFirstFrame()

Called when a frame has been released.

Returns
boolean

Whether this is the first released frame.

onProcessedStreamChange

public void onProcessedStreamChange()

Called when the renderer processed a stream change.

onStarted

public void onStarted()

Called when the renderer is started.

onStopped

public void onStopped()

Called when the renderer is stopped.

reset

public void reset()

Resets the release control.

setChangeFrameRateStrategy

public void setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy int changeFrameRateStrategy
)

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.

The default value is VIDEO_CHANGE_FRAME_RATE_STRATEGY_ONLY_IF_SEAMLESS.

setClock

public void setClock(Clock clock)

Sets the clock that will be used.

setFrameRate

public void setFrameRate(float frameRate)

Sets the frame rate.

setOutputSurface

public void setOutputSurface(@Nullable Surface outputSurface)

Called when the display surface changed.

setPlaybackSpeed

public void setPlaybackSpeed(@FloatRange(from = 0, fromInclusive = false) float speed)

Sets the playback speed. Called when the renderer playback speed changes.