VideoFrameReleaseHelper

@UnstableApi
public final 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 methods
long
adjustReleaseTime(long releaseTimeNs)

Adjusts the release timestamp for the next frame.
void
onFormatChanged(float formatFrameRate)

Called when the renderer's output format changes.
void
onNextFrame(long framePresentationTimeUs)

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

Called when the renderer's playback speed changes.
void

Called when the renderer's position is reset.
void

Called when the renderer is started.
void

Called when the renderer is stopped.
void

Called when the renderer changes which Surface it's rendering to renders to.
void
setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy int changeFrameRateStrategy
)

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.

Public constructors

VideoFrameReleaseHelper

public VideoFrameReleaseHelper(@Nullable Context context)

Constructs an instance.

Parameters
@Nullable Context context

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

Public methods

adjustReleaseTime

public long adjustReleaseTime(long releaseTimeNs)

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
long releaseTimeNs

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

public void onFormatChanged(float formatFrameRate)

Called when the renderer's output format changes.

Parameters
float formatFrameRate

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

onNextFrame

public void onNextFrame(long framePresentationTimeUs)

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

Parameters
long framePresentationTimeUs

The frame presentation timestamp, in microseconds.

onPlaybackSpeed

public void onPlaybackSpeed(float playbackSpeed)

Called when the renderer's playback speed changes.

Parameters
float playbackSpeed

The factor by which playback is sped up.

onPositionReset

public void onPositionReset()

Called when the renderer's position is reset.

onStarted

public void onStarted()

Called when the renderer is started.

onStopped

public void onStopped()

Called when the renderer is stopped.

onSurfaceChanged

public void onSurfaceChanged(@Nullable Surface surface)

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

Parameters
@Nullable Surface surface

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

setChangeFrameRateStrategy

public void setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy int changeFrameRateStrategy
)

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.

The default value is VIDEO_CHANGE_FRAME_RATE_STRATEGY_ONLY_IF_SEAMLESS.