# FrameExtractor

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

*** ** * ** ***

<br />

```
@UnstableApi
public final class FrameExtractor implements AutoCloseable
```

<br />

*** ** * ** ***

Extracts decoded frames from `https://developer.android.com/reference/androidx/media3/common/MediaItem`.

Frame extractor instances must be accessed from a single application thread.

This class may produce incorrect or washed out colors, or images that have too high contrast for inputs not covered by [testDecodeGlAccuracyRGB CTS test](https://cs.android.com/android/_/android/platform/cts/+/aaa242e5c26466cf245fa85ff8a7750378de9d72:tests/media/src/android/mediav2/cts/DecodeGlAccuracyTest.java;drc=d0d5ff338f8b84adf9066358bac435b1be3bbe61;l=534). That is:

- Inputs of BT.601 limited range are likely to produce accurate output with either `https://developer.android.com/reference/androidx/media3/exoplayer/mediacodec/MediaCodecSelector#PREFER_SOFTWARE()` or `https://developer.android.com/reference/androidx/media3/exoplayer/mediacodec/MediaCodecSelector#DEFAULT()` decoders across a wide range of devices.
- Other inputs are likely to produce accurate output when using `https://developer.android.com/reference/androidx/media3/exoplayer/mediacodec/MediaCodecSelector#DEFAULT()` decoders on devices that are launched with API 33 or later.
- HDR inputs will produce a `https://developer.android.com/reference/android/graphics/Bitmap.html` with `https://developer.android.com/reference/android/graphics/ColorSpace.Named.html#BT2020_HLG`. There are no guarantees that an HLG `https://developer.android.com/reference/android/graphics/Bitmap.html` displayed in `https://developer.android.com/reference/android/widget/ImageView.html` and an HLG video displayed in `https://developer.android.com/reference/android/view/SurfaceView.html` will look the same.
- Depending on the device and input video, color inaccuracies can be mitigated with an appropriate `https://developer.android.com/reference/androidx/media3/effect/RgbMatrix` effect.

## Summary

| ### Nested types |
|---|
| `public final class https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Builder` A builder for `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor` instances. |
| `public final class https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame` Stores an extracted and decoded video frame. |

| ### Public methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor#close()()` Releases the underlying resources. |
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame>` | `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor#getFrame(long)(long positionMs)` Extracts a representative `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame` for the specified video position. |
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame>` | `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor#getThumbnail()()` Extracts a representative thumbnail `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame` from the media. |

## Public methods

### close

```
public void close()
```

Releases the underlying resources. This method must be called when the frame extractor is no longer required. The frame extractor must not be used after calling this method.

### getFrame

```
public ListenableFuture<FrameExtractor.Frame> getFrame(long positionMs)
```

Extracts a representative `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame` for the specified video position.

**Performance Guidelines:**

- **Seek Parameters:** By default, this method uses `https://developer.android.com/reference/androidx/media3/exoplayer/SeekParameters#DEFAULT()` (equivalent to `https://developer.android.com/reference/androidx/media3/exoplayer/SeekParameters#EXACT()`), which requires the decoder to process all intermediate frames from the previous keyframe. If exact precision is not required, consider configuring the extractor with `https://developer.android.com/reference/androidx/media3/exoplayer/SeekParameters#CLOSEST_SYNC()` to improve extraction speed.
- **Downscaling:** If a full-resolution frame is not needed, consider applying a `https://developer.android.com/reference/androidx/media3/effect/Presentation` effect (e.g., `Presentation.createForHeight(480)`) to downscale the frame during extraction, reducing memory usage and accelerating processing.

| Parameters |
|---|---|
| `long positionMs` | The time position in the `https://developer.android.com/reference/androidx/media3/common/MediaItem` for which a frame is extracted, in milliseconds. |

| Returns |
|---|---|
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame>` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` of the result. |

### getThumbnail

```
public ListenableFuture<FrameExtractor.Frame> getThumbnail()
```

Extracts a representative thumbnail `https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame` from the media.

The implementation uses a heuristic to identify a good thumbnail position. If no specific thumbnail position is found, the frame at the beginning of the media is extracted.

**Performance Guidelines:** If a full-resolution thumbnail is not required, consider applying a `https://developer.android.com/reference/androidx/media3/effect/Presentation` effect (e.g., `Presentation.createForHeight(480)`) to downscale the frame during extraction. This reduces memory usage and accelerates processing.

| Returns |
|---|---|
| `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/media3/inspector/frame/FrameExtractor.Frame>` | A `https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html` of the result. |