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 caller 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,
    isDecodeOnlyFrame: Boolean,
    isLastFrame: Boolean,
    frameReleaseInfo: VideoFrameReleaseControl.FrameReleaseInfo!
)

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

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

Joins the release control to a new stream.
Boolean

Called when a frame has been released.
Unit

Called when rendering starts.
Unit

Called when rendering stops.
Unit
onStreamChanged(
    @VideoSink.FirstFrameReleaseInstruction firstFrameReleaseInstruction: Int
)

Called when the stream changes.
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 caller 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 caller 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,
    isDecodeOnlyFrame: Boolean,
    isLastFrame: Boolean,
    frameReleaseInfo: VideoFrameReleaseControl.FrameReleaseInfo!
): Int

Returns a FrameReleaseAction for a video frame which instructs the caller 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.
isDecodeOnlyFrame: Boolean

Whether the frame is decode-only because its presentation time is before the intended start time.
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 caller whether to release the frame or not.
Throws
androidx.media3.exoplayer.ExoPlaybackException

isReady

fun isReady(otherwiseReady: Boolean): Boolean

Whether the release control is ready to start playback.

Parameters
otherwiseReady: Boolean

Whether the caller 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.

onFrameReleasedIsFirstFrame

fun onFrameReleasedIsFirstFrame(): Boolean

Called when a frame has been released.

Returns
Boolean

Whether this is the first released frame.

onStarted

fun onStarted(): Unit

Called when rendering starts.

onStopped

fun onStopped(): Unit

Called when rendering stops.

onStreamChanged

fun onStreamChanged(
    @VideoSink.FirstFrameReleaseInstruction firstFrameReleaseInstruction: Int
): Unit

Called when the stream changes.

Must also be called for the first stream.

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.