public class

MediaMetadataRetriever

extends Object
java.lang.Object
   ↳ android.media.MediaMetadataRetriever

Class Overview

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_CD_TRACK_NUMBER The metadata key to retrieve the numberic 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_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_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, int option)
Call this method after setDataSource().
Bitmap getFrameAtTime(long timeUs)
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(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(FileDescriptor fd)
Sets the data source (FileDescriptor) to use.
void setDataSource(Context context, Uri uri)
Sets the data source as a content Uri.
Protected Methods
void finalize()
Called before the object's memory is reclaimed by the VM.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int METADATA_KEY_ALBUM

Since: API Level 10

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

Constant Value: 1 (0x00000001)

public static final int METADATA_KEY_ALBUMARTIST

Since: API Level 10

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

Constant Value: 13 (0x0000000d)

public static final int METADATA_KEY_ARTIST

Since: API Level 10

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

Constant Value: 2 (0x00000002)

public static final int METADATA_KEY_AUTHOR

Since: API Level 10

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

Constant Value: 3 (0x00000003)

public static final int METADATA_KEY_CD_TRACK_NUMBER

Since: API Level 10

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

Constant Value: 0 (0x00000000)

public static final int METADATA_KEY_COMPILATION

Since: API Level 10

The metadata key to retrieve the music album compilation status.

Constant Value: 15 (0x0000000f)

public static final int METADATA_KEY_COMPOSER

Since: API Level 10

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

Constant Value: 4 (0x00000004)

public static final int METADATA_KEY_DATE

Since: API Level 10

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

Constant Value: 5 (0x00000005)

public static final int METADATA_KEY_DISC_NUMBER

Since: API Level 10

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)

public static final int METADATA_KEY_DURATION

Since: API Level 10

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

Constant Value: 9 (0x00000009)

public static final int METADATA_KEY_GENRE

Since: API Level 10

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

Constant Value: 6 (0x00000006)

public static final int METADATA_KEY_MIMETYPE

Since: API Level 10

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)

public static final int METADATA_KEY_NUM_TRACKS

Since: API Level 10

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)

public static final int METADATA_KEY_TITLE

Since: API Level 10

The metadata key to retrieve the data source title.

Constant Value: 7 (0x00000007)

public static final int METADATA_KEY_WRITER

Since: API Level 10

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

Constant Value: 11 (0x0000000b)

public static final int METADATA_KEY_YEAR

Since: API Level 10

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

Constant Value: 8 (0x00000008)

public static final int OPTION_CLOSEST

Since: API Level 10

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.

Constant Value: 3 (0x00000003)

public static final int OPTION_CLOSEST_SYNC

Since: API Level 10

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.

Constant Value: 2 (0x00000002)

public static final int OPTION_NEXT_SYNC

Since: API Level 10

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.

Constant Value: 1 (0x00000001)

public static final int OPTION_PREVIOUS_SYNC

Since: API Level 10

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.

Constant Value: 0 (0x00000000)

Public Constructors

public MediaMetadataRetriever ()

Since: API Level 10

Public Methods

public String extractMetadata (int keyCode)

Since: API Level 10

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 One of the constants listed below at the end of the class.
Returns
  • The meta data value associate with the given keyCode on success; null on failure.

public byte[] getEmbeddedPicture ()

Since: API Level 10

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

Returns
  • null if no such graphic is found.

public Bitmap getFrameAtTime (long timeUs, int option)

Since: API Level 10

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

public Bitmap getFrameAtTime (long timeUs)

Since: API Level 10

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

public Bitmap getFrameAtTime ()

Since: API Level 10

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

public void release ()

Since: API Level 10

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

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

Since: API Level 10

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 the FileDescriptor for the file you want to play
offset the offset into the file where the data to be played starts, in bytes. It must be non-negative
length the length in bytes of the data to be played. It must be non-negative.
Throws
IllegalArgumentException if the arguments are invalid

public void setDataSource (String path)

Since: API Level 10

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 The path of the input media file.
Throws
IllegalArgumentException If the path is invalid.

public void setDataSource (FileDescriptor fd)

Since: API Level 10

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 the FileDescriptor for the file you want to play
Throws
IllegalArgumentException if the FileDescriptor is invalid

public void setDataSource (Context context, Uri uri)

Since: API Level 10

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 the Context to use when resolving the 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

protected void finalize ()

Since: API Level 10

Called before the object's memory is reclaimed by the VM. This can only happen once the garbage collector has detected that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.

Throws
Throwable