FFmpegMediaMetadataRetriever

https://github.com/wseemann/ffmpegmediametadataretriever
Admin
FFmpegMediaMetadataRetriever is a reimplementation of Android's MediaMetadataRetriever class that...
Tokens:8,956
Snippets:64
Trust Score:8.5
Update:6 months ago
Show doc for...
Tokens:
Raw
### Basic Usage of FFmpegMediaMetadataRetriever

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/README.md

Demonstrates how to initialize FFmpegMediaMetadataRetriever, set a data source, extract metadata, get a frame at a specific time, retrieve embedded artwork, and release the retriever.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
mmr.setDataSource(mUri);
mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ALBUM);
mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST);
Bitmap b = mmr.getFrameAtTime(2000000, FFmpegMediaMetadataRetriever.OPTION_CLOSEST); // frame at 2 seconds
byte [] artwork = mmr.getEmbeddedPicture();

mmr.release();
```

--------------------------------

### Configure Android SDK and NDK Paths

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/README.md

Set the sdk.dir and ndk.dir properties in local.properties to point to your Android SDK and NDK installations. This is required for building the native FFmpeg binaries.

```properties
sdk.dir=/Users/wseemann/Library/Android/sdk
ndk.dir=/Users/wseemann/Library/Android/sdk/ndk/27.1.12297006
```

--------------------------------

### Get All Available Metadata in Java

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves all metadata as a Metadata object for bulk access. Use the has() method to verify key existence before retrieval.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Music/track.mp3");

    FFmpegMediaMetadataRetriever.Metadata metadata = mmr.getMetadata();

    if (metadata != null) {
        HashMap<String, String> allMetadata = metadata.getAll();

        // Print all available metadata
        for (Map.Entry<String, String> entry : allMetadata.entrySet()) {
            System.out.println(entry.getKey() + ": " + entry.getValue());
        }

        // Check if specific metadata exists
        if (metadata.has(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST)) {
            String artist = metadata.getString(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST);
            System.out.println("Artist found: " + artist);
        }
    }
} finally {
    mmr.release();
}
```

--------------------------------

### getMetadata - Get All Available Metadata

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves all available metadata as a Metadata object containing a HashMap of key-value pairs.

```APIDOC
## getMetadata()

### Description
Retrieves all available metadata as a Metadata object containing a HashMap of key-value pairs. Provides bulk access to all metadata in a single call.

### Response
- **Metadata** (Object) - A container object providing access to the full set of metadata via getAll() or specific lookups via has() and getString().
```

--------------------------------

### Clean and Upload Archives

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/RELEASING.md

Clean the project and upload archives for both core and native modules. Use --no-daemon and --no-parallel for potentially faster execution.

```bash
./gradlew clean
```

```bash
./gradlew uploadArchives --no-daemon --no-parallel
```

--------------------------------

### Extract Media Metadata and Generate Thumbnails in Kotlin

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

A helper class demonstrating how to extract various metadata fields and generate scaled thumbnails from different URI sources.

```kotlin
class MediaMetadataHelper(private val context: Context) {

    data class MediaInfo(
        val title: String?,
        val artist: String?,
        val album: String?,
        val duration: Long,
        val audioCodec: String?,
        val videoCodec: String?,
        val width: Int,
        val height: Int,
        val thumbnail: Bitmap?,
        val albumArt: Bitmap?
    )

    fun extractMediaInfo(uri: Uri): Result<MediaInfo> {
        val mmr = FFmpegMediaMetadataRetriever()

        return try {
            // Set data source based on URI scheme
            when (uri.scheme) {
                "content" -> mmr.setDataSource(context, uri)
                "file", null -> mmr.setDataSource(uri.path)
                "http", "https", "rtmp" -> mmr.setDataSource(uri.toString())
                else -> throw IllegalArgumentException("Unsupported URI scheme: ${uri.scheme}")
            }

            // Extract metadata
            val title = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_TITLE)
            val artist = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST)
            val album = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ALBUM)
            val durationStr = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_DURATION)
            val audioCodec = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_AUDIO_CODEC)
            val videoCodec = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_CODEC)
            val widthStr = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH)
            val heightStr = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT)

            // Get thumbnail at 4 seconds
            val thumbnail = mmr.getFrameAtTime(
                4000000,
                FFmpegMediaMetadataRetriever.OPTION_CLOSEST_SYNC
            )

            // Get album art
            val albumArtBytes = mmr.embeddedPicture
            val albumArt = albumArtBytes?.let {
                BitmapFactory.decodeByteArray(it, 0, it.size)
            }

            Result.success(MediaInfo(
                title = title,
                artist = artist,
                album = album,
                duration = durationStr?.toLongOrNull() ?: 0L,
                audioCodec = audioCodec,
                videoCodec = videoCodec,
                width = widthStr?.toIntOrNull() ?: 0,
                height = heightStr?.toIntOrNull() ?: 0,
                thumbnail = thumbnail,
                albumArt = albumArt
            ))
        } catch (e: Exception) {
            Result.failure(e)
        } finally {
            mmr.release()
        }
    }

    fun generateThumbnails(uri: Uri, count: Int, width: Int, height: Int): List<Bitmap> {
        val mmr = FFmpegMediaMetadataRetriever()
        val thumbnails = mutableListOf<Bitmap>()

        try {
            mmr.setDataSource(uri.toString())

            val durationStr = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_DURATION)
            val duration = durationStr?.toLongOrNull() ?: return emptyList()

            val interval = (duration * 1000) / (count + 1) // Convert to microseconds

            for (i in 1..count) {
                val timeUs = interval * i
                val frame = mmr.getScaledFrameAtTime(
                    timeUs,
                    FFmpegMediaMetadataRetriever.OPTION_CLOSEST_SYNC,
                    width,
                    height
                )
                frame?.let { thumbnails.add(it) }
            }
        } finally {
            mmr.release()
        }

        return thumbnails
    }
}
```

--------------------------------

### Set Media Source from Local File Path

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Loads a local media file using its absolute path. Always call release() in a finally block to free resources.

```java
// Basic usage with local file path
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Movies/video.mp4");

    // Now ready to extract metadata or frames
    String title = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_TITLE);
    String duration = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_DURATION);

    System.out.println("Title: " + title);
    System.out.println("Duration: " + duration + " ms");
} catch (IllegalArgumentException e) {
    System.err.println("Invalid file path: " + e.getMessage());
} finally {
    mmr.release();
}
```

--------------------------------

### Set Media Source from FileDescriptor

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Loads media from a FileDescriptor, including support for specific offsets and lengths. Useful for raw resources.

```java
// Load media from FileDescriptor (e.g., from raw resources)
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
AssetFileDescriptor fd = null;
try {
    fd = context.getResources().openRawResourceFd(R.raw.sample_audio);

    mmr.setDataSource(
        fd.getFileDescriptor(),
        fd.getStartOffset(),
        fd.getLength()
    );

    String title = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_TITLE);
    String artist = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST);

    System.out.println("Title: " + title);
    System.out.println("Artist: " + artist);
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
} finally {
    mmr.release();
    if (fd != null) {
        try { fd.close(); } catch (IOException ignored) {}
    }
}
```

--------------------------------

### Tag Release Version

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/RELEASING.md

Create an annotated tag for the specific release version.

```bash
git tag -a X.Y.Z -m "Version X.Y.Z"
```

--------------------------------

### Set Media Source from URL with Headers

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Loads media from remote URLs, supporting protocols like HTTP, HTTPS, and RTMP. Custom headers are passed as a Map for authentication or configuration.

```java
// Load media from URL with custom headers
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    Map<String, String> headers = new HashMap<>();
    headers.put("Authorization", "Bearer your-token-here");
    headers.put("User-Agent", "MyApp/1.0");

    mmr.setDataSource("https://example.com/protected/video.mp4", headers);

    String audioCodec = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_AUDIO_CODEC);
    String videoCodec = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_CODEC);

    System.out.println("Audio codec: " + audioCodec);
    System.out.println("Video codec: " + videoCodec);
} catch (IllegalArgumentException e) {
    System.err.println("Failed to load URL: " + e.getMessage());
} finally {
    mmr.release();
}
```

--------------------------------

### Configure FFmpegMediaMetadataRetriever Gradle Dependencies

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Add FFmpegMediaMetadataRetriever to your Android project. Use the full library for all architectures or individual native libraries for smaller APKs. Configure ABI splits for optimized APK sizes.

```groovy
// In your app's build.gradle

// Option 1: Full library with all architectures
dependencies {
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-core:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native:1.0.21'
}

// Option 2: Individual architecture support (smaller APK)
dependencies {
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-core:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-armeabi-v7a:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-arm64-v8a:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-x86:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-x86_64:1.0.21'
}

// ABI splits for optimized APK sizes
android {
    splits {
        abi {
            enable true
            reset()
            include 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
            universalApk false
        }
    }
}
```

--------------------------------

### Add Maven Dependency for FFmpegMediaMetadataRetriever

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/README.md

Include these dependencies in your project's build.gradle file to integrate FFmpegMediaMetadataRetriever.

```gradle
dependencies {
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-core:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native:1.0.21'
}
```

```gradle
dependencies {
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-core:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-armeabi-v7a:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-x86:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-x86_64:1.0.21'
    implementation 'com.github.wseemann:FFmpegMediaMetadataRetriever-native-arm64-v8a:1.0.21'
}
```

--------------------------------

### Commit Changes for Release

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/RELEASING.md

Commit the version changes in gradle.properties before creating a tag.

```bash
git commit -am "Prepare for release X.Y.Z."
```

--------------------------------

### Push Changes and Tags

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/RELEASING.md

Push all local commits and tags to the remote repository.

```bash
git push && git push --tags
```

--------------------------------

### Commit Next Development Version

Source: https://github.com/wseemann/ffmpegmediametadataretriever/blob/master/RELEASING.md

After releasing, update gradle.properties to the next SNAPSHOT version and commit these changes.

```bash
git commit -am "Prepare next development version."
```

--------------------------------

### Set Media Source from Content URI

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Loads media using an Android content URI, suitable for files retrieved from system pickers or content providers.

```java
// Load media from content URI (e.g., from file picker)
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    Uri contentUri = Uri.parse("content://media/external/video/media/12345");
    mmr.setDataSource(context, contentUri);

    String artist = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST);
    String album = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ALBUM);

    System.out.println("Artist: " + artist);
    System.out.println("Album: " + album);
} catch (IllegalArgumentException | SecurityException e) {
    System.err.println("Failed to access content: " + e.getMessage());
} finally {
    mmr.release();
}
```

--------------------------------

### Extract Chapter-Specific Metadata in Java

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Iterates through chapters in a media file to retrieve title and timing information. Requires checking the chapter count before iteration.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/audiobooks/book.m4b");

    // Get total chapter count
    String countStr = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_CHAPTER_COUNT);

    if (countStr != null) {
        int chapterCount = Integer.parseInt(countStr);
        System.out.println("Total chapters: " + chapterCount);

        // Iterate through all chapters
        for (int i = 0; i < chapterCount; i++) {
            String chapterTitle = mmr.extractMetadataFromChapter(
                FFmpegMediaMetadataRetriever.METADATA_KEY_TITLE, i);
            String startTime = mmr.extractMetadataFromChapter(
                FFmpegMediaMetadataRetriever.METADATA_KEY_CHAPTER_START_TIME, i);
            String endTime = mmr.extractMetadataFromChapter(
                FFmpegMediaMetadataRetriever.METADATA_KEY_CHAPTER_END_TIME, i);

            System.out.println("Chapter " + (i + 1) + ": " + chapterTitle);
            System.out.println("  Start: " + startTime + " ms, End: " + endTime + " ms");
        }
    }
} finally {
    mmr.release();
}
```

--------------------------------

### Set Video Output Surface

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Sets a Surface for direct video frame output, useful for displaying frames directly to a SurfaceView or TextureView without intermediate Bitmap conversion. Frames will be rendered directly to the surface upon calling getFrameAtTime.

```java
// In an Activity or Fragment with a SurfaceView
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();

surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() {
    @Override
    public void surfaceCreated(SurfaceHolder holder) {
        try {
            mmr.setDataSource("/sdcard/Movies/video.mp4");
            mmr.setSurface(holder.getSurface());

            // Frames will be rendered directly to the surface
            Bitmap frame = mmr.getFrameAtTime(2000000); // 2 seconds

        } catch (IllegalArgumentException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }

    @Override
    public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {}

    @Override
    public void surfaceDestroyed(SurfaceHolder holder) {
        mmr.release();
    }
});
```

--------------------------------

### extractMetadataFromChapter - Extract Chapter-Specific Metadata

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves metadata from a specific chapter within the media file. Useful for audiobooks, podcasts, or videos with chapters.

```APIDOC
## extractMetadataFromChapter(key, chapterIndex)

### Description
Retrieves metadata from a specific chapter within the media file.

### Parameters
- **key** (String) - Required - The metadata key constant.
- **chapterIndex** (int) - Required - The index of the chapter to retrieve metadata from.

### Response
- **value** (String) - The metadata value for the specified chapter, or null if not found.
```

--------------------------------

### Extract Single Metadata Value in Java

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves specific metadata fields from a media source. Always call release() in a finally block to free resources.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("https://example.com/media/song.mp3");

    // Extract common metadata fields
    String title = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_TITLE);
    String artist = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ARTIST);
    String album = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ALBUM);
    String albumArtist = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ALBUM_ARTIST);
    String composer = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_COMPOSER);
    String genre = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_GENRE);
    String track = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_TRACK);
    String disc = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_DISC);
    String date = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_DATE);

    // Extract technical metadata
    String duration = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_DURATION);
    String audioCodec = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_AUDIO_CODEC);
    String videoCodec = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_CODEC);
    String bitrate = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VARIANT_BITRATE);
    String framerate = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_FRAMERATE);
    String rotation = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_ROTATION);
    String width = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_WIDTH);
    String height = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_VIDEO_HEIGHT);
    String filesize = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_FILESIZE);

    // Extract streaming metadata (SHOUTcast)
    String icyMetadata = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_ICY_METADATA);

    System.out.println("Title: " + title);
    System.out.println("Artist: " + artist);
    System.out.println("Duration: " + duration + " ms");
    System.out.println("Video: " + width + "x" + height + " @ " + framerate + " fps");
} finally {
    mmr.release();
}
```

--------------------------------

### Release FFmpegMediaMetadataRetriever Resources

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Call the release method in a finally block to prevent memory leaks after metadata extraction is complete.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Movies/video.mp4");

    // Extract metadata
    String title = mmr.extractMetadata(FFmpegMediaMetadataRetriever.METADATA_KEY_TITLE);
    Bitmap frame = mmr.getFrameAtTime(1000000);

    // Process data...

} catch (IllegalArgumentException e) {
    System.err.println("Error: " + e.getMessage());
} finally {
    // Always release resources
    mmr.release();
}
```

--------------------------------

### Extract Scaled Video Frame at Specific Time

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves a video frame at the specified timestamp, scaled to the requested dimensions. Useful for generating thumbnails at a specific size. Simplified calls use OPTION_CLOSEST_SYNC by default.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Movies/video.mp4");

    // Get frame at 10 seconds, scaled to 320x180 pixels
    long timeUs = 10000000; // 10 seconds in microseconds
    int width = 320;
    int height = 180;

    // Get scaled frame with seek option
    Bitmap thumbnail = mmr.getScaledFrameAtTime(
        timeUs,
        FFmpegMediaMetadataRetriever.OPTION_CLOSEST_SYNC,
        width,
        height
    );

    // Simplified call using OPTION_CLOSEST_SYNC by default
    Bitmap thumbnailDefault = mmr.getScaledFrameAtTime(timeUs, width, height);

    if (thumbnail != null) {
        System.out.println("Thumbnail size: " + thumbnail.getWidth() + "x" + thumbnail.getHeight());
        // Save thumbnail or display
        thumbnailImageView.setImageBitmap(thumbnail);
    }
} finally {
    mmr.release();
}
```

--------------------------------

### extractMetadata - Extract Single Metadata Value

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves a specific metadata value from the media file using predefined metadata keys. Returns null if the metadata is not available.

```APIDOC
## extractMetadata(key)

### Description
Retrieves a specific metadata value from the media file using predefined metadata keys. Returns null if the metadata is not available.

### Parameters
- **key** (String) - Required - The metadata key constant (e.g., METADATA_KEY_TITLE, METADATA_KEY_DURATION).

### Response
- **value** (String) - The metadata value associated with the key, or null if not found.
```

--------------------------------

### Extract Video Frame at Specific Time

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves a video frame as a Bitmap at or near the specified timestamp. Time is specified in microseconds. Use different options to control frame selection relative to the timestamp.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Movies/video.mp4");

    // Time is specified in microseconds (1 second = 1,000,000 microseconds)
    long timeUs = 5000000; // 5 seconds

    // OPTION_PREVIOUS_SYNC: Get sync frame at or before the time
    Bitmap framePrevSync = mmr.getFrameAtTime(timeUs,
        FFmpegMediaMetadataRetriever.OPTION_PREVIOUS_SYNC);

    // OPTION_NEXT_SYNC: Get sync frame at or after the time
    Bitmap frameNextSync = mmr.getFrameAtTime(timeUs,
        FFmpegMediaMetadataRetriever.OPTION_NEXT_SYNC);

    // OPTION_CLOSEST_SYNC: Get sync frame closest to the time
    Bitmap frameClosestSync = mmr.getFrameAtTime(timeUs,
        FFmpegMediaMetadataRetriever.OPTION_CLOSEST_SYNC);

    // OPTION_CLOSEST: Get exact frame (slower but most accurate)
    Bitmap frameExact = mmr.getFrameAtTime(timeUs,
        FFmpegMediaMetadataRetriever.OPTION_CLOSEST);

    // Simplified call using OPTION_CLOSEST_SYNC by default
    Bitmap frameDefault = mmr.getFrameAtTime(timeUs);

    // Get any representative frame (time position ignored)
    Bitmap frameAny = mmr.getFrameAtTime();

    if (frameExact != null) {
        System.out.println("Frame size: " + frameExact.getWidth() + "x" + frameExact.getHeight());
        // Use bitmap (e.g., display in ImageView or save to file)
        imageView.setImageBitmap(frameExact);
    }
} finally {
    mmr.release();
}
```

--------------------------------

### setSurface - Set Video Output Surface

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Sets a Surface for direct video frame output. Useful for displaying frames directly to a SurfaceView or TextureView without intermediate Bitmap conversion.

```APIDOC
## setSurface - Set Video Output Surface

### Description
Sets a Surface for direct video frame output. Useful for displaying frames directly to a SurfaceView or TextureView without intermediate Bitmap conversion.

### Method
`setSurface(Surface surface)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
// In an Activity or Fragment with a SurfaceView
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();

surfaceView.getHolder().addCallback(new SurfaceHolder.Callback() {
    @Override
    public void surfaceCreated(SurfaceHolder holder) {
        try {
            mmr.setDataSource("/sdcard/Movies/video.mp4");
            mmr.setSurface(holder.getSurface());

            // Frames will be rendered directly to the surface
            Bitmap frame = mmr.getFrameAtTime(2000000); // 2 seconds

        } catch (IllegalArgumentException e) {
            System.err.println("Error: " + e.getMessage());
        }
    }

    @Override
    public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {}

    @Override
    public void surfaceDestroyed(SurfaceHolder holder) {
        mmr.release();
    }
});
```

### Response
#### Success Response (200)
No explicit return value, but video frames will be rendered to the provided Surface.

#### Response Example
```java
// Video frames are rendered directly to the SurfaceView
```
```

--------------------------------

### getFrameAtTime - Extract Video Frame at Specific Time

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves a video frame as a Bitmap at or near the specified timestamp. The option parameter controls how the frame is located relative to the requested time.

```APIDOC
## getFrameAtTime - Extract Video Frame at Specific Time

### Description
Retrieves a video frame as a Bitmap at or near the specified timestamp. The option parameter controls how the frame is located relative to the requested time.

### Method
`getFrameAtTime(long timeUs, int option)`
`getFrameAtTime(long timeUs)` (defaults to OPTION_CLOSEST_SYNC)
`getFrameAtTime()` (returns any representative frame)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Movies/video.mp4");

    // Time is specified in microseconds (1 second = 1,000,000 microseconds)
    long timeUs = 5000000; // 5 seconds

    // OPTION_PREVIOUS_SYNC: Get sync frame at or before the time
    Bitmap framePrevSync = mmr.getFrameAtTime(timeUs, FFmpegMediaMetadataRetriever.OPTION_PREVIOUS_SYNC);

    // OPTION_NEXT_SYNC: Get sync frame at or after the time
    Bitmap frameNextSync = mmr.getFrameAtTime(timeUs, FFmpegMediaMetadataRetriever.OPTION_NEXT_SYNC);

    // OPTION_CLOSEST_SYNC: Get sync frame closest to the time
    Bitmap frameClosestSync = mmr.getFrameAtTime(timeUs, FFmpegMediaMetadataRetriever.OPTION_CLOSEST_SYNC);

    // OPTION_CLOSEST: Get exact frame (slower but most accurate)
    Bitmap frameExact = mmr.getFrameAtTime(timeUs, FFmpegMediaMetadataRetriever.OPTION_CLOSEST);

    // Simplified call using OPTION_CLOSEST_SYNC by default
    Bitmap frameDefault = mmr.getFrameAtTime(timeUs);

    // Get any representative frame (time position ignored)
    Bitmap frameAny = mmr.getFrameAtTime();

    if (frameExact != null) {
        System.out.println("Frame size: " + frameExact.getWidth() + "x" + frameExact.getHeight());
        // Use bitmap (e.g., display in ImageView or save to file)
        imageView.setImageBitmap(frameExact);
    }
} finally {
    mmr.release();
}
```

### Response
#### Success Response (200)
- **Bitmap** - The extracted video frame.

#### Response Example
```java
// Bitmap object representing the video frame
```
```

--------------------------------

### getScaledFrameAtTime - Extract Scaled Video Frame

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves a video frame at the specified timestamp, scaled to the requested dimensions. Useful for generating thumbnails at a specific size without additional image processing.

```APIDOC
## getScaledFrameAtTime - Extract Scaled Video Frame

### Description
Retrieves a video frame at the specified timestamp, scaled to the requested dimensions. Useful for generating thumbnails at a specific size without additional image processing.

### Method
`getScaledFrameAtTime(long timeUs, int option, int width, int height)`
`getScaledFrameAtTime(long timeUs, int width, int height)` (defaults to OPTION_CLOSEST_SYNC)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Movies/video.mp4");

    // Get frame at 10 seconds, scaled to 320x180 pixels
    long timeUs = 10000000; // 10 seconds in microseconds
    int width = 320;
    int height = 180;

    // Get scaled frame with seek option
    Bitmap thumbnail = mmr.getScaledFrameAtTime(
        timeUs,
        FFmpegMediaMetadataRetriever.OPTION_CLOSEST_SYNC,
        width,
        height
    );

    // Simplified call using OPTION_CLOSEST_SYNC by default
    Bitmap thumbnailDefault = mmr.getScaledFrameAtTime(timeUs, width, height);

    if (thumbnail != null) {
        System.out.println("Thumbnail size: " + thumbnail.getWidth() + "x" + thumbnail.getHeight());
        // Save thumbnail or display
        thumbnailImageView.setImageBitmap(thumbnail);
    }
} finally {
    mmr.release();
}
```

### Response
#### Success Response (200)
- **Bitmap** - The extracted and scaled video frame.

#### Response Example
```java
// Bitmap object representing the scaled video frame
```
```

--------------------------------

### Extract Embedded Album Art

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves embedded artwork (album cover, movie poster) from the media file as a byte array. Returns null if no embedded picture is found. The artwork can then be decoded into a Bitmap.

```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Music/album_track.mp3");

    byte[] artwork = mmr.getEmbeddedPicture();

    if (artwork != null && artwork.length > 0) {
        // Decode byte array to Bitmap
        Bitmap albumArt = BitmapFactory.decodeByteArray(artwork, 0, artwork.length);

        if (albumArt != null) {
            System.out.println("Album art size: " + albumArt.getWidth() + "x" + albumArt.getHeight());
            albumArtImageView.setImageBitmap(albumArt);
        }
    } else {
        System.out.println("No embedded artwork found");
        // Use placeholder image
    }
} finally {
    mmr.release();
}
```

--------------------------------

### getEmbeddedPicture - Extract Album Art

Source: https://context7.com/wseemann/ffmpegmediametadataretriever/llms.txt

Retrieves embedded artwork (album cover, movie poster) from the media file as a byte array. Returns null if no embedded picture is found.

```APIDOC
## getEmbeddedPicture - Extract Album Art

### Description
Retrieves embedded artwork (album cover, movie poster) from the media file as a byte array. Returns null if no embedded picture is found.

### Method
`getEmbeddedPicture()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```java
FFmpegMediaMetadataRetriever mmr = new FFmpegMediaMetadataRetriever();
try {
    mmr.setDataSource("/sdcard/Music/album_track.mp3");

    byte[] artwork = mmr.getEmbeddedPicture();

    if (artwork != null && artwork.length > 0) {
        // Decode byte array to Bitmap
        Bitmap albumArt = BitmapFactory.decodeByteArray(artwork, 0, artwork.length);

        if (albumArt != null) {
            System.out.println("Album art size: " + albumArt.getWidth() + "x" + albumArt.getHeight());
            albumArtImageView.setImageBitmap(albumArt);
        }
    } else {
        System.out.println("No embedded artwork found");
        // Use placeholder image
    }
} finally {
    mmr.release();
}
```

### Response
#### Success Response (200)
- **byte[]** - A byte array representing the embedded artwork. Returns null if no artwork is found.

#### Response Example
```java
// byte array representing the artwork, or null
```
```
Tokens:
Raw