VideoFrameReleaseControl

Artifact: androidx.media3:media3-exoplayer

View Source

---

Kotlin |Java

@UnstableApi
class VideoFrameReleaseControl

---

Controls the releasing of video frames.

Summary

Nested types
@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = ElementType.TYPE_USE) @UnstableApi @IntDef(value = ) annotation VideoFrameReleaseControl.FrameReleaseAction The frame release action returned by getFrameReleaseAction.
class VideoFrameReleaseControl.FrameReleaseInfo Per FrameReleaseAction metadata.
interface VideoFrameReleaseControl.FrameTimingEvaluator Decides whether a frame should be forced to be released, or dropped.

Constants
const Int	FRAME_RELEASE_DROP = 2 Signals a frame should be dropped.
const Int	FRAME_RELEASE_IGNORE = 4 Signals that a frame should be ignored.
const Int	FRAME_RELEASE_IMMEDIATELY = 0 Signals a frame should be released immediately.
const Int	FRAME_RELEASE_SCHEDULED = 1 Signals a frame should be scheduled for release.
const Int	FRAME_RELEASE_SKIP = 3 Signals that a frame should be skipped.
const Int	FRAME_RELEASE_TRY_AGAIN_LATER = 5 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	allowReleaseFirstFrameBeforeStarted() 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,     frameDurationNs: Long,     frameIndex: Long,     frameReleaseInfo: VideoFrameReleaseControl.FrameReleaseInfo! ) Returns a FrameReleaseAction for a video frame which instructs the caller what to do with the frame.
Boolean	isJoining() Returns whether the release control is currently joining.
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	onFrameReleasedIsFirstFrame() Called when a frame has been released.
Unit	onStarted() Called when rendering starts.
Unit	onStopped() Called when rendering stops.
Unit	onStreamChanged(     @VideoSink.FirstFrameReleaseInstruction firstFrameReleaseInstruction: Int ) Called when the stream changes.
Unit	reset() Resets the release control.
Unit	setChangeFrameRateStrategy(     @C.VideoChangeFrameRateStrategy changeFrameRateStrategy: Int ) Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.
Unit	setClock(clock: Clock!) Sets the clock that will be used.
Unit	@ExperimentalApi setEarlySchedulingThresholdUs(earlySchedulingThresholdUs: Long) Sets the threshold for how early a frame may be scheduled for release on the surface.
Unit	setOutputSurface(outputSurface: Surface?) Called when the display surface changed.
Unit	setPlaybackSpeed(speed: @FloatRange(from = 0, fromInclusive = false) Float) Sets the playback speed.
Unit	setRequiresOutputSurface(requiresOutputSurface: Boolean) Sets whether an output surface is required for the release control to release frames.
Unit	setSurfaceMediaFrameRate(surfaceMediaFrameRate: Float) Sets the surface media frame rate.

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,
    frameDurationNs: Long,
    frameIndex: Long,
    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.
frameDurationNs: Long	The estimated fixed frame duration in nanoseconds, or TIME_UNSET if unknown.
frameIndex: Long	A monotonically increasing index for the frame, or INDEX_UNSET if unknown.
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

isJoining

fun isJoining(): Boolean

Returns whether the release control is currently joining.

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.

setEarlySchedulingThresholdUs

@ExperimentalApi
fun setEarlySchedulingThresholdUs(earlySchedulingThresholdUs: Long): Unit

Sets the threshold for how early a frame may be scheduled for release on the surface.

Frames that are earlier than this threshold will be held and 'release' will be tried again later.

This value is in microseconds. The default value is DEFAULT_EARLY_SCHEDULING_THRESHOLD_US.

This method is experimental and will be renamed or removed in a future release.

Parameters
earlySchedulingThresholdUs: Long	The maximum early time threshold in microseconds.

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.

setRequiresOutputSurface

fun setRequiresOutputSurface(requiresOutputSurface: Boolean): Unit

Sets whether an output surface is required for the release control to release frames.

The default value is true.

setSurfaceMediaFrameRate

fun setSurfaceMediaFrameRate(surfaceMediaFrameRate: Float): Unit

Sets the surface media frame rate.