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, long frameDurationNs, long frameIndex )` Adjusts the release timestamp for the frame with the given presentation timestamp.
`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`	`setSurfaceMediaFrameRate(float surfaceMediaFrameRate)` Sets the media frame rate used to calculate the playback frame rate of the surface.
`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,
    long frameDurationNs,
    long frameIndex
)

Adjusts the release timestamp for the frame with the given presentation timestamp.

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.
`long frameDurationNs`	The estimated fixed frame duration in nanoseconds, or `TIME_UNSET` if unknown.
`long frameIndex`	A monotonically increasing index for the frame, or `INDEX_UNSET` if unknown.

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

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.

setSurfaceMediaFrameRate

public void setSurfaceMediaFrameRate(float surfaceMediaFrameRate)

Sets the media frame rate used to calculate the playback frame rate of the surface.

Parameters
`float surfaceMediaFrameRate`	The media frame rate, or `NO_VALUE` if unknown.

setVsyncData

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