wseemann.media

Class FFmpegMediaMetadataRetriever

java.lang.Object

wseemann.media.FFmpegMediaMetadataRetriever

public class FFmpegMediaMetadataRetriever
extends java.lang.Object

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

Field Summary

Fields

Modifier and Type	Field and Description
static Bitmap.Config	IN_PREFERRED_CONFIG User defined bitmap configuration.
static java.lang.String	METADATA_CHAPTER_COUNT The metadata key to retrieve the chapter count.
static java.lang.String	METADATA_KEY_ALBUM The metadata key to retrieve the name of the set this work belongs to.
static java.lang.String	METADATA_KEY_ALBUM_ARTIST The metadata key to retrieve the main creator of the set/album, if different from artist.
static java.lang.String	METADATA_KEY_ARTIST The metadata key to retrieve the main creator of the work.
static java.lang.String	METADATA_KEY_AUDIO_CODEC The metadata key to retrieve the audio codec of the work.
static java.lang.String	METADATA_KEY_CHAPTER_END_TIME The metadata key to retrieve the chapter end time in milliseconds.
static java.lang.String	METADATA_KEY_CHAPTER_START_TIME The metadata key to retrieve the chapter start time in milliseconds.
static java.lang.String	METADATA_KEY_COMMENT The metadata key to retrieve the any additional description of the file.
static java.lang.String	METADATA_KEY_COMPOSER The metadata key to retrieve the who composed the work, if different from artist.
static java.lang.String	METADATA_KEY_COPYRIGHT The metadata key to retrieve the name of copyright holder.
static java.lang.String	METADATA_KEY_CREATION_TIME The metadata key to retrieve the date when the file was created, preferably in ISO 8601.
static java.lang.String	METADATA_KEY_DATE The metadata key to retrieve the date when the work was created, preferably in ISO 8601.
static java.lang.String	METADATA_KEY_DISC The metadata key to retrieve the number of a subset, e.g.
static java.lang.String	METADATA_KEY_DURATION The metadata key to retrieve the duration of the work in milliseconds.
static java.lang.String	METADATA_KEY_ENCODED_BY The metadata key to retrieve the person/group who created the file.
static java.lang.String	METADATA_KEY_ENCODER The metadata key to retrieve the name/settings of the software/hardware that produced the file.
static java.lang.String	METADATA_KEY_FILENAME The metadata key to retrieve the original name of the file.
static java.lang.String	METADATA_KEY_FILESIZE The metadata key to retrieve the file size in bytes.
static java.lang.String	METADATA_KEY_FRAMERATE This metadata key retrieves the average framerate (in frames/sec), if available.
static java.lang.String	METADATA_KEY_GENRE The metadata key to retrieve the genre of the work.
static java.lang.String	METADATA_KEY_ICY_METADATA The metadata key to retrieve the main creator of the work.
static java.lang.String	METADATA_KEY_LANGUAGE The metadata key to retrieve the main language in which the work is performed, preferably in ISO 639-2 format.
static java.lang.String	METADATA_KEY_PERFORMER The metadata key to retrieve the artist who performed the work, if different from artist.
static java.lang.String	METADATA_KEY_PUBLISHER The metadata key to retrieve the name of the label/publisher.
static java.lang.String	METADATA_KEY_SERVICE_NAME The metadata key to retrieve the name of the service in broadcasting (channel name).
static java.lang.String	METADATA_KEY_SERVICE_PROVIDER The metadata key to retrieve the name of the service provider in broadcasting.
static java.lang.String	METADATA_KEY_TITLE The metadata key to retrieve the name of the work.
static java.lang.String	METADATA_KEY_TRACK The metadata key to retrieve the number of this work in the set, can be in form current/total.
static java.lang.String	METADATA_KEY_VARIANT_BITRATE The metadata key to retrieve the total bitrate of the bitrate variant that the current stream is part of.
static java.lang.String	METADATA_KEY_VIDEO_CODEC The metadata key to retrieve the video codec of the work.
static java.lang.String	METADATA_KEY_VIDEO_ROTATION This key retrieves the video rotation angle in degrees, if available.
static 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.
static 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.
static 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.
static 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.

Constructor Summary

Constructors

Constructor and Description
FFmpegMediaMetadataRetriever()

Method Summary

Methods

Modifier and Type	Method and Description
java.lang.String	extractMetadata(java.lang.String key) Call this method after setDataSource().
java.lang.String	extractMetadataFromChapter(java.lang.String key, int chapter) Call this method after setDataSource().
protected void	finalize()
byte[]	getEmbeddedPicture() Call this method after setDataSource().
Bitmap	getFrameAtTime() 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().
Metadata	getMetadata() Gets the media metadata.
Bitmap	getScaledFrameAtTime(long timeUs, int width, int height) Call this method after setDataSource().
Bitmap	getScaledFrameAtTime(long timeUs, int option, int width, int height) Call this method after setDataSource().
void	release() Call it when one is done with the object.
void	setDataSource(Context context, Uri uri) Sets the data source as a content Uri.
void	setDataSource(java.io.FileDescriptor fd) Sets the data source (FileDescriptor) to use.
void	setDataSource(java.io.FileDescriptor fd, long offset, long length) Sets the data source (FileDescriptor) to use.
void	setDataSource(java.lang.String path) Sets the data source (file pathname) to use.
void	setDataSource(java.lang.String uri, java.util.Map<java.lang.String,java.lang.String> headers) Sets the data source (URI) to use.
void	setSurface(java.lang.Object surface) Sets the Surface to be used as the sink for the video portion of the media.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

IN_PREFERRED_CONFIG

public static Bitmap.Config IN_PREFERRED_CONFIG

User defined bitmap configuration. A bitmap configuration describes how pixels are stored. This affects the quality (color depth) as well as the ability to display transparent/translucent colors.

OPTION_PREVIOUS_SYNC

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 Field Values

OPTION_NEXT_SYNC

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 Field Values

OPTION_CLOSEST_SYNC

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 Field Values

OPTION_CLOSEST

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 Field Values

METADATA_KEY_ALBUM

public static final java.lang.String METADATA_KEY_ALBUM

The metadata key to retrieve the name of the set this work belongs to.

See Also:

Constant Field Values

METADATA_KEY_ALBUM_ARTIST

public static final java.lang.String METADATA_KEY_ALBUM_ARTIST

The metadata key to retrieve the main creator of the set/album, if different from artist. e.g. "Various Artists" for compilation albums.

See Also:

Constant Field Values

METADATA_KEY_ARTIST

public static final java.lang.String METADATA_KEY_ARTIST

The metadata key to retrieve the main creator of the work.

See Also:

Constant Field Values

METADATA_KEY_COMMENT

public static final java.lang.String METADATA_KEY_COMMENT

The metadata key to retrieve the any additional description of the file.

See Also:

Constant Field Values

METADATA_KEY_COMPOSER

public static final java.lang.String METADATA_KEY_COMPOSER

The metadata key to retrieve the who composed the work, if different from artist.

See Also:

Constant Field Values

METADATA_KEY_COPYRIGHT

public static final java.lang.String METADATA_KEY_COPYRIGHT

The metadata key to retrieve the name of copyright holder.

See Also:

Constant Field Values

METADATA_KEY_CREATION_TIME

public static final java.lang.String METADATA_KEY_CREATION_TIME

The metadata key to retrieve the date when the file was created, preferably in ISO 8601.

See Also:

Constant Field Values

METADATA_KEY_DATE

public static final java.lang.String METADATA_KEY_DATE

The metadata key to retrieve the date when the work was created, preferably in ISO 8601.

See Also:

Constant Field Values

METADATA_KEY_DISC

public static final java.lang.String METADATA_KEY_DISC

The metadata key to retrieve the number of a subset, e.g. disc in a multi-disc collection.

See Also:

Constant Field Values

METADATA_KEY_ENCODER

public static final java.lang.String METADATA_KEY_ENCODER

The metadata key to retrieve the name/settings of the software/hardware that produced the file.

See Also:

Constant Field Values

METADATA_KEY_ENCODED_BY

public static final java.lang.String METADATA_KEY_ENCODED_BY

The metadata key to retrieve the person/group who created the file.

See Also:

Constant Field Values

METADATA_KEY_FILENAME

public static final java.lang.String METADATA_KEY_FILENAME

The metadata key to retrieve the original name of the file.

See Also:

Constant Field Values

METADATA_KEY_GENRE

public static final java.lang.String METADATA_KEY_GENRE

The metadata key to retrieve the genre of the work.

See Also:

Constant Field Values

METADATA_KEY_LANGUAGE

public static final java.lang.String METADATA_KEY_LANGUAGE

The metadata key to retrieve the main language in which the work is performed, preferably in ISO 639-2 format. Multiple languages can be specified by separating them with commas.

See Also:

Constant Field Values

METADATA_KEY_PERFORMER

public static final java.lang.String METADATA_KEY_PERFORMER

The metadata key to retrieve the artist who performed the work, if different from artist. E.g for "Also sprach Zarathustra", artist would be "Richard Strauss" and performer "London Philharmonic Orchestra".

See Also:

Constant Field Values

METADATA_KEY_PUBLISHER

public static final java.lang.String METADATA_KEY_PUBLISHER

The metadata key to retrieve the name of the label/publisher.

See Also:

Constant Field Values

METADATA_KEY_SERVICE_NAME

public static final java.lang.String METADATA_KEY_SERVICE_NAME

The metadata key to retrieve the name of the service in broadcasting (channel name).

See Also:

Constant Field Values

METADATA_KEY_SERVICE_PROVIDER

public static final java.lang.String METADATA_KEY_SERVICE_PROVIDER

The metadata key to retrieve the name of the service provider in broadcasting.

See Also:

Constant Field Values

METADATA_KEY_TITLE

public static final java.lang.String METADATA_KEY_TITLE

The metadata key to retrieve the name of the work.

See Also:

Constant Field Values

METADATA_KEY_TRACK

public static final java.lang.String METADATA_KEY_TRACK

The metadata key to retrieve the number of this work in the set, can be in form current/total.

See Also:

Constant Field Values

METADATA_KEY_VARIANT_BITRATE

public static final java.lang.String METADATA_KEY_VARIANT_BITRATE

The metadata key to retrieve the total bitrate of the bitrate variant that the current stream is part of.

See Also:

Constant Field Values

METADATA_KEY_DURATION

public static final java.lang.String METADATA_KEY_DURATION

The metadata key to retrieve the duration of the work in milliseconds.

See Also:

Constant Field Values

METADATA_KEY_AUDIO_CODEC

public static final java.lang.String METADATA_KEY_AUDIO_CODEC

The metadata key to retrieve the audio codec of the work.

See Also:

Constant Field Values

METADATA_KEY_VIDEO_CODEC

public static final java.lang.String METADATA_KEY_VIDEO_CODEC

The metadata key to retrieve the video codec of the work.

See Also:

Constant Field Values

METADATA_KEY_VIDEO_ROTATION

public static final java.lang.String 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.

See Also:

Constant Field Values

METADATA_KEY_ICY_METADATA

public static final java.lang.String METADATA_KEY_ICY_METADATA

The metadata key to retrieve the main creator of the work.

See Also:

Constant Field Values

METADATA_KEY_FRAMERATE

public static final java.lang.String METADATA_KEY_FRAMERATE

This metadata key retrieves the average framerate (in frames/sec), if available.

See Also:

Constant Field Values

METADATA_KEY_CHAPTER_START_TIME

public static final java.lang.String METADATA_KEY_CHAPTER_START_TIME

The metadata key to retrieve the chapter start time in milliseconds.

See Also:

Constant Field Values

METADATA_KEY_CHAPTER_END_TIME

public static final java.lang.String METADATA_KEY_CHAPTER_END_TIME

The metadata key to retrieve the chapter end time in milliseconds.

See Also:

Constant Field Values

METADATA_CHAPTER_COUNT

public static final java.lang.String METADATA_CHAPTER_COUNT

The metadata key to retrieve the chapter count.

See Also:

Constant Field Values

METADATA_KEY_FILESIZE

public static final java.lang.String METADATA_KEY_FILESIZE

The metadata key to retrieve the file size in bytes.

See Also:

Constant Field Values

Constructor Detail

FFmpegMediaMetadataRetriever

public FFmpegMediaMetadataRetriever()

Method Detail

setDataSource

public void setDataSource(java.lang.String path)
                   throws java.lang.IllegalArgumentException

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:

java.lang.IllegalArgumentException - If the path is invalid.

setDataSource

public void setDataSource(java.lang.String uri,
                 java.util.Map<java.lang.String,java.lang.String> headers)
                   throws java.lang.IllegalArgumentException

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 - The URI of the input media.

headers - the headers to be sent together with the request for the data

Throws:

java.lang.IllegalArgumentException - If the URI is invalid.

setDataSource

public void setDataSource(java.io.FileDescriptor fd,
                 long offset,
                 long length)
                   throws java.lang.IllegalArgumentException

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:

java.lang.IllegalArgumentException - if the arguments are invalid

setDataSource

public void setDataSource(java.io.FileDescriptor fd)
                   throws java.lang.IllegalArgumentException

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:

java.lang.IllegalArgumentException - if the FileDescriptor is invalid

setDataSource

public void setDataSource(Context context,
                 Uri uri)
                   throws java.lang.IllegalArgumentException,
                          java.lang.SecurityException

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:

java.lang.IllegalArgumentException - if the Uri is invalid

java.lang.SecurityException - if the Uri cannot be used due to lack of permission.

extractMetadata

public java.lang.String extractMetadata(java.lang.String key)

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.

extractMetadataFromChapter

public java.lang.String extractMetadataFromChapter(java.lang.String key,
                                          int chapter)

Call this method after setDataSource(). This method retrieves the meta data value associated with the keyCode from a specific chapter, if available. 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.

chapter - The chapter from where the metadata will be retrieved.

Returns:

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

getMetadata

public Metadata getMetadata()

Gets the media metadata. //* @param update_only controls whether the full set of available //* metadata is returned or just the set that changed since the //* last call. See #METADATA_UPDATE_ONLY and #METADATA_ALL. //* //* @param apply_filter if true only metadata that matches the //* filter is returned. See #APPLY_METADATA_FILTER and #BYPASS_METADATA_FILTER. //*

Returns:

The metadata, possibly empty. null if an error occured.

getFrameAtTime

public 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 - 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.

getFrameAtTime

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

See Also:

getFrameAtTime(long, int)

getFrameAtTime

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

See Also:

getFrameAtTime(long), getFrameAtTime(long, int)

getScaledFrameAtTime

public Bitmap getScaledFrameAtTime(long timeUs,
                          int option,
                          int width,
                          int height)

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.

getScaledFrameAtTime

public Bitmap getScaledFrameAtTime(long timeUs,
                          int width,
                          int height)

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 #getScaledFrameAtTime(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.

See Also:

#getScaledFrameAtTime(long, int)

getEmbeddedPicture

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:

null if no such graphic is found.

release

public void release()

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

finalize

protected void finalize()
                 throws java.lang.Throwable

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

setSurface

public void setSurface(java.lang.Object surface)

Sets the Surface to be used as the sink for the video portion of the media. This is similar to #setDisplay(SurfaceHolder), but does not support #setScreenOnWhilePlaying(boolean). Setting a Surface will un-set any Surface or SurfaceHolder that was previously set. A null surface will result in only the audio track being played. If the Surface sends frames to a SurfaceTexture, the timestamps returned from SurfaceTexture#getTimestamp() will have an unspecified zero point. These timestamps cannot be directly compared between different media sources, different instances of the same media source, or multiple runs of the same program. The timestamp is normally monotonically increasing and is unaffected by time-of-day adjustments, but it is reset when the position is set.

Parameters:

surface - The Surface to be used for the video portion of the media.