# 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
public final 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 |
|---|---|
| `static final long` | `@https://developer.android.com/reference/androidx/annotation/VisibleForTesting https://developer.android.com/reference/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/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#VideoFrameReleaseHelper(android.content.Context)(https://developer.android.com/reference/android/content/Context.html context)` Constructs an instance. |

| ### Public methods |
|---|---|
| `long` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#adjustReleaseTime(long,long,long,long)( long releaseTimeNs, long presentationTimeUs, long frameDurationNs, long frameIndex )` Adjusts the release timestamp for the frame with the given presentation timestamp. |
| `long` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#getVsyncDurationNs()()` Returns the vsync duration in nanoseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if unknown. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onPlaybackSpeed(float)(float playbackSpeed)` Called when the playback speed changes. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onPositionReset()()` Called when the position is reset. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onStarted()()` Called when rendering starts. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onStopped()()` Called when rendering stops. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#onSurfaceChanged(android.view.Surface)(@https://developer.android.com/reference/androidx/annotation/Nullable https://developer.android.com/reference/android/view/Surface.html surface)` Called when the `https://developer.android.com/reference/android/view/Surface.html` on which to render changes. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#setChangeFrameRateStrategy(int)( @https://developer.android.com/reference/androidx/media3/common/C.VideoChangeFrameRateStrategy int changeFrameRateStrategy )` Changes the `https://developer.android.com/reference/androidx/media3/common/C.VideoChangeFrameRateStrategy` used when calling `https://developer.android.com/reference/android/view/Surface.html#setFrameRate(float, int)`. |
| `void` | `https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#setSurfaceMediaFrameRate(float)(float surfaceMediaFrameRate)` Sets the media frame rate used to calculate the playback frame rate of the surface. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/VisibleForTesting https://developer.android.com/reference/androidx/media3/exoplayer/video/VideoFrameReleaseHelper#setVsyncData(long,long)(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 |
|---|---|
| `https://developer.android.com/reference/android/content/Context.html 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 `https://developer.android.com/reference/java/lang/System.html#nanoTime()`. |
| `long presentationTimeUs` | The frame's presentation timestamp in microsecond. |
| `long frameDurationNs` | The estimated fixed frame duration in nanoseconds, or `https://developer.android.com/reference/androidx/media3/common/C#TIME_UNSET()` if unknown. |
| `long frameIndex` | A monotonically increasing index for the frame, or `https://developer.android.com/reference/androidx/media3/common/C#INDEX_UNSET()` if unknown. |

| Returns |
|---|---|
| `long` | 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

```
public long getVsyncDurationNs()
```

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

### 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 `https://developer.android.com/reference/android/view/Surface.html` on which to render changes.

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

### setChangeFrameRateStrategy

```
public void setChangeFrameRateStrategy(
    @C.VideoChangeFrameRateStrategy int changeFrameRateStrategy
)
```

Changes the `https://developer.android.com/reference/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/androidx/media3/common/C#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 `https://developer.android.com/reference/androidx/media3/common/Format#NO_VALUE()` if unknown. |

### setVsyncData

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