FileDocCategorySizeDatePackage
MediaMetadataRetriever.javaAPI DocAndroid 5.1 API19191Thu Mar 12 22:22:30 GMT 2015android.media

MediaMetadataRetriever

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

Fields Summary
private long
mNativeContext
private static final int
EMBEDDED_PICTURE_TYPE_ANY
public static final int
OPTION_PREVIOUS_SYNC
This option is used with {@link #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 static final int
OPTION_NEXT_SYNC
This option is used with {@link #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.
public static final int
OPTION_CLOSEST_SYNC
This option is used with {@link #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.
public static final int
OPTION_CLOSEST
This option is used with {@link #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.
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.
public static final int
METADATA_KEY_ALBUM
The metadata key to retrieve the information about the album title of the data source.
public static final int
METADATA_KEY_ARTIST
The metadata key to retrieve the information about the artist of the data source.
public static final int
METADATA_KEY_AUTHOR
The metadata key to retrieve the information about the author of the data source.
public static final int
METADATA_KEY_COMPOSER
The metadata key to retrieve the information about the composer of the data source.
public static final int
METADATA_KEY_DATE
The metadata key to retrieve the date when the data source was created or modified.
public static final int
METADATA_KEY_GENRE
The metadata key to retrieve the content type or genre of the data source.
public static final int
METADATA_KEY_TITLE
The metadata key to retrieve the data source title.
public static final int
METADATA_KEY_YEAR
The metadata key to retrieve the year when the data source was created or modified.
public static final int
METADATA_KEY_DURATION
The metadata key to retrieve the playback duration of the data source.
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.
public static final int
METADATA_KEY_WRITER
The metadata key to retrieve the information of the writer (such as lyricist) of the data source.
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.
public static final int
METADATA_KEY_ALBUMARTIST
The metadata key to retrieve the information about the performers or artist associated with the data source.
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.
public static final int
METADATA_KEY_COMPILATION
The metadata key to retrieve the music album compilation status.
public static final int
METADATA_KEY_HAS_AUDIO
If this key exists the media contains audio content.
public static final int
METADATA_KEY_HAS_VIDEO
If this key exists the media contains video content.
public static final int
METADATA_KEY_VIDEO_WIDTH
If the media contains video, this key retrieves its width.
public static final int
METADATA_KEY_VIDEO_HEIGHT
If the media contains video, this key retrieves its height.
public static final int
METADATA_KEY_BITRATE
This key retrieves the average bitrate (in bits/sec), if available.
public static final int
METADATA_KEY_TIMED_TEXT_LANGUAGES
This key retrieves the language code of text tracks, if available. If multiple text tracks present, the return value will look like: "eng:chi"
public static final int
METADATA_KEY_IS_DRM
If this key exists the media is drm-protected.
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 "-90.0000+180.0000", for instance.
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.
Constructors Summary
public MediaMetadataRetriever()


      
        native_setup();
Methods Summary
private native android.graphics.Bitmap_getFrameAtTime(long timeUs, int option)

private native void_setDataSource(android.os.IBinder httpServiceBinder, java.lang.String uri, java.lang.String[] keys, java.lang.String[] values)
public native java.lang.StringextractMetadata(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.
param
keyCode One of the constants listed below at the end of the class.
return
The meta data value associate with the given keyCode on success;
null on failure.
protected voidfinalize()
        try {
            native_finalize();
        } finally {
            super.finalize();
        }
    
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.
return
null if no such graphic is found.
        return getEmbeddedPicture(EMBEDDED_PICTURE_TYPE_ANY);
    
private native byte[]getEmbeddedPicture(int pictureType)
public android.graphics.BitmapgetFrameAtTime(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 {@link #getFrameAtTime(long, int)}.
param
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.
return
A Bitmap containing a representative video frame, which
can be null, if such a frame cannot be retrieved.
see
#getFrameAtTime(long, int)
        return getFrameAtTime(timeUs, OPTION_CLOSEST_SYNC);
    
public android.graphics.BitmapgetFrameAtTime()
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
{@link #getFrameAtTime(long)} or {@link #getFrameAtTime(long, int)}
return
A Bitmap containing a representative video frame, which
can be null, if such a frame cannot be retrieved.
see
#getFrameAtTime(long)
see
#getFrameAtTime(long, int)
        return getFrameAtTime(-1, OPTION_CLOSEST_SYNC);
    
public android.graphics.BitmapgetFrameAtTime(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.
param
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.
param
option a hint on how the frame is found. Use
{@link #OPTION_PREVIOUS_SYNC} if one wants to retrieve a sync frame
that has a timestamp earlier than or the same as timeUs. Use
{@link #OPTION_NEXT_SYNC} if one wants to retrieve a sync frame
that has a timestamp later than or the same as timeUs. Use
{@link #OPTION_CLOSEST_SYNC} if one wants to retrieve a sync frame
that has a timestamp closest to or the same as timeUs. Use
{@link #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.
{@link #OPTION_CLOSEST} often has larger performance overhead compared
to the other options if there is no sync frame located at timeUs.
return
A Bitmap containing a representative video frame, which
can be null, if such a frame cannot be retrieved.
        if (option < OPTION_PREVIOUS_SYNC ||
            option > OPTION_CLOSEST) {
            throw new IllegalArgumentException("Unsupported option: " + option);
        }

        return _getFrameAtTime(timeUs, option);
    
private final native voidnative_finalize()
private static native voidnative_init()
private native voidnative_setup()
public native voidrelease()
Call it when one is done with the object. This method releases the memory
allocated internally.
public voidsetDataSource(java.lang.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.
param
path The path of the input media file.
throws
IllegalArgumentException If the path is invalid.
        if (path == null) {
            throw new IllegalArgumentException();
        }

        FileInputStream is = null;
        try {
            is = new FileInputStream(path);
            FileDescriptor fd = is.getFD();
            setDataSource(fd, 0, 0x7ffffffffffffffL);
        } catch (FileNotFoundException fileEx) {
            throw new IllegalArgumentException();
        } catch (IOException ioEx) {
            throw new IllegalArgumentException();
        }

        try {
            if (is != null) {
                is.close();
            }
        } catch (Exception e) {}
    
public voidsetDataSource(java.lang.String uri, java.util.Map 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.
param
uri The URI of the input media.
param
headers the headers to be sent together with the request for the data
throws
IllegalArgumentException If the URI is invalid.
        int i = 0;
        String[] keys = new String[headers.size()];
        String[] values = new String[headers.size()];
        for (Map.Entry<String, String> entry: headers.entrySet()) {
            keys[i] = entry.getKey();
            values[i] = entry.getValue();
            ++i;
        }

        _setDataSource(
                MediaHTTPService.createHttpServiceBinderIfNecessary(uri),
                uri,
                keys,
                values);
    
public native voidsetDataSource(java.io.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.
param
fd the FileDescriptor for the file you want to play
param
offset the offset into the file where the data to be played starts,
in bytes. It must be non-negative
param
length the length in bytes of the data to be played. It must be
non-negative.
throws
IllegalArgumentException if the arguments are invalid
public voidsetDataSource(java.io.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.
param
fd the FileDescriptor for the file you want to play
throws
IllegalArgumentException if the FileDescriptor is invalid
        // intentionally less than LONG_MAX
        setDataSource(fd, 0, 0x7ffffffffffffffL);
    
public voidsetDataSource(android.content.Context context, android.net.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.
param
context the Context to use when resolving the Uri
param
uri the Content URI of the data you want to play
throws
IllegalArgumentException if the Uri is invalid
throws
SecurityException if the Uri cannot be used due to lack of
permission.
        if (uri == null) {
            throw new IllegalArgumentException();
        }
        
        String scheme = uri.getScheme();
        if(scheme == null || scheme.equals("file")) {
            setDataSource(uri.getPath());
            return;
        }

        AssetFileDescriptor fd = null;
        try {
            ContentResolver resolver = context.getContentResolver();
            try {
                fd = resolver.openAssetFileDescriptor(uri, "r");
            } catch(FileNotFoundException e) {
                throw new IllegalArgumentException();
            }
            if (fd == null) {
                throw new IllegalArgumentException();
            }
            FileDescriptor descriptor = fd.getFileDescriptor();
            if (!descriptor.valid()) {
                throw new IllegalArgumentException();
            }
            // Note: using getDeclaredLength so that our behavior is the same
            // as previous versions when the content provider is returning
            // a full file.
            if (fd.getDeclaredLength() < 0) {
                setDataSource(descriptor);
            } else {
                setDataSource(descriptor, fd.getStartOffset(), fd.getDeclaredLength());
            }
            return;
        } catch (SecurityException ex) {
        } finally {
            try {
                if (fd != null) {
                    fd.close();
                }
            } catch(IOException ioEx) {
            }
        }
        setDataSource(uri.toString());