# VideoFrameReleaseHelper

Artifact: [androidx.media3:media3-exoplayer](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/exoplayer/video/VideoFrameReleaseHelper.java+class:androidx.media3.exoplayer.video.VideoFrameReleaseHelper)

*** ** * ** ***


```
@UnstableApi
class VideoFrameReleaseHelper
```

<br />

*** ** * ** ***

A helper to release video frames to a `https://developer.android.com/reference/android/view/Surface.html`. 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 `https://developer.android.com/reference/android/view/Surface.html` frame rate to inform the underlying platform of a fixed frame rate, when there is one.

## Summary

| ### Constants |
|---|---|
| `const https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/VisibleForTesting https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#VSYNC_SAMPLE_UPDATE_PERIOD_MS() = 500` The period between sampling display VSYNC timestamps, in milliseconds. |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#VideoFrameReleaseHelper(android.content.Context)(context: https://developer.android.com/reference/android/content/Context.html!)` Constructs an instance. |

| ### Public functions |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#adjustReleaseTime(long,long,long,long)( releaseTimeNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, presentationTimeUs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, frameDurationNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, frameIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html )` Adjusts the release timestamp for the frame with the given presentation timestamp. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#getVsyncDurationNs()()` Returns the vsync duration in nanoseconds, or `https://developer.android.com/reference/kotlin/androidx/media3/common/C#TIME_UNSET()` if unknown. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onPlaybackSpeed(float)(playbackSpeed: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` Called when the playback speed changes. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onPositionReset()()` Called when the position is reset. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onStarted()()` Called when rendering starts. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onStopped()()` Called when rendering stops. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onSurfaceChanged(android.view.Surface)(surface: https://developer.android.com/reference/android/view/Surface.html?)` Called when the `https://developer.android.com/reference/android/view/Surface.html` on which to render changes. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#setChangeFrameRateStrategy(int)( @https://developer.android.com/reference/kotlin/androidx/media3/common/C.VideoChangeFrameRateStrategy changeFrameRateStrategy: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html )` Changes the `https://developer.android.com/reference/kotlin/androidx/media3/common/C.VideoChangeFrameRateStrategy` used when calling `https://developer.android.com/reference/android/view/Surface.html#setFrameRate(float, int)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#setSurfaceMediaFrameRate(float)(surfaceMediaFrameRate: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html)` Sets the media frame rate used to calculate the playback frame rate of the surface. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/annotation/VisibleForTesting https://developer.android.com/reference/kotlin/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#setVsyncData(long,long)(vsyncSampleTimeNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, vsyncDurationNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` |

## 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: https://developer.android.com/reference/android/content/Context.html!` | 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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The frame's unadjusted release time, in nanoseconds and in the same time base as `https://developer.android.com/reference/java/lang/System.html#nanoTime()`. |
| `presentationTimeUs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The frame's presentation timestamp in microsecond. |
| `frameDurationNs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The estimated fixed frame duration in nanoseconds, or `https://developer.android.com/reference/kotlin/androidx/media3/common/C#TIME_UNSET()` if unknown. |
| `frameIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | A monotonically increasing index for the frame, or `https://developer.android.com/reference/kotlin/androidx/media3/common/C#INDEX_UNSET()` if unknown. |

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html` | The adjusted frame release timestamp, in nanoseconds and in the same time base as `https://developer.android.com/reference/java/lang/System.html#nanoTime()`. |

### getVsyncDurationNs

```
fun getVsyncDurationNs(): Long
```

Returns the vsync duration in nanoseconds, or `https://developer.android.com/reference/kotlin/androidx/media3/common/C#TIME_UNSET()` if unknown.

### onPlaybackSpeed

```
fun onPlaybackSpeed(playbackSpeed: Float): Unit
```

Called when the playback speed changes.

| Parameters |
|---|---|
| `playbackSpeed: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | 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 `https://developer.android.com/reference/android/view/Surface.html` on which to render changes.

| Parameters |
|---|---|
| `surface: https://developer.android.com/reference/android/view/Surface.html?` | The new `https://developer.android.com/reference/android/view/Surface.html`, or `null` if there is none. |

### setChangeFrameRateStrategy

```
fun setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy changeFrameRateStrategy: Int
): Unit
```

Changes the `https://developer.android.com/reference/kotlin/androidx/media3/common/C.VideoChangeFrameRateStrategy` used when calling `https://developer.android.com/reference/android/view/Surface.html#setFrameRate(float, int)`.

The default value is `https://developer.android.com/reference/kotlin/androidx/media3/common/C#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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-float/index.html` | The media frame rate, or `https://developer.android.com/reference/kotlin/androidx/media3/common/Format#NO_VALUE()` if unknown. |

### setVsyncData

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