VideoFrameReleaseControl

@UnstableApi
class VideoFrameReleaseControl

Controls the releasing of video frames.

Summary

Nested types
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@UnstableApi
@IntDef(value = )
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
const Int

Signals a frame should be dropped.
const Int

Signals that a frame should be ignored.
const Int

Signals a frame should be released immediately.
const Int

Signals a frame should be scheduled for release.
const Int

Signals that a frame should be skipped.
const Int

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

Public constructors
VideoFrameReleaseControl(
    applicationContext: Context!,
    frameTimingEvaluator: VideoFrameReleaseControl.FrameTimingEvaluator!,
    allowedJoiningTimeMs: Long
)

Creates an instance.

Public functions
Unit

Allows the frame control to indicate the first frame can be released before this instance is started.
Int
@VideoFrameReleaseControl.FrameReleaseAction
getFrameReleaseAction(
    presentationTimeUs: Long,
    positionUs: Long,
    elapsedRealtimeUs: Long,
    outputStreamStartPositionUs: Long,
    isLastFrame: Boolean,
    frameReleaseInfo: VideoFrameReleaseControl.FrameReleaseInfo!
)

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

Whether the release control is ready to start playback.
Unit
join(renderNextFrameImmediately: Boolean)

Joins the release control to a new stream.
Unit

Called when the renderer is disabled.
Unit
onEnabled(releaseFirstFrameBeforeStarted: Boolean)

Called when the renderer is enabled.
Boolean

Called when a frame has been released.
Unit

Called when the renderer processed a stream change.
Unit

Called when the renderer is started.
Unit

Called when the renderer is stopped.
Unit

Resets the release control.
Unit

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.
Unit
setClock(clock: Clock!)

Sets the clock that will be used.
Unit
setFrameRate(frameRate: Float)

Sets the frame rate.
Unit
setOutputSurface(outputSurface: Surface?)

Called when the display surface changed.
Unit
setPlaybackSpeed(speed: @FloatRange(from = 0, fromInclusive = false) Float)

Sets the playback speed.

Constants

FRAME_RELEASE_DROP

const val FRAME_RELEASE_DROP = 2: Int

Signals a frame should be dropped.

FRAME_RELEASE_IGNORE

const val FRAME_RELEASE_IGNORE = 4: Int

Signals that a frame should be ignored.

FRAME_RELEASE_IMMEDIATELY

const val FRAME_RELEASE_IMMEDIATELY = 0: Int

Signals a frame should be released immediately.

FRAME_RELEASE_SCHEDULED

const val FRAME_RELEASE_SCHEDULED = 1: Int

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

FRAME_RELEASE_SKIP

const val FRAME_RELEASE_SKIP = 3: Int

Signals that a frame should be skipped.

FRAME_RELEASE_TRY_AGAIN_LATER

const val FRAME_RELEASE_TRY_AGAIN_LATER = 5: Int

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

Public constructors

VideoFrameReleaseControl

VideoFrameReleaseControl(
    applicationContext: Context!,
    frameTimingEvaluator: VideoFrameReleaseControl.FrameTimingEvaluator!,
    allowedJoiningTimeMs: Long
)

Creates an instance.

Parameters
applicationContext: Context!

The application context.
frameTimingEvaluator: VideoFrameReleaseControl.FrameTimingEvaluator!

The FrameTimingEvaluator that will assist in frame release actions.
allowedJoiningTimeMs: Long

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

Public functions

allowReleaseFirstFrameBeforeStarted

fun allowReleaseFirstFrameBeforeStarted(): Unit

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

getFrameReleaseAction

@VideoFrameReleaseControl.FrameReleaseAction
fun getFrameReleaseAction(
    presentationTimeUs: Long,
    positionUs: Long,
    elapsedRealtimeUs: Long,
    outputStreamStartPositionUs: Long,
    isLastFrame: Boolean,
    frameReleaseInfo: VideoFrameReleaseControl.FrameReleaseInfo!
): Int

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

Parameters
presentationTimeUs: Long

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

The current playback position, in microseconds.
elapsedRealtimeUs: Long

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

The stream's start position, in microseconds.
isLastFrame: Boolean

Whether the frame is known to contain the last frame of the current stream.
frameReleaseInfo: VideoFrameReleaseControl.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

fun isReady(rendererOtherwiseReady: Boolean): Boolean

Whether the release control is ready to start playback.

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

Parameters
rendererOtherwiseReady: Boolean

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

Whether the release control is ready.

join

fun join(renderNextFrameImmediately: Boolean): Unit

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
renderNextFrameImmediately: Boolean

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

onDisabled

fun onDisabled(): Unit

Called when the renderer is disabled.

onEnabled

fun onEnabled(releaseFirstFrameBeforeStarted: Boolean): Unit

Called when the renderer is enabled.

onFrameReleasedIsFirstFrame

fun onFrameReleasedIsFirstFrame(): Boolean

Called when a frame has been released.

Returns
Boolean

Whether this is the first released frame.

onProcessedStreamChange

fun onProcessedStreamChange(): Unit

Called when the renderer processed a stream change.

onStarted

fun onStarted(): Unit

Called when the renderer is started.

onStopped

fun onStopped(): Unit

Called when the renderer is stopped.

reset

fun reset(): Unit

Resets the release control.

setChangeFrameRateStrategy

fun setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy changeFrameRateStrategy: Int
): Unit

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.

The default value is VIDEO_CHANGE_FRAME_RATE_STRATEGY_ONLY_IF_SEAMLESS.

setClock

fun setClock(clock: Clock!): Unit

Sets the clock that will be used.

setFrameRate

fun setFrameRate(frameRate: Float): Unit

Sets the frame rate.

setOutputSurface

fun setOutputSurface(outputSurface: Surface?): Unit

Called when the display surface changed.

setPlaybackSpeed

fun setPlaybackSpeed(speed: @FloatRange(from = 0, fromInclusive = false) Float): Unit

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