Added in API level 10

Summary: Nested Classes | Constants | Ctors | Methods | Protected Methods | Inherited Methods

MediaMetadataRetriever

---

Kotlin |Java

public class MediaMetadataRetriever
extends Object implements AutoCloseable

java.lang.Object
↳	android.media.MediaMetadataRetriever

---

MediaMetadataRetriever class provides a unified interface for retrieving frame and meta data from an input media file.

Summary

Nested classes
class	MediaMetadataRetriever.BitmapParams

Constants
int	METADATA_KEY_ALBUM The metadata key to retrieve the information about the album title of the data source.
int	METADATA_KEY_ALBUMARTIST The metadata key to retrieve the information about the performers or artist associated with the data source.
int	METADATA_KEY_ARTIST The metadata key to retrieve the information about the artist of the data source.
int	METADATA_KEY_AUTHOR The metadata key to retrieve the information about the author of the data source.
int	METADATA_KEY_BITRATE This key retrieves the average bitrate (in bits/sec), if available.
int	METADATA_KEY_BITS_PER_SAMPLE This key retrieves the bits per sample in numbers of bits, if available.
int	METADATA_KEY_CAPTURE_FRAMERATE This key retrieves the original capture framerate, if it's available.
int	METADATA_KEY_CD_TRACK_NUMBER The metadata key to retrieve the numeric string describing the order of the audio data source on its original recording.
int	METADATA_KEY_COLOR_RANGE This key retrieves the color range, if available.
int	METADATA_KEY_COLOR_STANDARD This key retrieves the color standard, if available.
int	METADATA_KEY_COLOR_TRANSFER This key retrieves the color transfer, if available.
int	METADATA_KEY_COMPILATION The metadata key to retrieve the music album compilation status.
int	METADATA_KEY_COMPOSER The metadata key to retrieve the information about the composer of the data source.
int	METADATA_KEY_DATE The metadata key to retrieve the date when the data source was created or modified.
int	METADATA_KEY_DISC_NUMBER The metadata key to retrieve the numberic string that describes which part of a set the audio data source comes from.
int	METADATA_KEY_DURATION The metadata key to retrieve the playback duration (in ms) of the data source.
int	METADATA_KEY_EXIF_LENGTH If the media contains EXIF data, this key retrieves the length (in bytes) of the data.
int	METADATA_KEY_EXIF_OFFSET If the media contains EXIF data, this key retrieves the offset (in bytes) of the data.
int	METADATA_KEY_GENRE The metadata key to retrieve the content type or genre of the data source.
int	METADATA_KEY_HAS_AUDIO If this key exists the media contains audio content.
int	METADATA_KEY_HAS_IMAGE If this key exists the media contains still image content.
int	METADATA_KEY_HAS_VIDEO If this key exists the media contains video content.
int	METADATA_KEY_IMAGE_COUNT If the media contains still images, this key retrieves the number of still images.
int	METADATA_KEY_IMAGE_HEIGHT If the media contains still images, this key retrieves the height of the primary image.
int	METADATA_KEY_IMAGE_PRIMARY If the media contains still images, this key retrieves the image index of the primary image.
int	METADATA_KEY_IMAGE_ROTATION If the media contains still images, this key retrieves the rotation angle (in degrees clockwise) of the primary image.
int	METADATA_KEY_IMAGE_WIDTH If the media contains still images, this key retrieves the width of the primary image.
int	METADATA_KEY_LOCATION This key retrieves the location information, if available.
int	METADATA_KEY_MIMETYPE The metadata key to retrieve the mime type of the data source.
int	METADATA_KEY_NUM_TRACKS The metadata key to retrieve the number of tracks, such as audio, video, text, in the data source, such as a mp4 or 3gpp file.
int	METADATA_KEY_SAMPLERATE This key retrieves the sample rate in Hz, if available.
int	METADATA_KEY_TITLE The metadata key to retrieve the data source title.
int	METADATA_KEY_VIDEO_FRAME_COUNT If the media contains video and this key exists, it retrieves the total number of frames in the video sequence.
int	METADATA_KEY_VIDEO_HEIGHT If the media contains video, this key retrieves its height.
int	METADATA_KEY_VIDEO_ROTATION This key retrieves the video rotation angle in degrees, if available.
int	METADATA_KEY_VIDEO_WIDTH If the media contains video, this key retrieves its width.
int	METADATA_KEY_WRITER The metadata key to retrieve the information of the writer (such as lyricist) of the data source.
int	METADATA_KEY_XMP_LENGTH If the media contains XMP data, this key retrieves the length (in bytes) of the data.
int	METADATA_KEY_XMP_OFFSET If the media contains XMP data, this key retrieves the offset (in bytes) of the data.
int	METADATA_KEY_YEAR The metadata key to retrieve the year when the data source was created or modified.
int	OPTION_CLOSEST This option is used with getFrameAtTime(long, int) to retrieve a frame (not necessarily a key frame) associated with a data source that is located closest to or at the given time.
int	OPTION_CLOSEST_SYNC This option is used with getFrameAtTime(long, int) to retrieve a sync (or key) frame associated with a data source that is located closest to (in time) or at the given time.
int	OPTION_NEXT_SYNC This option is used with getFrameAtTime(long, int) to retrieve a sync (or key) frame associated with a data source that is located right after or at the given time.
int	OPTION_PREVIOUS_SYNC This option is used with getFrameAtTime(long, int) to retrieve a sync (or key) frame associated with a data source that is located right before or at the given time.

Public constructors
MediaMetadataRetriever()

Public methods
void	close() Releases any acquired resources.
String	extractMetadata(int keyCode) Call this method after setDataSource().
byte[]	getEmbeddedPicture() Call this method after setDataSource().
Bitmap	getFrameAtIndex(int frameIndex, MediaMetadataRetriever.BitmapParams params) This method retrieves a video frame by its index.
Bitmap	getFrameAtIndex(int frameIndex) This method is similar to getFrameAtIndex(int, android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.
Bitmap	getFrameAtTime() Call this method after setDataSource().
Bitmap	getFrameAtTime(long timeUs, int option) This method is similar to getFrameAtTime(long, int, android.media.MediaMetadataRetriever.BitmapParams) except that the device will choose the actual Bitmap.Config to use.
Bitmap	getFrameAtTime(long timeUs) Call this method after setDataSource().
Bitmap	getFrameAtTime(long timeUs, int option, MediaMetadataRetriever.BitmapParams params) Call this method after setDataSource().
List<Bitmap>	getFramesAtIndex(int frameIndex, int numFrames) This method is similar to getFramesAtIndex(int, int, android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.
List<Bitmap>	getFramesAtIndex(int frameIndex, int numFrames, MediaMetadataRetriever.BitmapParams params) This method retrieves a consecutive set of video frames starting at the specified index.
Bitmap	getImageAtIndex(int imageIndex) This method is similar to getImageAtIndex(int, android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.
Bitmap	getImageAtIndex(int imageIndex, MediaMetadataRetriever.BitmapParams params) This method retrieves a still image by its index.
Bitmap	getPrimaryImage(MediaMetadataRetriever.BitmapParams params) This method retrieves the primary image of the media content.
Bitmap	getPrimaryImage() This method is similar to getPrimaryImage(android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.
Bitmap	getScaledFrameAtTime(long timeUs, int option, int dstWidth, int dstHeight, MediaMetadataRetriever.BitmapParams params) Retrieve a video frame near a given timestamp scaled to a desired size.
Bitmap	getScaledFrameAtTime(long timeUs, int option, int dstWidth, int dstHeight) This method is similar to getScaledFrameAtTime(long, int, int, int, android.media.MediaMetadataRetriever.BitmapParams) except that the device will choose the actual Bitmap.Config to use.
void	release() Releases any acquired resources.
void	setDataSource(FileDescriptor fd) Sets the data source (FileDescriptor) to use.
void	setDataSource(MediaDataSource dataSource) Sets the data source (MediaDataSource) to use.
void	setDataSource(FileDescriptor fd, long offset, long length) Sets the data source (FileDescriptor) to use.
void	setDataSource(String path) Sets the data source (file pathname) to use.
void	setDataSource(String uri, Map<String, String> headers) Sets the data source (URI) to use.
void	setDataSource(Context context, Uri uri) Sets the data source as a content Uri.

Protected methods
void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface java.lang.AutoCloseable abstract void close() Closes this resource, relinquishing any underlying resources.

Constants

METADATA_KEY_ALBUM

Added in API level 10

public static final int METADATA_KEY_ALBUM

The metadata key to retrieve the information about the album title of the data source.

Constant Value: 1 (0x00000001)

METADATA_KEY_ALBUMARTIST

Added in API level 10

public static final int METADATA_KEY_ALBUMARTIST

The metadata key to retrieve the information about the performers or artist associated with the data source.

Constant Value: 13 (0x0000000d)

METADATA_KEY_ARTIST

Added in API level 10

public static final int METADATA_KEY_ARTIST

The metadata key to retrieve the information about the artist of the data source.

Constant Value: 2 (0x00000002)

METADATA_KEY_AUTHOR

Added in API level 10

public static final int METADATA_KEY_AUTHOR

The metadata key to retrieve the information about the author of the data source.

Constant Value: 3 (0x00000003)

METADATA_KEY_BITRATE

Added in API level 14

public static final int METADATA_KEY_BITRATE

This key retrieves the average bitrate (in bits/sec), if available.

Constant Value: 20 (0x00000014)

METADATA_KEY_BITS_PER_SAMPLE

Added in API level 31

public static final int METADATA_KEY_BITS_PER_SAMPLE

This key retrieves the bits per sample in numbers of bits, if available. This is a signed 32-bit integer formatted as a string in base 10.

Constant Value: 39 (0x00000027)

METADATA_KEY_CAPTURE_FRAMERATE

Added in API level 23

public static final int METADATA_KEY_CAPTURE_FRAMERATE

This key retrieves the original capture framerate, if it's available. The capture framerate will be a floating point number.

Constant Value: 25 (0x00000019)

METADATA_KEY_CD_TRACK_NUMBER

Added in API level 10

public static final int METADATA_KEY_CD_TRACK_NUMBER

The metadata key to retrieve the numeric string describing the order of the audio data source on its original recording.

Constant Value: 0 (0x00000000)

METADATA_KEY_COLOR_RANGE

Added in API level 30

public static final int METADATA_KEY_COLOR_RANGE

This key retrieves the color range, if available.

See also:

• MediaFormat.COLOR_RANGE_LIMITED
• MediaFormat.COLOR_RANGE_FULL

Constant Value: 37 (0x00000025)

METADATA_KEY_COLOR_STANDARD

Added in API level 30

public static final int METADATA_KEY_COLOR_STANDARD

This key retrieves the color standard, if available.

See also:

• MediaFormat.COLOR_STANDARD_BT709
• MediaFormat.COLOR_STANDARD_BT601_PAL
• MediaFormat.COLOR_STANDARD_BT601_NTSC
• MediaFormat.COLOR_STANDARD_BT2020

Constant Value: 35 (0x00000023)

METADATA_KEY_COLOR_TRANSFER

Added in API level 30

public static final int METADATA_KEY_COLOR_TRANSFER

This key retrieves the color transfer, if available.

See also:

• MediaFormat.COLOR_TRANSFER_LINEAR
• MediaFormat.COLOR_TRANSFER_SDR_VIDEO
• MediaFormat.COLOR_TRANSFER_ST2084
• MediaFormat.COLOR_TRANSFER_HLG

Constant Value: 36 (0x00000024)

METADATA_KEY_COMPILATION

Added in API level 10

public static final int METADATA_KEY_COMPILATION

The metadata key to retrieve the music album compilation status.

Constant Value: 15 (0x0000000f)

METADATA_KEY_COMPOSER

Added in API level 10

public static final int METADATA_KEY_COMPOSER

The metadata key to retrieve the information about the composer of the data source.

Constant Value: 4 (0x00000004)

METADATA_KEY_DATE

Added in API level 10

public static final int METADATA_KEY_DATE

The metadata key to retrieve the date when the data source was created or modified.

Constant Value: 5 (0x00000005)

METADATA_KEY_DISC_NUMBER

Added in API level 10

public static final int METADATA_KEY_DISC_NUMBER

The metadata key to retrieve the numberic string that describes which part of a set the audio data source comes from.

Constant Value: 14 (0x0000000e)

METADATA_KEY_DURATION

Added in API level 10

public static final int METADATA_KEY_DURATION

The metadata key to retrieve the playback duration (in ms) of the data source.

Constant Value: 9 (0x00000009)

METADATA_KEY_EXIF_LENGTH

Added in API level 29

public static final int METADATA_KEY_EXIF_LENGTH

If the media contains EXIF data, this key retrieves the length (in bytes) of the data.

Constant Value: 34 (0x00000022)

METADATA_KEY_EXIF_OFFSET

Added in API level 29

public static final int METADATA_KEY_EXIF_OFFSET

If the media contains EXIF data, this key retrieves the offset (in bytes) of the data.

Constant Value: 33 (0x00000021)

METADATA_KEY_GENRE

Added in API level 10

public static final int METADATA_KEY_GENRE

The metadata key to retrieve the content type or genre of the data source.

Constant Value: 6 (0x00000006)

METADATA_KEY_HAS_AUDIO

Added in API level 14

public static final int METADATA_KEY_HAS_AUDIO

If this key exists the media contains audio content.

Constant Value: 16 (0x00000010)

METADATA_KEY_HAS_IMAGE

Added in API level 28

public static final int METADATA_KEY_HAS_IMAGE

If this key exists the media contains still image content.

Constant Value: 26 (0x0000001a)

METADATA_KEY_HAS_VIDEO

Added in API level 14

public static final int METADATA_KEY_HAS_VIDEO

If this key exists the media contains video content.

Constant Value: 17 (0x00000011)

METADATA_KEY_IMAGE_COUNT

Added in API level 28

public static final int METADATA_KEY_IMAGE_COUNT

If the media contains still images, this key retrieves the number of still images.

Constant Value: 27 (0x0000001b)

METADATA_KEY_IMAGE_HEIGHT

Added in API level 28

public static final int METADATA_KEY_IMAGE_HEIGHT

If the media contains still images, this key retrieves the height of the primary image.

Constant Value: 30 (0x0000001e)

METADATA_KEY_IMAGE_PRIMARY

Added in API level 28

public static final int METADATA_KEY_IMAGE_PRIMARY

If the media contains still images, this key retrieves the image index of the primary image.

Constant Value: 28 (0x0000001c)

METADATA_KEY_IMAGE_ROTATION

Added in API level 28

public static final int METADATA_KEY_IMAGE_ROTATION

If the media contains still images, this key retrieves the rotation angle (in degrees clockwise) of the primary image. The image rotation angle must be one of 0, 90, 180, or 270 degrees.

Constant Value: 31 (0x0000001f)

METADATA_KEY_IMAGE_WIDTH

Added in API level 28

public static final int METADATA_KEY_IMAGE_WIDTH

If the media contains still images, this key retrieves the width of the primary image.

Constant Value: 29 (0x0000001d)

METADATA_KEY_LOCATION

Added in API level 15

public static final int METADATA_KEY_LOCATION

This key retrieves the location information, if available. The location should be specified according to ISO-6709 standard, under a mp4/3gp box "@xyz". Location with longitude of -90 degrees and latitude of 180 degrees will be retrieved as "+180.0000-90.0000/", for instance.

Constant Value: 23 (0x00000017)

METADATA_KEY_MIMETYPE

Added in API level 10

public static final int METADATA_KEY_MIMETYPE

The metadata key to retrieve the mime type of the data source. Some example mime types include: "video/mp4", "audio/mp4", "audio/amr-wb", etc.

Constant Value: 12 (0x0000000c)

METADATA_KEY_NUM_TRACKS

Added in API level 10

public static final int METADATA_KEY_NUM_TRACKS

The metadata key to retrieve the number of tracks, such as audio, video, text, in the data source, such as a mp4 or 3gpp file.

Constant Value: 10 (0x0000000a)

METADATA_KEY_SAMPLERATE

Added in API level 31

public static final int METADATA_KEY_SAMPLERATE

This key retrieves the sample rate in Hz, if available. This is a signed 32-bit integer formatted as a string in base 10.

Constant Value: 38 (0x00000026)

METADATA_KEY_TITLE

Added in API level 10

public static final int METADATA_KEY_TITLE

The metadata key to retrieve the data source title.

Constant Value: 7 (0x00000007)

METADATA_KEY_VIDEO_FRAME_COUNT

Added in API level 28

public static final int METADATA_KEY_VIDEO_FRAME_COUNT

If the media contains video and this key exists, it retrieves the total number of frames in the video sequence.

Constant Value: 32 (0x00000020)

METADATA_KEY_VIDEO_HEIGHT

Added in API level 14

public static final int METADATA_KEY_VIDEO_HEIGHT

If the media contains video, this key retrieves its height.

Constant Value: 19 (0x00000013)

METADATA_KEY_VIDEO_ROTATION

Added in API level 17

public static final int METADATA_KEY_VIDEO_ROTATION

This key retrieves the video rotation angle in degrees, if available. The video rotation angle may be 0, 90, 180, or 270 degrees.

Constant Value: 24 (0x00000018)

METADATA_KEY_VIDEO_WIDTH

Added in API level 14

public static final int METADATA_KEY_VIDEO_WIDTH

If the media contains video, this key retrieves its width.

Constant Value: 18 (0x00000012)

METADATA_KEY_WRITER

Added in API level 10

public static final int METADATA_KEY_WRITER

The metadata key to retrieve the information of the writer (such as lyricist) of the data source.

Constant Value: 11 (0x0000000b)

METADATA_KEY_XMP_LENGTH

Added in API level 31

public static final int METADATA_KEY_XMP_LENGTH

If the media contains XMP data, this key retrieves the length (in bytes) of the data.

Constant Value: 42 (0x0000002a)

METADATA_KEY_XMP_OFFSET

Added in API level 31

public static final int METADATA_KEY_XMP_OFFSET

If the media contains XMP data, this key retrieves the offset (in bytes) of the data.

Constant Value: 41 (0x00000029)

METADATA_KEY_YEAR

Added in API level 10

public static final int METADATA_KEY_YEAR

The metadata key to retrieve the year when the data source was created or modified.

Constant Value: 8 (0x00000008)

OPTION_CLOSEST

Added in API level 10

public static final int OPTION_CLOSEST

This option is used with getFrameAtTime(long, int) to retrieve a frame (not necessarily a key frame) associated with a data source that is located closest to or at the given time.

See also:

• getFrameAtTime(long, int)

Constant Value: 3 (0x00000003)

OPTION_CLOSEST_SYNC

Added in API level 10

public static final int OPTION_CLOSEST_SYNC

This option is used with getFrameAtTime(long, int) to retrieve a sync (or key) frame associated with a data source that is located closest to (in time) or at the given time.

See also:

• getFrameAtTime(long, int)

Constant Value: 2 (0x00000002)

OPTION_NEXT_SYNC

Added in API level 10

public static final int OPTION_NEXT_SYNC

This option is used with getFrameAtTime(long, int) to retrieve a sync (or key) frame associated with a data source that is located right after or at the given time.

See also:

• getFrameAtTime(long, int)

Constant Value: 1 (0x00000001)

OPTION_PREVIOUS_SYNC

Added in API level 10

public static final int OPTION_PREVIOUS_SYNC

This option is used with getFrameAtTime(long, int) to retrieve a sync (or key) frame associated with a data source that is located right before or at the given time.

See also:

• getFrameAtTime(long, int)

Constant Value: 0 (0x00000000)

Public constructors

MediaMetadataRetriever

Added in API level 10

public MediaMetadataRetriever ()

Public methods

close

Added in API level 29

public void close ()

Releases any acquired resources. Call it when done with the object.

Throws
IOException	When an IOException is thrown while closing a MediaDataSource passed to setDataSource(android.media.MediaDataSource). This throws clause exists since API Build.VERSION_CODES.TIRAMISU, but this method can throw in earlier API versions where the exception is not declared.

extractMetadata

Added in API level 10

public String extractMetadata (int keyCode)

Call this method after setDataSource(). This method retrieves the meta data value associated with the keyCode. The keyCode currently supported is listed below as METADATA_XXX constants. With any other value, it returns a null pointer.

Parameters
keyCode	int: One of the constants listed below at the end of the class.

Returns
String	The meta data value associate with the given keyCode on success; null on failure.

getEmbeddedPicture

Added in API level 10

public byte[] getEmbeddedPicture ()

Call this method after setDataSource(). This method finds the optional graphic or album/cover art associated associated with the data source. If there are more than one pictures, (any) one of them is returned.

Returns
byte[]	null if no such graphic is found.

getFrameAtIndex

Added in API level 28

public Bitmap getFrameAtIndex (int frameIndex, 
                MediaMetadataRetriever.BitmapParams params)

This method retrieves a video frame by its index. It should only be called after setDataSource(Context, Uri). After the bitmap is returned, you can query the actual parameters that were used to create the bitmap from the BitmapParams argument, for instance to query the bitmap config used for the bitmap with BitmapParams#getActualConfig.

Parameters
frameIndex	int: 0-based index of the video frame. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key.
params	MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null.

Returns
Bitmap	A Bitmap containing the requested video frame, or null if the retrieval fails.

Throws
IllegalStateException	if the container doesn't contain video or image sequences.
IllegalArgumentException	if the requested frame index does not exist.

See also:

• getFrameAtIndex(int)
• getFramesAtIndex(int, int, BitmapParams)
• getFramesAtIndex(int, int)

getFrameAtIndex

Added in API level 28

public Bitmap getFrameAtIndex (int frameIndex)

This method is similar to getFrameAtIndex(int, android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.

Parameters
frameIndex	int: 0-based index of the video frame. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key.

Returns
Bitmap	A Bitmap containing the requested video frame, or null if the retrieval fails.

Throws
IllegalStateException	if the container doesn't contain video or image sequences.
IllegalArgumentException	if the requested frame index does not exist.

See also:

• getFrameAtIndex(int, BitmapParams)
• getFramesAtIndex(int, int, BitmapParams)
• getFramesAtIndex(int, int)

getFrameAtTime

Added in API level 10

public Bitmap getFrameAtTime ()

Call this method after setDataSource(). This method finds a representative frame at any time position if possible, and returns it as a bitmap. Call this method if one does not care about where the frame is located; otherwise, please call getFrameAtTime(long) or getFrameAtTime(long, int)

If you don't need a full-resolution frame (for example, because you need a thumbnail image), use getScaledFrameAtTime() instead of this method.

Returns
Bitmap	A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved.

See also:

• getFrameAtTime(long)
• getFrameAtTime(long, int)

getFrameAtTime

Added in API level 10

public Bitmap getFrameAtTime (long timeUs, 
                int option)

This method is similar to getFrameAtTime(long, int, android.media.MediaMetadataRetriever.BitmapParams) except that the device will choose the actual Bitmap.Config to use.

Parameters
timeUs	long: The time position where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned.
option	int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is OPTION_PREVIOUS_SYNC, OPTION_NEXT_SYNC, OPTION_CLOSEST_SYNC, or OPTION_CLOSEST

Returns
Bitmap	A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved. Bitmap#getConfig() can be used to query the actual Bitmap.Config.

See also:

• getFrameAtTime(long, int, BitmapParams)

getFrameAtTime

Added in API level 10

public Bitmap getFrameAtTime (long timeUs)

Call this method after setDataSource(). This method finds a representative frame close to the given time position if possible, and returns it as a bitmap. Call this method if one does not care how the frame is found as long as it is close to the given time; otherwise, please call getFrameAtTime(long, int).

If you don't need a full-resolution frame (for example, because you need a thumbnail image), use getScaledFrameAtTime() instead of this method.

Parameters
timeUs	long: The time position where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarentee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned.

Returns
Bitmap	A Bitmap of size dst_widthxdst_height containing a representative video frame, which can be null, if such a frame cannot be retrieved.

See also:

• getFrameAtTime(long, int)

getFrameAtTime

Added in API level 30

public Bitmap getFrameAtTime (long timeUs, 
                int option, 
                MediaMetadataRetriever.BitmapParams params)

Call this method after setDataSource(). This method finds a representative frame close to the given time position by considering the given option if possible, and returns it as a bitmap.

If you don't need a full-resolution frame (for example, because you need a thumbnail image), use getScaledFrameAtTime() instead of this method.

Parameters
timeUs	long: The time position where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned.
option	int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is OPTION_PREVIOUS_SYNC, OPTION_NEXT_SYNC, OPTION_CLOSEST_SYNC, or OPTION_CLOSEST
params	MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null.

Returns
Bitmap	A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved.

See also:

• getFrameAtTime(long, int)

getFramesAtIndex

Added in API level 28

public List<Bitmap> getFramesAtIndex (int frameIndex, 
                int numFrames)

This method is similar to getFramesAtIndex(int, int, android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.

Parameters
frameIndex	int: 0-based index of the first video frame to retrieve. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key.
numFrames	int: number of consecutive video frames to retrieve. Must be a positive value. The stream must contain at least numFrames frames starting at frameIndex.

Returns
List<Bitmap>	An list of Bitmaps containing the requested video frames. The returned array could contain less frames than requested if the retrieval fails. This value cannot be null.

Throws
IllegalStateException	if the container doesn't contain video or image sequences.
IllegalArgumentException	if the frameIndex or numFrames is invalid, or the stream doesn't contain at least numFrames starting at frameIndex.

See also:

• getFrameAtIndex(int, BitmapParams)
• getFrameAtIndex(int)
• getFramesAtIndex(int, int, BitmapParams)

getFramesAtIndex

Added in API level 28

public List<Bitmap> getFramesAtIndex (int frameIndex, 
                int numFrames, 
                MediaMetadataRetriever.BitmapParams params)

This method retrieves a consecutive set of video frames starting at the specified index. It should only be called after setDataSource(Context, Uri). If the caller intends to retrieve more than one consecutive video frames, this method is preferred over getFrameAtIndex(int, android.media.MediaMetadataRetriever.BitmapParams) for efficiency. After the bitmaps are returned, you can query the actual parameters that were used to create the bitmaps from the BitmapParams argument, for instance to query the bitmap config used for the bitmaps with BitmapParams#getActualConfig.

Parameters
frameIndex	int: 0-based index of the first video frame to retrieve. The frame index must be that of a valid frame. The total number of frames available for retrieval can be queried via the METADATA_KEY_VIDEO_FRAME_COUNT key.
numFrames	int: number of consecutive video frames to retrieve. Must be a positive value. The stream must contain at least numFrames frames starting at frameIndex.
params	MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null.

Returns
List<Bitmap>	An list of Bitmaps containing the requested video frames. The returned array could contain less frames than requested if the retrieval fails. This value cannot be null.

Throws
IllegalStateException	if the container doesn't contain video or image sequences.
IllegalArgumentException	if the frameIndex or numFrames is invalid, or the stream doesn't contain at least numFrames starting at frameIndex.

See also:

• getFrameAtIndex(int, BitmapParams)
• getFrameAtIndex(int)
• getFramesAtIndex(int, int)

getImageAtIndex

Added in API level 28

public Bitmap getImageAtIndex (int imageIndex)

This method is similar to getImageAtIndex(int, android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.

Parameters
imageIndex	int: 0-based index of the image.

Returns
Bitmap	the requested still image, or null if the image cannot be retrieved.

Throws
IllegalStateException	if the container doesn't contain still images.
IllegalArgumentException	if the requested image does not exist.

See also:

• getImageAtIndex(int, BitmapParams)
• getPrimaryImage(BitmapParams)
• getPrimaryImage()

getImageAtIndex

Added in API level 28

public Bitmap getImageAtIndex (int imageIndex, 
                MediaMetadataRetriever.BitmapParams params)

This method retrieves a still image by its index. It should only be called after setDataSource(Context, Uri). After the bitmap is returned, you can query the actual parameters that were used to create the bitmap from the BitmapParams argument, for instance to query the bitmap config used for the bitmap with BitmapParams#getActualConfig.

Parameters
imageIndex	int: 0-based index of the image.
params	MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null.

Returns
Bitmap	the requested still image, or null if the image cannot be retrieved.

Throws
IllegalStateException	if the container doesn't contain still images.
IllegalArgumentException	if the requested image does not exist.

See also:

• getImageAtIndex(int)
• getPrimaryImage(BitmapParams)
• getPrimaryImage()

getPrimaryImage

Added in API level 28

public Bitmap getPrimaryImage (MediaMetadataRetriever.BitmapParams params)

This method retrieves the primary image of the media content. It should only be called after setDataSource(Context, Uri). After the bitmap is returned, you can query the actual parameters that were used to create the bitmap from the BitmapParams argument, for instance to query the bitmap config used for the bitmap with BitmapParams#getActualConfig.

Parameters
params	MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null.

Returns
Bitmap	the primary image, or null if it cannot be retrieved.

Throws
IllegalStateException	if the container doesn't contain still images.

See also:

• getImageAtIndex(int, BitmapParams)
• getImageAtIndex(int)
• getPrimaryImage()

getPrimaryImage

Added in API level 28

public Bitmap getPrimaryImage ()

This method is similar to getPrimaryImage(android.media.MediaMetadataRetriever.BitmapParams) except that the default for BitmapParams will be used.

Returns
Bitmap	the primary image, or null if it cannot be retrieved.

Throws
IllegalStateException	if the container doesn't contain still images.

See also:

• getImageAtIndex(int, BitmapParams)
• getImageAtIndex(int)
• getPrimaryImage(BitmapParams)

getScaledFrameAtTime

Added in API level 30

public Bitmap getScaledFrameAtTime (long timeUs, 
                int option, 
                int dstWidth, 
                int dstHeight, 
                MediaMetadataRetriever.BitmapParams params)

Retrieve a video frame near a given timestamp scaled to a desired size. Call this method after setDataSource(). This method finds a representative frame close to the given time position by considering the given option if possible, and returns it as a bitmap with same aspect ratio as the source while scaling it so that it fits into the desired size of dst_width by dst_height. This is useful for generating a thumbnail for an input data source or just to obtain a scaled frame at the given time position.

Parameters
timeUs	long: The time position in microseconds where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned.
option	int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is OPTION_PREVIOUS_SYNC, OPTION_NEXT_SYNC, OPTION_CLOSEST_SYNC, or OPTION_CLOSEST
dstWidth	int: expected output bitmap width Value is 1 or greater
dstHeight	int: expected output bitmap height Value is 1 or greater
params	MediaMetadataRetriever.BitmapParams: BitmapParams that controls the returned bitmap config (such as pixel formats). This value cannot be null.

Returns
Bitmap	A Bitmap of size not larger than dstWidth by dstHeight containing a scaled video frame, which can be null, if such a frame cannot be retrieved.

Throws
IllegalArgumentException	if passed in invalid option or width by height is less than or equal to 0.

See also:

• getScaledFrameAtTime(long, int, int, int)

getScaledFrameAtTime

Added in API level 27

public Bitmap getScaledFrameAtTime (long timeUs, 
                int option, 
                int dstWidth, 
                int dstHeight)

This method is similar to getScaledFrameAtTime(long, int, int, int, android.media.MediaMetadataRetriever.BitmapParams) except that the device will choose the actual Bitmap.Config to use.

Parameters
timeUs	long: The time position in microseconds where the frame will be retrieved. When retrieving the frame at the given time position, there is no guarantee that the data source has a frame located at the position. When this happens, a frame nearby will be returned. If timeUs is negative, time position and option will ignored, and any frame that the implementation considers as representative may be returned.
option	int: a hint on how the frame is found. Use OPTION_PREVIOUS_SYNC if one wants to retrieve a sync frame that has a timestamp earlier than or the same as timeUs. Use OPTION_NEXT_SYNC if one wants to retrieve a sync frame that has a timestamp later than or the same as timeUs. Use OPTION_CLOSEST_SYNC if one wants to retrieve a sync frame that has a timestamp closest to or the same as timeUs. Use OPTION_CLOSEST if one wants to retrieve a frame that may or may not be a sync frame but is closest to or the same as timeUs. OPTION_CLOSEST often has larger performance overhead compared to the other options if there is no sync frame located at timeUs. Value is OPTION_PREVIOUS_SYNC, OPTION_NEXT_SYNC, OPTION_CLOSEST_SYNC, or OPTION_CLOSEST
dstWidth	int: expected output bitmap width Value is 1 or greater
dstHeight	int: expected output bitmap height Value is 1 or greater

Returns
Bitmap	A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved. Bitmap#getConfig() can be used to query the actual Bitmap.Config.

Throws
IllegalArgumentException	if passed in invalid option or width by height is less than or equal to 0.

See also:

• getScaledFrameAtTime(long, int, int, int, BitmapParams)

release

Added in API level 10

public void release ()

Releases any acquired resources. Call it when done with the object.

Throws
IOException	When an IOException is thrown while closing a MediaDataSource passed to setDataSource(android.media.MediaDataSource). This throws clause exists since API Build.VERSION_CODES.TIRAMISU, but this method can throw in earlier API versions where the exception is not declared.

setDataSource

Added in API level 10

public void setDataSource (FileDescriptor fd)

Sets the data source (FileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns. Call this method before the rest of the methods in this class. This method may be time-consuming.

Parameters
fd	FileDescriptor: the FileDescriptor for the file you want to play

Throws
IllegalArgumentException	if the FileDescriptor is invalid

setDataSource

Added in API level 23

public void setDataSource (MediaDataSource dataSource)

Sets the data source (MediaDataSource) to use.

Parameters
dataSource	MediaDataSource: the MediaDataSource for the media you want to play

Throws
IllegalArgumentException

setDataSource

Added in API level 10

public void setDataSource (FileDescriptor fd, 
                long offset, 
                long length)

Sets the data source (FileDescriptor) to use. It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns. Call this method before the rest of the methods in this class. This method may be time-consuming.

Parameters
fd	FileDescriptor: the FileDescriptor for the file you want to play
offset	long: the offset into the file where the data to be played starts, in bytes. It must be non-negative
length	long: the length in bytes of the data to be played. It must be non-negative.

Throws
IllegalArgumentException	if the arguments are invalid

setDataSource

Added in API level 10

public void setDataSource (String path)

Sets the data source (file pathname) to use. Call this method before the rest of the methods in this class. This method may be time-consuming.

Parameters
path	String: The path, or the URI (doesn't support streaming source currently) of the input media file.

Throws
IllegalArgumentException	If the path is invalid.

setDataSource

Added in API level 14

public void setDataSource (String uri, 
                Map<String, String> headers)

Sets the data source (URI) to use. Call this method before the rest of the methods in this class. This method may be time-consuming.

Parameters
uri	String: The URI of the input media.
headers	Map: the headers to be sent together with the request for the data

Throws
IllegalArgumentException	If the URI is invalid.

setDataSource

Added in API level 10

public void setDataSource (Context context, 
                Uri uri)

Sets the data source as a content Uri. Call this method before the rest of the methods in this class. This method may be time-consuming.

Parameters
context	Context: the Context to use when resolving the Uri
uri	Uri: the Content URI of the data you want to play

Throws
IllegalArgumentException	if the Uri is invalid
SecurityException	if the Uri cannot be used due to lack of permission.

Protected methods

finalize

Added in API level 10

protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable