VideoFrameReleaseHelper

@UnstableApi
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
const Long

The period between sampling display VSYNC timestamps, in milliseconds.

Public constructors

Constructs an instance.

Public functions
Long
adjustReleaseTime(
    releaseTimeNs: Long,
    presentationTimeUs: Long,
    frameDurationNs: Long,
    frameIndex: Long
)

Adjusts the release timestamp for the frame with the given presentation timestamp.
Unit
onPlaybackSpeed(playbackSpeed: Float)

Called when the playback speed changes.
Unit

Called when the position is reset.
Unit

Called when rendering starts.
Unit

Called when rendering stops.
Unit

Called when the Surface on which to render changes.
Unit

Changes the C.VideoChangeFrameRateStrategy used when calling setFrameRate.
Unit
setSurfaceMediaFrameRate(surfaceMediaFrameRate: Float)

Sets the media frame rate used to calculate the playback frame rate of the surface.
Unit
@VisibleForTesting
setVsyncData(vsyncSampleTimeNs: Long, vsyncDurationNs: Long)

Constants

VSYNC_SAMPLE_UPDATE_PERIOD_MS

@VisibleForTesting
const val VSYNC_SAMPLE_UPDATE_PERIOD_MS = 500: Long

The period between sampling display VSYNC timestamps, in milliseconds.

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,
    presentationTimeUs: Long,
    frameDurationNs: Long,
    frameIndex: Long
): Long

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
releaseTimeNs: Long

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

The frame's presentation timestamp in microsecond.
frameDurationNs: Long

The estimated fixed frame duration in nanoseconds, or TIME_UNSET if unknown.
frameIndex: Long

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

fun onPlaybackSpeed(playbackSpeed: Float): Unit

Called when the playback speed changes.

Parameters
playbackSpeed: Float

The factor by which playback is sped up.

onPositionReset

fun onPositionReset(): Unit

Called when the position is reset.

onStarted

fun onStarted(): Unit

Called when rendering starts.

onStopped

fun onStopped(): Unit

Called when rendering stops.

onSurfaceChanged

fun onSurfaceChanged(surface: Surface?): Unit

Called when the Surface on which to render changes.

Parameters
surface: Surface?

The new Surface, or null if there is none.

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.

setSurfaceMediaFrameRate

fun setSurfaceMediaFrameRate(surfaceMediaFrameRate: Float): Unit

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

Parameters
surfaceMediaFrameRate: Float

The media frame rate, or NO_VALUE if unknown.

setVsyncData

@VisibleForTesting
fun setVsyncData(vsyncSampleTimeNs: Long, vsyncDurationNs: Long): Unit