Skip to content

Most visited

Recently visited

navigation
Added in API level 10

MediaMetadataRetriever

public class MediaMetadataRetriever
extends Object

java.lang.Object
   ↳ android.media.MediaMetadataRetriever


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

Summary

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_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_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 of the data source.

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_VIDEO

If this key exists the media contains video content.

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_TITLE

The metadata key to retrieve the data source title.

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_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

String extractMetadata(int keyCode)

Call this method after setDataSource().

byte[] getEmbeddedPicture()

Call this method after setDataSource().

Bitmap getFrameAtTime(long timeUs)

Call this method after setDataSource().

Bitmap getFrameAtTime(long timeUs, int option)

Call this method after setDataSource().

Bitmap getFrameAtTime()

Call this method after setDataSource().

void release()

Call it when one is done with the object.

void setDataSource(String path)

Sets the data source (file pathname) to use.

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

Sets the data source (URI) to use.

void setDataSource(FileDescriptor fd)

Sets the data source (FileDescriptor) to use.

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

Sets the data source (FileDescriptor) to use.

void setDataSource(MediaDataSource dataSource)

Sets the data source (MediaDataSource) to use.

void setDataSource(Context context, Uri uri)

Sets the data source as a content Uri.

Protected methods

void finalize()

Invoked when the garbage collector has detected that this instance is no longer reachable.

Inherited methods

From class java.lang.Object

Constants

METADATA_KEY_ALBUM

Added in API level 10
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
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
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
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
int METADATA_KEY_BITRATE

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

Constant Value: 20 (0x00000014)

METADATA_KEY_CAPTURE_FRAMERATE

Added in API level 23
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
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_COMPILATION

Added in API level 10
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
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
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
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
int METADATA_KEY_DURATION

The metadata key to retrieve the playback duration of the data source.

Constant Value: 9 (0x00000009)

METADATA_KEY_GENRE

Added in API level 10
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
int METADATA_KEY_HAS_AUDIO

If this key exists the media contains audio content.

Constant Value: 16 (0x00000010)

METADATA_KEY_HAS_VIDEO

Added in API level 14
int METADATA_KEY_HAS_VIDEO

If this key exists the media contains video content.

Constant Value: 17 (0x00000011)

METADATA_KEY_LOCATION

Added in API level 15
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 "-90.0000+180.0000", for instance.

Constant Value: 23 (0x00000017)

METADATA_KEY_MIMETYPE

Added in API level 10
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
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_TITLE

Added in API level 10
int METADATA_KEY_TITLE

The metadata key to retrieve the data source title.

Constant Value: 7 (0x00000007)

METADATA_KEY_VIDEO_HEIGHT

Added in API level 14
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
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
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
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_YEAR

Added in API level 10
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
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:

Constant Value: 3 (0x00000003)

OPTION_CLOSEST_SYNC

Added in API level 10
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:

Constant Value: 2 (0x00000002)

OPTION_NEXT_SYNC

Added in API level 10
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:

Constant Value: 1 (0x00000001)

OPTION_PREVIOUS_SYNC

Added in API level 10
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:

Constant Value: 0 (0x00000000)

Public constructors

MediaMetadataRetriever

Added in API level 10
MediaMetadataRetriever ()

Public methods

extractMetadata

Added in API level 10
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
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.

getFrameAtTime

Added in API level 10
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. This is useful for generating a thumbnail for an input data source. 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).

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 containing a representative video frame, which can be null, if such a frame cannot be retrieved.

See also:

getFrameAtTime

Added in API level 10
Bitmap getFrameAtTime (long timeUs, 
                int option)

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. This is useful for generating a thumbnail for an input data source or just obtain and display a frame at the given time position.

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.
Returns
Bitmap A Bitmap containing a representative video frame, which can be null, if such a frame cannot be retrieved.

getFrameAtTime

Added in API level 10
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. This is useful for generating a thumbnail for an input data source. Call this method if one does not care about where the frame is located; otherwise, please call getFrameAtTime(long) or getFrameAtTime(long, int)

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

See also:

release

Added in API level 10
void release ()

Call it when one is done with the object. This method releases the memory allocated internally.

setDataSource

Added in API level 10
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 of the input media file.
Throws
IllegalArgumentException If the path is invalid.

setDataSource

Added in API level 14
void setDataSource (String uri, 
                Map<StringString> 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
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 10
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 23
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
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
void finalize ()

Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.

Throws
Throwable
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.