@UnstableApi
public final class MediaCodecUtil

A utility class for querying the available codecs.

Summary

Nested types

Thrown when an error occurs querying the device for its underlying media capabilities.

Public methods
synchronized static void
static @Nullable String

Returns an alternative codec MIME type (besides the default sampleMimeType) that can be used to decode samples of the provided Format.
static List<MediaCodecInfo>
getAlternativeDecoderInfos(
    MediaCodecSelector mediaCodecSelector,
    Format format,
    boolean requiresSecureDecoder,
    boolean requiresTunnelingDecoder
)

Returns a list of decoders for alternative MIME types that can decode samples of the provided Format, in the priority order specified by the MediaCodecSelector.
static @Nullable Pair<Integer, Integer>
@InlineMe(replacement = "CodecSpecificDataUtil.getCodecProfileAndLevel(format)", imports = [""androidx.media3.common.util.CodecSpecificDataUtil""])
getCodecProfileAndLevel(Format format)

This method is deprecated.

Use getCodecProfileAndLevel.
static @Nullable MediaCodecInfo
getDecoderInfo(String mimeType, boolean secure, boolean tunneling)

Returns information about the preferred decoder for a given MIME type.
synchronized static List<MediaCodecInfo>
getDecoderInfos(String mimeType, boolean secure, boolean tunneling)

Returns all MediaCodecInfos for the given MIME type, in the order given by .
static List<MediaCodecInfo>
@RequiresNonNull(value = "#2.sampleMimeType")
getDecoderInfosSoftMatch(
    MediaCodecSelector mediaCodecSelector,
    Format format,
    boolean requiresSecureDecoder,
    boolean requiresTunnelingDecoder
)

Returns a list of decoders that can decode media in the specified format, in the priority order specified by the MediaCodecSelector.
static List<MediaCodecInfo>
getDecoderInfosSortedByFormatSupport(
    List<MediaCodecInfo> decoderInfos,
    Format format
)

Returns a copy of the provided decoder list sorted such that decoders with functional format support are listed first.
static @Nullable MediaCodecInfo

Returns information about a decoder that will only decrypt data, without decoding it.
static @Nullable Pair<Integer, Integer>

Returns profile and level (as defined by CodecProfileLevel) corresponding to the base layer (for the case of falling back to single-layer HEVC from L-HEVC).
static int

Returns the maximum frame size supported by the default H264 decoder.
static void
warmDecoderInfoCache(String mimeType, boolean secure, boolean tunneling)

Optional call to warm the codec cache for a given MIME type.

Public methods

clearDecoderInfoCache

@VisibleForTesting
synchronized public static void clearDecoderInfoCache()

getAlternativeCodecMimeType

public static @Nullable String getAlternativeCodecMimeType(Format format)

Returns an alternative codec MIME type (besides the default sampleMimeType) that can be used to decode samples of the provided Format.

Parameters
Format format

The media format.
Returns
@Nullable String

An alternative MIME type of a codec that be used decode samples of the provided Format (besides the default sampleMimeType), or null if no such alternative exists.

getAlternativeDecoderInfos

public static List<MediaCodecInfo> getAlternativeDecoderInfos(
    MediaCodecSelector mediaCodecSelector,
    Format format,
    boolean requiresSecureDecoder,
    boolean requiresTunnelingDecoder
)

Returns a list of decoders for alternative MIME types that can decode samples of the provided Format, in the priority order specified by the MediaCodecSelector.

Since the MediaCodecSelector only has access to sampleMimeType, the list is not ordered to account for whether each decoder supports the details of the format (e.g., taking into account the format's profile, level, resolution and so on). getDecoderInfosSortedByFormatSupport can be used to further sort the list into an order where decoders that fully support the format come first.

Parameters
MediaCodecSelector mediaCodecSelector

The decoder selector.
Format format

The Format for which an alternative decoder is required.
boolean requiresSecureDecoder

Whether a secure decoder is required.
boolean requiresTunnelingDecoder

Whether a tunneling decoder is required.
Returns
List<MediaCodecInfo>

A list of MediaCodecInfos corresponding to alternative decoders. May be empty.
Throws
androidx.media3.exoplayer.mediacodec.MediaCodecUtil.DecoderQueryException

Thrown if there was an error querying decoders.

getCodecProfileAndLevel

@InlineMe(replacement = "CodecSpecificDataUtil.getCodecProfileAndLevel(format)", imports = [""androidx.media3.common.util.CodecSpecificDataUtil""])
public static @Nullable Pair<Integer, Integer> getCodecProfileAndLevel(Format format)

getDecoderInfo

public static @Nullable MediaCodecInfo getDecoderInfo(String mimeType, boolean secure, boolean tunneling)

Returns information about the preferred decoder for a given MIME type.

Parameters
String mimeType

The MIME type.
boolean secure

Whether the decoder is required to support secure decryption. Always pass false unless secure decryption really is required.
boolean tunneling

Whether the decoder is required to support tunneling. Always pass false unless tunneling really is required.
Returns
@Nullable MediaCodecInfo

A MediaCodecInfo describing the decoder, or null if no suitable decoder exists.
Throws
androidx.media3.exoplayer.mediacodec.MediaCodecUtil.DecoderQueryException

If there was an error querying the available decoders.

getDecoderInfos

synchronized public static List<MediaCodecInfo> getDecoderInfos(String mimeType, boolean secure, boolean tunneling)

Returns all MediaCodecInfos for the given MIME type, in the order given by .

Parameters
String mimeType

The MIME type.
boolean secure

Whether the decoder is required to support secure decryption. Always pass false unless secure decryption really is required.
boolean tunneling

Whether the decoder is required to support tunneling. Always pass false unless tunneling really is required.
Returns
List<MediaCodecInfo>

An unmodifiable list of all MediaCodecInfos for the given MIME type, in the order given by MediaCodecList.
Throws
androidx.media3.exoplayer.mediacodec.MediaCodecUtil.DecoderQueryException

If there was an error querying the available decoders.

getDecoderInfosSoftMatch

@RequiresNonNull(value = "#2.sampleMimeType")
public static List<MediaCodecInfo> getDecoderInfosSoftMatch(
    MediaCodecSelector mediaCodecSelector,
    Format format,
    boolean requiresSecureDecoder,
    boolean requiresTunnelingDecoder
)

Returns a list of decoders that can decode media in the specified format, in the priority order specified by the MediaCodecSelector.

Since the MediaCodecSelector only has access to sampleMimeType, the list is not ordered to account for whether each decoder supports the details of the format (e.g., taking into account the format's profile, level, resolution and so on). getDecoderInfosSortedByFormatSupport can be used to further sort the list into an order where decoders that fully support the format come first.

This list is more complete than getDecoderInfos, as it also considers alternative MIME types that are a close match using getAlternativeCodecMimeType.

Parameters
MediaCodecSelector mediaCodecSelector

The decoder selector.
Format format

The Format for which a decoder is required.
boolean requiresSecureDecoder

Whether a secure decoder is required.
boolean requiresTunnelingDecoder

Whether a tunneling decoder is required.
Returns
List<MediaCodecInfo>

A list of MediaCodecInfos corresponding to decoders. May be empty.
Throws
androidx.media3.exoplayer.mediacodec.MediaCodecUtil.DecoderQueryException

Thrown if there was an error querying decoders.

getDecoderInfosSortedByFormatSupport

public static List<MediaCodecInfo> getDecoderInfosSortedByFormatSupport(
    List<MediaCodecInfo> decoderInfos,
    Format format
)

Returns a copy of the provided decoder list sorted such that decoders with functional format support are listed first. The returned list is modifiable for convenience.

getDecryptOnlyDecoderInfo

public static @Nullable MediaCodecInfo getDecryptOnlyDecoderInfo()

Returns information about a decoder that will only decrypt data, without decoding it.

Returns
@Nullable MediaCodecInfo

A MediaCodecInfo describing the decoder, or null if no suitable decoder exists.
Throws
androidx.media3.exoplayer.mediacodec.MediaCodecUtil.DecoderQueryException

If there was an error querying the available decoders.

getHevcBaseLayerCodecProfileAndLevel

public static @Nullable Pair<Integer, Integer> getHevcBaseLayerCodecProfileAndLevel(Format format)

Returns profile and level (as defined by CodecProfileLevel) corresponding to the base layer (for the case of falling back to single-layer HEVC from L-HEVC).

Parameters
Format format

Media format with codec specific initialization data.
Returns
@Nullable Pair<Integer, Integer>

A pair (profile constant, level constant) if the initializationData of the format is well-formed and recognized, or null otherwise.

maxH264DecodableFrameSize

public static int maxH264DecodableFrameSize()

Returns the maximum frame size supported by the default H264 decoder.

Returns
int

The maximum frame size for an H264 stream that can be decoded on the device.
Throws
androidx.media3.exoplayer.mediacodec.MediaCodecUtil.DecoderQueryException

warmDecoderInfoCache

public static void warmDecoderInfoCache(String mimeType, boolean secure, boolean tunneling)

Optional call to warm the codec cache for a given MIME type.

Calling this method may speed up subsequent calls to getDecoderInfo and getDecoderInfos.

Parameters
String mimeType

The MIME type.
boolean secure

Whether the decoder is required to support secure decryption. Always pass false unless secure decryption really is required.
boolean tunneling

Whether the decoder is required to support tunneling. Always pass false unless tunneling really is required.