VideoFrameReleaseHelper

@UnstableApi
class VideoFrameReleaseHelper

Helps a video Renderer release frames to a Surface. The helper:

  • Adjusts frame release timestamps to achieve a smoother visual result. The release timestamps are smoothed, and aligned with the default display's vsync signal.
  • Adjusts the Surface frame rate to inform the underlying platform of a fixed frame rate, when there is one.

Summary

Public constructors

Constructs an instance.

Public functions
Long
adjustReleaseTime(releaseTimeNs: Long)

Adjusts the release timestamp for the next frame.
Unit
onFormatChanged(formatFrameRate: Float)

Called when the renderer's output format changes.
Unit
onNextFrame(framePresentationTimeUs: Long)

Called by the renderer for each frame, prior to it being skipped, dropped or rendered.
Unit
onPlaybackSpeed(playbackSpeed: Float)

Called when the renderer's playback speed changes.
Unit

Called when the renderer's position is reset.
Unit

Called when the renderer is started.
Unit

Called when the renderer is stopped.
Unit

Called when the renderer changes which Surface it's rendering to renders to.
Unit

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.

Public constructors

VideoFrameReleaseHelper

VideoFrameReleaseHelper(context: Context?)

Constructs an instance.

Parameters
context: Context?

A context from which information about the default display can be retrieved.

Public functions

adjustReleaseTime

fun adjustReleaseTime(releaseTimeNs: Long): Long

Adjusts the release timestamp for the next frame. This is the frame whose presentation timestamp was most recently passed to onNextFrame.

This method may be called any number of times for each frame, including zero times (for skipped frames, or when rendering the first frame prior to playback starting), or more than once (if the caller wishes to give the helper the opportunity to refine a release time closer to when the frame needs to be released).

Parameters
releaseTimeNs: Long

The frame's unadjusted release time, in nanoseconds and in the same time base as nanoTime.
Returns
Long

The adjusted frame release timestamp, in nanoseconds and in the same time base as nanoTime.

onFormatChanged

fun onFormatChanged(formatFrameRate: Float): Unit

Called when the renderer's output format changes.

Parameters
formatFrameRate: Float

The format's frame rate, or NO_VALUE if unknown.

onNextFrame

fun onNextFrame(framePresentationTimeUs: Long): Unit

Called by the renderer for each frame, prior to it being skipped, dropped or rendered.

Parameters
framePresentationTimeUs: Long

The frame presentation timestamp, in microseconds.

onPlaybackSpeed

fun onPlaybackSpeed(playbackSpeed: Float): Unit

Called when the renderer's playback speed changes.

Parameters
playbackSpeed: Float

The factor by which playback is sped up.

onPositionReset

fun onPositionReset(): Unit

Called when the renderer's position is reset.

onStarted

fun onStarted(): Unit

Called when the renderer is started.

onStopped

fun onStopped(): Unit

Called when the renderer is stopped.

onSurfaceChanged

fun onSurfaceChanged(surface: Surface?): Unit

Called when the renderer changes which Surface it's rendering to renders to.

Parameters
surface: Surface?

The new Surface, or null if the renderer does not have one.

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.