VideoFrameReleaseHelper

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
public final class VideoFrameReleaseHelper

A helper to release video frames to a Surface. This 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

Constants
`static final long`	`@VisibleForTesting VSYNC_SAMPLE_UPDATE_PERIOD_MS = 500` The period between sampling display VSYNC timestamps, in milliseconds.

Public constructors
`VideoFrameReleaseHelper(Context context)` Constructs an instance.

Public methods
`long`	`adjustReleaseTime(long releaseTimeNs, long presentationTimeUs)` Adjusts the release timestamp for the next frame.
`void`	`onFormatChanged(float formatFrameRate)` Called when the output format changes.
`void`	`onNextFrame(long framePresentationTimeUs)` Called for each frame, prior to it being skipped, dropped or rendered.
`void`	`onPlaybackSpeed(float playbackSpeed)` Called when the playback speed changes.
`void`	`onPositionReset()` Called when the position is reset.
`void`	`onStarted()` Called when rendering starts.
`void`	`onStopped()` Called when rendering stops.
`void`	`onSurfaceChanged(@Nullable Surface surface)` Called when the `Surface` on which to render changes.
`void`	`setChangeFrameRateStrategy( @C.VideoChangeFrameRateStrategy int changeFrameRateStrategy )` Changes the `C.VideoChangeFrameRateStrategy` used when calling setFrameRate.
`void`	`@VisibleForTesting setVsyncData(long vsyncSampleTimeNs, long vsyncDurationNs)`

Constants

VSYNC_SAMPLE_UPDATE_PERIOD_MS

@VisibleForTesting
public static final long VSYNC_SAMPLE_UPDATE_PERIOD_MS = 500

The period between sampling display VSYNC timestamps, in milliseconds.

Public constructors

VideoFrameReleaseHelper

public VideoFrameReleaseHelper(Context context)

Constructs an instance.

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

Public methods

adjustReleaseTime

public long adjustReleaseTime(long releaseTimeNs, long presentationTimeUs)

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`.
`long presentationTimeUs`	The frame's presentation timestamp in microsecond.

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 output format changes.

Parameters
`float formatFrameRate`	The format's frame rate, or `NO_VALUE` if unknown.

onNextFrame

public void onNextFrame(long framePresentationTimeUs)

Called 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 playback speed changes.

Parameters
`float playbackSpeed`	The factor by which playback is sped up.

onPositionReset

public void onPositionReset()

Called when the position is reset.

onStarted

public void onStarted()

Called when rendering starts.

onStopped

public void onStopped()

Called when rendering stops.

onSurfaceChanged

public void onSurfaceChanged(@Nullable Surface surface)

Called when the Surface on which to render changes.

Parameters
`@Nullable Surface surface`	The new `Surface`, or `null` if there is none.

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.

setVsyncData

@VisibleForTesting
public void setVsyncData(long vsyncSampleTimeNs, long vsyncDurationNs)