MediaExtractorCompat

Artifact: androidx.media3:media3-inspector

Kotlin |Java

@UnstableApi
public final class MediaExtractorCompat

A drop-in replacement for MediaExtractor that provides similar functionality, based on the media3.extractor logic.

Summary

Nested types
`@IntDef(value = ) @Retention(value = RetentionPolicy.SOURCE) public annotation MediaExtractorCompat.SeekMode` The seeking mode.

Constants
`static final int`	`SEEK_TO_CLOSEST_SYNC = 2` See `SEEK_TO_CLOSEST_SYNC`.
`static final int`	`SEEK_TO_NEXT_SYNC = 1` See `SEEK_TO_NEXT_SYNC`.
`static final int`	`SEEK_TO_PREVIOUS_SYNC = 0` See `SEEK_TO_PREVIOUS_SYNC`.

Public constructors
`MediaExtractorCompat(Context context)` Creates a new instance.
`MediaExtractorCompat( ExtractorsFactory extractorsFactory, DataSource.Factory dataSourceFactory )` Creates a new instance using the given `ExtractorsFactory` to create the `extractors` to use for obtaining media samples from a `DataSource` generated by the given `DataSource.Factory`.

Public methods
`boolean`	`advance()` Advances to the next sample.
`Allocator`	`@VisibleForTesting(otherwise = 5) getAllocator()`
`long`	`getCachedDuration()` Returns an estimate of how much data is presently cached in memory, expressed in microseconds, or -1 if this information is unavailable or not applicable (i.e., no cache exists).
`@Nullable DrmInitData`	`getDrmInitData()` Extracts the DRM initialization data from the available tracks, if it exists.
`LogSessionId`	`@RequiresApi(value = 31) getLogSessionId()` Returns the `LogSessionId` for MediaExtractorCompat.
`PersistableBundle`	`@RequiresApi(value = 26) getMetrics()` Returns a `PersistableBundle` containing metrics data for the current media container.
`@Nullable Map<UUID, byte[]>`	`getPsshInfo()` Extracts PSSH data from the media, if present.
`boolean`	`getSampleCryptoInfo(MediaCodec.CryptoInfo info)` Returns `true` if the current sample is at least partially encrypted and fills the provided `MediaCodec.CryptoInfo` structure with relevant decryption information.
`int`	`getSampleFlags()` Returns the current sample's flags.
`long`	`getSampleSize()` Returns the current sample's size in bytes, or -1 if no more samples are available.
`long`	`getSampleTime()` Returns the current sample's presentation time in microseconds, or -1 if no more samples are available.
`int`	`getSampleTrackIndex()` Returns the track index the current sample originates from, or -1 if no more samples are available.
`int`	`getTrackCount()` Returns the number of tracks found in the data source.
`MediaFormat`	`getTrackFormat(int trackIndex)` Returns the track `MediaFormat` at the specified `trackIndex`.
`boolean`	`hasCacheReachedEndOfStream()` Returns `true` if data is being cached and the cache has reached the end of the data stream.
`int`	`readSampleData(ByteBuffer buffer, int offset)` Retrieves the current encoded sample and stores it in the byte `buffer` starting at the given `offset`.
`void`	`release()` Releases any resources held by this instance.
`void`	`seekTo(long timeUs, @MediaExtractorCompat.SeekMode int mode)` All selected tracks seek near the requested `timeUs` according to the specified `mode`.
`void`	`selectTrack(int trackIndex)` Selects a track at the specified `trackIndex`.
`void`	`setDataSource(AssetFileDescriptor assetFileDescriptor)` Sets the data source using the media stream obtained from the provided `AssetFileDescriptor`.
`void`	`setDataSource(FileDescriptor fileDescriptor)` Sets the data source using the media stream obtained from the provided `FileDescriptor`.
`void`	`setDataSource(MediaDataSource mediaDataSource)` Sets the data source using the media stream obtained from the given `MediaDataSource`.
`void`	`setDataSource(String path)` Sets the data source using the media stream obtained from the given file path or HTTP URL.
`void`	`setDataSource(String path, @Nullable Map<String, String> headers)` Sets the data source using the media stream obtained from the given file path or HTTP URL, with optional HTTP request headers.
`void`	`setDataSource(Uri uri, long offset)` Sets the data source using the media stream obtained from the given `Uri` at the given `offset`.
`void`	`setDataSource( Context context, Uri uri, @Nullable Map<String, String> headers )` Sets the data source using the media stream obtained from the given `content URI` and optional HTTP request headers.
`void`	`setDataSource(FileDescriptor fileDescriptor, long offset, long length)` Sets the data source using the media stream obtained from the provided `FileDescriptor`, with a specified `offset` and `length`.
`void`	`@RequiresApi(value = 31) setLogSessionId(LogSessionId logSessionId)` Sets the `LogSessionId` for MediaExtractorCompat.
`void`	`unselectTrack(int trackIndex)` Unselects the track at the specified `trackIndex`.

Constants

SEEK_TO_CLOSEST_SYNC

public static final int SEEK_TO_CLOSEST_SYNC = 2

See SEEK_TO_CLOSEST_SYNC.

SEEK_TO_NEXT_SYNC

public static final int SEEK_TO_NEXT_SYNC = 1

See SEEK_TO_NEXT_SYNC.

SEEK_TO_PREVIOUS_SYNC

public static final int SEEK_TO_PREVIOUS_SYNC = 0

See SEEK_TO_PREVIOUS_SYNC.

Public constructors

MediaExtractorCompat

public MediaExtractorCompat(Context context)

Creates a new instance.

MediaExtractorCompat

public MediaExtractorCompat(
    ExtractorsFactory extractorsFactory,
    DataSource.Factory dataSourceFactory
)

Creates a new instance using the given ExtractorsFactory to create the extractors to use for obtaining media samples from a DataSource generated by the given DataSource.Factory.

Note: The DataSource.Factory provided will not be used to generate DataSource when setting data source using methods:

setDataSource
setDataSource
setDataSource

Note: The DataSource.Factory provided may not be used to generate DataSource when setting data source using method setDataSource as the behavior depends on the fallthrough logic related to the scheme of the provided URI.

Public methods

advance

public boolean advance()

Advances to the next sample. Returns false if no more sample data is available (i.e., end of stream), or true otherwise.

Note: When extracting from a local file, the behavior of advance and readSampleData is undefined if there are concurrent writes to the same file. This may result in an unexpected end of stream being signaled.

getAllocator

@VisibleForTesting(otherwise = 5)
public Allocator getAllocator()

getCachedDuration

public long getCachedDuration()

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

getDrmInitData

public @Nullable DrmInitData getDrmInitData()

Extracts the DRM initialization data from the available tracks, if it exists.

Returns
`@Nullable DrmInitData`	The `DrmInitData` in the content, or `null` if no recognizable DRM format is found.

getLogSessionId

@RequiresApi(value = 31)
public LogSessionId getLogSessionId()

Returns the LogSessionId for MediaExtractorCompat.

getMetrics

@RequiresApi(value = 26)
public PersistableBundle getMetrics()

Returns a PersistableBundle containing metrics data for the current media container.

The bundle includes attributes and values for the media container, as described in MediaExtractor.MetricsConstants.

getPsshInfo

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

Extracts PSSH data from the media, if present.

Returns
`@Nullable Map<UUID, byte[]>`	A `Map` of UUID-to-byte[] pairs, where the `UUID` identifies the crypto scheme, and the byte array contains the scheme-specific data. Returns `null` if no PSSH data exists.

getSampleCryptoInfo

public boolean getSampleCryptoInfo(MediaCodec.CryptoInfo info)

Returns true if the current sample is at least partially encrypted and fills the provided MediaCodec.CryptoInfo structure with relevant decryption information.

Parameters
`MediaCodec.CryptoInfo info`	The `MediaCodec.CryptoInfo` structure to be filled with decryption data.

Returns
`boolean`	`true` if the sample is at least partially encrypted, `false` otherwise.

getSampleFlags

public int getSampleFlags()

Returns the current sample's flags.

getSampleSize

public long getSampleSize()

Returns the current sample's size in bytes, or -1 if no more samples are available.

getSampleTime

public long getSampleTime()

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

getSampleTrackIndex

public int getSampleTrackIndex()

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

getTrackCount

public int getTrackCount()

Returns the number of tracks found in the data source.

getTrackFormat

public MediaFormat getTrackFormat(int trackIndex)

Returns the track MediaFormat at the specified trackIndex.

hasCacheReachedEndOfStream

public boolean hasCacheReachedEndOfStream()

Returns true if data is being cached and the cache has reached the end of the data stream. This indicates that no additional data is currently available for caching, although a future seek may restart data fetching. This method only returns a meaningful result if getCachedDuration indicates the presence of a cache (i.e., does not return -1).

readSampleData

public int readSampleData(ByteBuffer buffer, int offset)

Retrieves the current encoded sample and stores it in the byte buffer starting at the given offset.

Note:On success, the position and limit of buffer is updated to point to the data just read.

Parameters
`ByteBuffer buffer`	the destination byte buffer.
`int offset`	The offset into the byte buffer at which to write.

Returns
`int`	the sample size, or -1 if no more samples are available.

release

public void release()

Releases any resources held by this instance.

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

seekTo

public void seekTo(long timeUs, @MediaExtractorCompat.SeekMode int mode)

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

selectTrack

public void selectTrack(int trackIndex)

Selects a track at the specified trackIndex.

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

Note: Selecting the same track multiple times has no effect, the track is only selected once.

setDataSource

public void setDataSource(AssetFileDescriptor assetFileDescriptor)

Sets the data source using the media stream obtained from the provided AssetFileDescriptor.

Note: The caller is responsible for closing the AssetFileDescriptor. It is safe to do so immediately after this method returns.

Parameters
`AssetFileDescriptor assetFileDescriptor`	The `AssetFileDescriptor` for the file to extract from.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

public void setDataSource(FileDescriptor fileDescriptor)

Sets the data source using the media stream obtained from the provided FileDescriptor.

Parameters
`FileDescriptor fileDescriptor`	The `FileDescriptor` for the file to extract from.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

public void setDataSource(MediaDataSource mediaDataSource)

Sets the data source using the media stream obtained from the given MediaDataSource.

Parameters
`MediaDataSource mediaDataSource`	The `MediaDataSource` to extract media from.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

public void setDataSource(String path)

Sets the data source using the media stream obtained from the given file path or HTTP URL.

Parameters
`String path`	The path of the file, or the HTTP URL, to extract media from.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

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

Sets the data source using the media stream obtained from the given file path or HTTP URL, with optional HTTP request headers.

Parameters
`String path`	The path of the file, or the HTTP URL, to extract media from.
`@Nullable Map<String, String> headers`	An optional `Map` of HTTP request headers to include when fetching the data, or `null` if no headers are to be included.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

public void setDataSource(Uri uri, long offset)

Sets the data source using the media stream obtained from the given Uri at the given offset.

Parameters
`Uri uri`	The content `Uri` to extract from.
`long offset`	The offset into the file where the data to be extracted starts, in bytes.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

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

Sets the data source using the media stream obtained from the given content URI and optional HTTP request headers.

Parameters
`Context context`	The `Context` used to resolve the `Uri`.
`Uri uri`	The `content URI` of the media to extract from.
`@Nullable Map<String, String> headers`	An optional `Map` of HTTP request headers to include when fetching the data, or `null` if no headers are to be included.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setDataSource

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

Sets the data source using the media stream obtained from the provided FileDescriptor, with a specified offset and length.

Parameters
`FileDescriptor fileDescriptor`	The `FileDescriptor` for the file to extract from.
`long offset`	The offset into the file where the data to be extracted starts, in bytes.
`long length`	The length of the data to be extracted, in bytes, or `LENGTH_UNSET` if it is unknown.

Throws
`java.io.IOException`	If an error occurs while extracting the media.
`androidx.media3.exoplayer.source.UnrecognizedInputFormatException`	If none of the available extractors successfully sniffs the input.
`java.lang.IllegalStateException`	If this method is called twice on the same instance.

setLogSessionId

@RequiresApi(value = 31)
public void setLogSessionId(LogSessionId logSessionId)

Sets the LogSessionId for MediaExtractorCompat.

unselectTrack

public void unselectTrack(int trackIndex)

Unselects the track at the specified trackIndex.

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

MediaExtractorCompat

Summary

Nested types

Constants

Public constructors

Public methods

Constants

SEEK_TO_CLOSEST_SYNC

SEEK_TO_NEXT_SYNC

SEEK_TO_PREVIOUS_SYNC

Public constructors

MediaExtractorCompat

MediaExtractorCompat

Public methods

advance

getAllocator

getCachedDuration

getDrmInitData

getLogSessionId

getMetrics

getPsshInfo

getSampleCryptoInfo

getSampleFlags

getSampleSize

getSampleTime

getSampleTrackIndex

getTrackCount

getTrackFormat

hasCacheReachedEndOfStream

readSampleData

release

seekTo

selectTrack

setDataSource

setDataSource

setDataSource

setDataSource

setDataSource

setDataSource

setDataSource

setDataSource

setLogSessionId

unselectTrack