Android APIs
public final class

MediaExtractor

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

Class Overview

MediaExtractor facilitates extraction of demuxed, typically encoded, media data from a data source.

It is generally used like this:

 MediaExtractor extractor = new MediaExtractor();
 extractor.setDataSource(...);
 int numTracks = extractor.getTrackCount();
 for (int i = 0; i < numTracks; ++i) {
   MediaFormat format = extractor.getTrackFormat(i);
   String mime = format.getString(MediaFormat.KEY_MIME);
   if (weAreInterestedInThisTrack) {
     extractor.selectTrack(i);
   }
 }
 ByteBuffer inputBuffer = ByteBuffer.allocate(...)
 while (extractor.readSampleData(inputBuffer, ...) >= 0) {
   int trackIndex = extractor.getSampleTrackIndex();
   long presentationTimeUs = extractor.getSampleTime();
   ...
   extractor.advance();
 }

 extractor.release();
 extractor = null;
 

Summary

Constants
int SAMPLE_FLAG_ENCRYPTED The sample is (at least partially) encrypted, see also the documentation for queueSecureInputBuffer(int, int, MediaCodec.CryptoInfo, long, int)
int SAMPLE_FLAG_SYNC The sample is a sync sample (or in MediaCodec's terminology it is a key frame.)
int SEEK_TO_CLOSEST_SYNC If possible, seek to the sync sample closest to the specified time
int SEEK_TO_NEXT_SYNC If possible, seek to a sync sample at or after the specified time
int SEEK_TO_PREVIOUS_SYNC If possible, seek to a sync sample at or before the specified time
Public Constructors
MediaExtractor()
Public Methods
boolean advance()
Advance to the next sample.
long getCachedDuration()
Returns an estimate of how much data is presently cached in memory expressed in microseconds.
Map<UUID, byte[]> getPsshInfo()
Get the PSSH info if present.
boolean getSampleCryptoInfo(MediaCodec.CryptoInfo info)
If the sample flags indicate that the current sample is at least partially encrypted, this call returns relevant information about the structure of the sample data required for decryption.
int getSampleFlags()
Returns the current sample's flags.
long getSampleTime()
Returns the current sample's presentation time in microseconds.
int getSampleTrackIndex()
Returns the track index the current sample originates from (or -1 if no more samples are available)
final int getTrackCount()
Count the number of tracks found in the data source.
MediaFormat getTrackFormat(int index)
Get the track format at the specified index.
boolean hasCacheReachedEndOfStream()
Returns true iff we are caching data and the cache has reached the end of the data stream (for now, a future seek may of course restart the fetching of data).
int readSampleData(ByteBuffer byteBuf, int offset)
Retrieve the current encoded sample and store it in the byte buffer starting at the given offset.
final void release()
Make sure you call this when you're done to free up any resources instead of relying on the garbage collector to do this for you at some point in the future.
void seekTo(long timeUs, int mode)
All selected tracks seek near the requested time according to the specified mode.
void selectTrack(int index)
Subsequent calls to readSampleData(ByteBuffer, int), getSampleTrackIndex() and getSampleTime() only retrieve information for the subset of tracks selected.
final void setDataSource(String path)
Sets the data source (file-path or http URL) to use.
final void setDataSource(String path, Map<StringString> headers)
Sets the data source (file-path or http URL) to use.
final void setDataSource(FileDescriptor fd)
Sets the data source (FileDescriptor) to use.
final void setDataSource(FileDescriptor fd, long offset, long length)
Sets the data source (FileDescriptor) to use.
final void setDataSource(Context context, Uri uri, Map<StringString> headers)
Sets the data source as a content Uri.
final void setDataSource(MediaDataSource dataSource)
Sets the data source (MediaDataSource) to use.
void unselectTrack(int index)
Subsequent calls to readSampleData(ByteBuffer, int), getSampleTrackIndex() and getSampleTime() only retrieve information for the subset of tracks selected.
Protected Methods
void finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int SAMPLE_FLAG_ENCRYPTED

Added in API level 16

The sample is (at least partially) encrypted, see also the documentation for queueSecureInputBuffer(int, int, MediaCodec.CryptoInfo, long, int)

Constant Value: 2 (0x00000002)

public static final int SAMPLE_FLAG_SYNC

Added in API level 16

The sample is a sync sample (or in MediaCodec's terminology it is a key frame.)

Constant Value: 1 (0x00000001)

public static final int SEEK_TO_CLOSEST_SYNC

Added in API level 16

If possible, seek to the sync sample closest to the specified time

Constant Value: 2 (0x00000002)

public static final int SEEK_TO_NEXT_SYNC

Added in API level 16

If possible, seek to a sync sample at or after the specified time

Constant Value: 1 (0x00000001)

public static final int SEEK_TO_PREVIOUS_SYNC

Added in API level 16

If possible, seek to a sync sample at or before the specified time

Constant Value: 0 (0x00000000)

Public Constructors

public MediaExtractor ()

Added in API level 16

Public Methods

public boolean advance ()

Added in API level 16

Advance to the next sample. Returns false if no more sample data is available (end of stream).

Returns
boolean

public long getCachedDuration ()

Added in API level 16

Returns an estimate of how much data is presently cached in memory expressed in microseconds. Returns -1 if that information is unavailable or not applicable (no cache).

Returns
long

public Map<UUID, byte[]> getPsshInfo ()

Added in API level 18

Get the PSSH info if present.

Returns
Map<UUID, byte[]> a map of uuid-to-bytes, with the uuid specifying the crypto scheme, and the bytes being the data specific to that scheme. This can be null if the source does not contain PSSH info.

public boolean getSampleCryptoInfo (MediaCodec.CryptoInfo info)

Added in API level 16

If the sample flags indicate that the current sample is at least partially encrypted, this call returns relevant information about the structure of the sample data required for decryption.

Parameters
info MediaCodec.CryptoInfo: The android.media.MediaCodec.CryptoInfo structure to be filled in.
Returns
boolean true iff the sample flags contain SAMPLE_FLAG_ENCRYPTED

public int getSampleFlags ()

Added in API level 16

Returns the current sample's flags.

Returns
int

public long getSampleTime ()

Added in API level 16

Returns the current sample's presentation time in microseconds. or -1 if no more samples are available.

Returns
long

public int getSampleTrackIndex ()

Added in API level 16

Returns the track index the current sample originates from (or -1 if no more samples are available)

Returns
int

public final int getTrackCount ()

Added in API level 16

Count the number of tracks found in the data source.

Returns
int

public MediaFormat getTrackFormat (int index)

Added in API level 16

Get the track format at the specified index. More detail on the representation can be found at MediaCodec

Parameters
index int
Returns
MediaFormat

public boolean hasCacheReachedEndOfStream ()

Added in API level 16

Returns true iff we are caching data and the cache has reached the end of the data stream (for now, a future seek may of course restart the fetching of data). This API only returns a meaningful result if getCachedDuration() indicates the presence of a cache, i.e. does NOT return -1.

Returns
boolean

public int readSampleData (ByteBuffer byteBuf, int offset)

Added in API level 16

Retrieve the current encoded sample and store it in the byte buffer starting at the given offset.

Note:As of API 21, on success the position and limit of byteBuf is updated to point to the data just read.

Parameters
byteBuf ByteBuffer: the destination byte buffer
offset int
Returns
int the sample size (or -1 if no more samples are available).

public final void release ()

Added in API level 16

Make sure you call this when you're done to free up any resources instead of relying on the garbage collector to do this for you at some point in the future.

public void seekTo (long timeUs, int mode)

Added in API level 16

All selected tracks seek near the requested time according to the specified mode.

Parameters
timeUs long
mode int

public void selectTrack (int index)

Added in API level 16

Subsequent calls to readSampleData(ByteBuffer, int), getSampleTrackIndex() and getSampleTime() only retrieve information for the subset of tracks selected. Selecting the same track multiple times has no effect, the track is only selected once.

Parameters
index int

public final void setDataSource (String path)

Added in API level 16

Sets the data source (file-path or http URL) to use.

Parameters
path String: the path of the file, or the http URL of the stream

When path refers to a local file, the file may actually be opened by a process other than the calling application. This implies that the pathname should be an absolute path (as any other process runs with unspecified current working directory), and that the pathname should reference a world-readable file. As an alternative, the application could first open the file for reading, and then use the file descriptor form setDataSource(FileDescriptor).

Throws
IOException

public final void setDataSource (String path, Map<StringString> headers)

Added in API level 16

Sets the data source (file-path or http URL) to use.

Parameters
path String: the path of the file, or the http URL
headers Map: the headers associated with the http request for the stream you want to play. This can be null if no specific headers are to be sent with the request.
Throws
IOException

public final void setDataSource (FileDescriptor fd)

Added in API level 16

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.

Parameters
fd FileDescriptor: the FileDescriptor for the file you want to extract from.
Throws
IOException

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

Added in API level 16

Sets the data source (FileDescriptor) to use. The FileDescriptor must be seekable (N.B. a LocalSocket is not seekable). It is the caller's responsibility to close the file descriptor. It is safe to do so as soon as this call returns.

Parameters
fd FileDescriptor: the FileDescriptor for the file you want to extract from.
offset long: the offset into the file where the data to be extracted starts, in bytes
length long: the length in bytes of the data to be extracted
Throws
IOException

public final void setDataSource (Context context, Uri uri, Map<StringString> headers)

Added in API level 16

Sets the data source as a content Uri.

Parameters
context Context: the Context to use when resolving the Uri
uri Uri: the Content URI of the data you want to extract from.
headers Map: the headers to be sent together with the request for the data. This can be null if no specific headers are to be sent with the request.
Throws
IOException

public final void setDataSource (MediaDataSource dataSource)

Added in API level 23

Sets the data source (MediaDataSource) to use.

Parameters
dataSource MediaDataSource: the MediaDataSource for the media you want to extract from
Throws
IllegalArgumentException if dataSource is invalid.
IOException

public void unselectTrack (int index)

Added in API level 16

Subsequent calls to readSampleData(ByteBuffer, int), getSampleTrackIndex() and getSampleTime() only retrieve information for the subset of tracks selected.

Parameters
index int

Protected Methods

protected void finalize ()

Added in API level 16

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.