to top
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.getTrackIndex();
   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
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.
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<String, String> 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<String, String> headers)
Sets the data source as a content Uri.
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

Since: 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

Since: API Level 16

The sample is a sync sample

Constant Value: 1 (0x00000001)

public static final int SEEK_TO_CLOSEST_SYNC

Since: 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

Since: 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

Since: API Level 16

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

Constant Value: 0 (0x00000000)

Public Constructors

public MediaExtractor ()

Since: API Level 16

Public Methods

public boolean advance ()

Since: API Level 16

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

public long getCachedDuration ()

Since: 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).

public boolean getSampleCryptoInfo (MediaCodec.CryptoInfo info)

Since: 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 The android.media.MediaCodec.CryptoInfo structure to be filled in.
Returns

public int getSampleFlags ()

Since: API Level 16

Returns the current sample's flags.

public long getSampleTime ()

Since: API Level 16

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

public int getSampleTrackIndex ()

Since: API Level 16

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

public final int getTrackCount ()

Since: API Level 16

Count the number of tracks found in the data source.

public MediaFormat getTrackFormat (int index)

Since: API Level 16

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

public boolean hasCacheReachedEndOfStream ()

Since: 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 {link #getCachedDuration} indicates the presence of a cache, i.e. does NOT return -1.

public int readSampleData (ByteBuffer byteBuf, int offset)

Since: API Level 16

Retrieve the current encoded sample and store it in the byte buffer starting at the given offset. Returns the sample size (or -1 if no more samples are available).

public final void release ()

Since: 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)

Since: API Level 16

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

public void selectTrack (int index)

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

public final void setDataSource (String path)

Since: API Level 16

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

Parameters
path 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).

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

Since: API Level 16

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

Parameters
path the path of the file, or the http URL
headers the headers associated with the http request for the stream you want to play

public final void setDataSource (FileDescriptor fd)

Since: 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 the FileDescriptor for the file you want to extract from.

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

Since: 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 the FileDescriptor for the file you want to extract from.
offset the offset into the file where the data to be extracted starts, in bytes
length the length in bytes of the data to be extracted

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

Since: API Level 16

Sets the data source as a content Uri.

Parameters
context the Context to use when resolving the Uri
uri the Content URI of the data you want to extract from.
headers the headers to be sent together with the request for the data
Throws
IOException

public void unselectTrack (int index)

Since: API Level 16

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

Protected Methods

protected void finalize ()

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