VideoFrameReleaseHelper

Artifact: androidx.media3:media3-exoplayer

View Source

---

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)