@UnstableApi
interface VideoSink

A sink that consumes decoded video frames and images from video and image renderers.

Multiple renderers can feed the same sink, but not in parallel.

Summary

Nested types
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation VideoSink.InputType

Specifies how the input frames are made available to the video sink.

Listener for VideoSink events.

Handler for a video frame.

Thrown by VideoSink implementations.

Constants
const Int

Input frames come from a Bitmap.
const Int

Input frames come from a surface.

Public functions
Unit

Clears the set output surface info.
Unit

Enables this video sink to render the start of the stream to its output surface even if the renderer is not started yet.
Unit
flush(resetPosition: Boolean)

Flushes the video sink.
Surface!

Returns the input Surface where the video sink consumes input frames from.
Boolean
handleInputBitmap(
    inputBitmap: Bitmap!,
    timestampIterator: TimestampIterator!
)

Handles an input Bitmap.
Boolean
handleInputFrame(
    framePresentationTimeUs: Long,
    isLastFrame: Boolean,
    positionUs: Long,
    elapsedRealtimeUs: Long,
    videoFrameHandler: VideoSink.VideoFrameHandler!
)

Handles a video input frame.
Unit
initialize(sourceFormat: Format!)

Initializes the video sink.
Boolean

Returns whether all the data has been rendered to the output surface.
Boolean

Returns whether the video sink is initialized.
Boolean
isReady(rendererOtherwiseReady: Boolean)

Returns whether the video sink is able to immediately render media to its output surface from the current position.
Unit
join(renderNextFrameImmediately: Boolean)

Joins the video sink to a new stream.
Unit

Informs the video sink that a new input stream will be queued.
Unit

Called when the Renderer currently feeding this sink is disabled.
Unit
onRendererEnabled(mayRenderStartOfStream: Boolean)

Called when the Renderer currently feeding this sink is enabled.
Unit

Called when the Renderer currently feeding this sink is started.
Unit

Called when the Renderer currently feeding this sink is stopped.
Unit

Releases the sink.
Unit
render(positionUs: Long, elapsedRealtimeUs: Long)

Incrementally renders processed video frames to the output surface.
Unit

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.
Unit
setListener(listener: VideoSink.Listener!, executor: Executor!)

Sets a Listener on this sink.
Unit
setOutputSurfaceInfo(outputSurface: Surface!, outputResolution: Size!)

Sets the output surface info.
Unit

Sets video effects to apply after the next stream change.
Unit
setPlaybackSpeed(speed: @FloatRange(from = 0, fromInclusive = false) Float)

Sets the playback speed.
Unit
setStreamTimestampInfo(
    streamStartPositionUs: Long,
    streamOffsetUs: Long,
    bufferTimestampAdjustmentUs: Long,
    lastResetPositionUs: Long
)

Sets information about the timestamps of the current input stream.
Unit
setVideoEffects(videoEffects: (Mutable)List<Effect!>!)

Sets video effects to apply immediately.
Unit
setVideoFrameMetadataListener(
    videoFrameMetadataListener: VideoFrameMetadataListener!
)

Sets the VideoFrameMetadataListener.

Constants

INPUT_TYPE_BITMAP

const val INPUT_TYPE_BITMAP = 2: Int

Input frames come from a Bitmap.

INPUT_TYPE_SURFACE

const val INPUT_TYPE_SURFACE = 1: Int

Input frames come from a surface.

Public functions

clearOutputSurfaceInfo

fun clearOutputSurfaceInfo(): Unit

Clears the set output surface info.

enableMayRenderStartOfStream

fun enableMayRenderStartOfStream(): Unit

Enables this video sink to render the start of the stream to its output surface even if the renderer is not started yet.

This is used to update the value of mayRenderStartOfStream passed to onRendererEnabled.

flush

fun flush(resetPosition: Boolean): Unit

Flushes the video sink.

After calling this method, any frames stored inside the video sink are discarded.

Parameters
resetPosition: Boolean

Whether to reset the current position.

getInputSurface

fun getInputSurface(): Surface!

Returns the input Surface where the video sink consumes input frames from.

Must be called after the sink is initialized.

handleInputBitmap

fun handleInputBitmap(
    inputBitmap: Bitmap!,
    timestampIterator: TimestampIterator!
): Boolean

Handles an input Bitmap.

Must be called after the corresponding stream is signalled.

Parameters
inputBitmap: Bitmap!

The Bitmap to queue to the video sink.
timestampIterator: TimestampIterator!

The times within the current stream that the bitmap should be shown at. The timestamps should be monotonically increasing.
Returns
Boolean

Whether the bitmap was queued successfully. If false, the caller can try again later.

handleInputFrame

fun handleInputFrame(
    framePresentationTimeUs: Long,
    isLastFrame: Boolean,
    positionUs: Long,
    elapsedRealtimeUs: Long,
    videoFrameHandler: VideoSink.VideoFrameHandler!
): Boolean

Handles a video input frame.

Must be called after the corresponding stream is signalled.

Parameters
framePresentationTimeUs: Long

The frame's presentation time, in microseconds.
isLastFrame: Boolean

Whether this is the last frame of the video stream.
positionUs: Long

The current playback position, in microseconds.
elapsedRealtimeUs: Long

elapsedRealtime in microseconds, taken approximately at the time the playback position was positionUs.
videoFrameHandler: VideoSink.VideoFrameHandler!

The VideoFrameHandler used to handle the input frame.
Returns
Boolean

Whether the frame was handled successfully. If false, the caller can try again later.
Throws
androidx.media3.exoplayer.video.VideoSink.VideoSinkException

initialize

fun initialize(sourceFormat: Format!): Unit

Initializes the video sink.

Parameters
sourceFormat: Format!

The format of the first input video or image.
Throws
androidx.media3.exoplayer.video.VideoSink.VideoSinkException

If initializing the sink failed.

isEnded

fun isEnded(): Boolean

Returns whether all the data has been rendered to the output surface.

isInitialized

fun isInitialized(): Boolean

Returns whether the video sink is initialized.

isReady

fun isReady(rendererOtherwiseReady: Boolean): Boolean

Returns whether the video sink is able to immediately render media to its output surface from the current position.

The renderer should be ready if and only if the video sink is ready.

Parameters
rendererOtherwiseReady: Boolean

Whether the renderer is ready except for the video sink.

join

fun join(renderNextFrameImmediately: Boolean): Unit

Joins the video sink to a new stream.

The sink will mask isReady as true for a short time to avoid interrupting an ongoing playback, even if the first frame hasn't yet been rendered to the output surface.

Parameters
renderNextFrameImmediately: Boolean

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

onInputStreamChanged

fun onInputStreamChanged(@VideoSink.InputType inputType: Int, format: Format!): Unit

Informs the video sink that a new input stream will be queued.

Must be called after the sink is initialized.

Parameters
@VideoSink.InputType inputType: Int

The InputType of the stream.
format: Format!

The Format of the stream.

onRendererDisabled

fun onRendererDisabled(): Unit

Called when the Renderer currently feeding this sink is disabled.

onRendererEnabled

fun onRendererEnabled(mayRenderStartOfStream: Boolean): Unit

Called when the Renderer currently feeding this sink is enabled.

onRendererStarted

fun onRendererStarted(): Unit

Called when the Renderer currently feeding this sink is started.

onRendererStopped

fun onRendererStopped(): Unit

Called when the Renderer currently feeding this sink is stopped.

release

fun release(): Unit

Releases the sink.

render

fun render(positionUs: Long, elapsedRealtimeUs: Long): Unit

Incrementally renders processed video frames to the output surface.

Parameters
positionUs: Long

The current playback position, in microseconds.
elapsedRealtimeUs: Long

elapsedRealtime in microseconds, taken approximately at the time the playback position was positionUs.
Throws
androidx.media3.exoplayer.video.VideoSink.VideoSinkException

If an error occurs during rendering.

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.

setListener

fun setListener(listener: VideoSink.Listener!, executor: Executor!): Unit

Sets a Listener on this sink. Callbacks are triggered on the supplied Executor.

Parameters
listener: VideoSink.Listener!

The Listener.
executor: Executor!

The Executor to dispatch the callbacks.

setOutputSurfaceInfo

fun setOutputSurfaceInfo(outputSurface: Surface!, outputResolution: Size!): Unit

Sets the output surface info.

setPendingVideoEffects

fun setPendingVideoEffects(videoEffects: (Mutable)List<Effect!>!): Unit

Sets video effects to apply after the next stream change.

setPlaybackSpeed

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

Sets the playback speed.

setStreamTimestampInfo

fun setStreamTimestampInfo(
    streamStartPositionUs: Long,
    streamOffsetUs: Long,
    bufferTimestampAdjustmentUs: Long,
    lastResetPositionUs: Long
): Unit

Sets information about the timestamps of the current input stream.

Parameters
streamStartPositionUs: Long

The start position of the buffer presentation timestamps of the current stream, in microseconds.
streamOffsetUs: Long

The offset that is added to the buffer presentation timestamps by the player, in microseconds.
bufferTimestampAdjustmentUs: Long

The timestamp adjustment to add to the buffer presentation timestamps to convert them to frame presentation timestamps, in microseconds.
lastResetPositionUs: Long

The renderer last reset position, in microseconds.

setVideoEffects

fun setVideoEffects(videoEffects: (Mutable)List<Effect!>!): Unit

Sets video effects to apply immediately.

setVideoFrameMetadataListener

fun setVideoFrameMetadataListener(
    videoFrameMetadataListener: VideoFrameMetadataListener!
): Unit

Sets the VideoFrameMetadataListener.