From 43a2398258964e438c2dcdb4638fe9a24edfb208 Mon Sep 17 00:00:00 2001 From: Lajos Molnar Date: Thu, 23 Jun 2016 16:52:29 -0700 Subject: media: document format keys for MediaExtractor/CodecCapabilities Bug: 29618892 Change-Id: I78049997c153fe00fbcf4475eeefdc937de284dd --- media/java/android/media/MediaCodecInfo.java | 66 +++++++++++++++++ media/java/android/media/MediaCodecList.java | 6 ++ media/java/android/media/MediaExtractor.java | 106 +++++++++++++++++++++++++++ 3 files changed, 178 insertions(+) diff --git a/media/java/android/media/MediaCodecInfo.java b/media/java/android/media/MediaCodecInfo.java index 07d1f7542b26..0bfeaed36282 100644 --- a/media/java/android/media/MediaCodecInfo.java +++ b/media/java/android/media/MediaCodecInfo.java @@ -541,6 +541,72 @@ public final class MediaCodecInfo { * frame rate}. Use * format.setString(MediaFormat.KEY_FRAME_RATE, null) * to clear any existing frame rate setting in the format. + *

+ * + * The following table summarizes the format keys considered by this method. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
OS Version(s){@code MediaFormat} keys considered for + *
Audio CodecsVideo CodecsEncoders
{@link android.os.Build.VERSION_CODES#LOLLIPOP} + * {@link MediaFormat#KEY_MIME}*,
+ * {@link MediaFormat#KEY_SAMPLE_RATE},
+ * {@link MediaFormat#KEY_CHANNEL_COUNT},		{@link MediaFormat#KEY_MIME}*,
+ * {@link CodecCapabilities#FEATURE_AdaptivePlayback}D,
+ * {@link CodecCapabilities#FEATURE_SecurePlayback}D,
+ * {@link CodecCapabilities#FEATURE_TunneledPlayback}D,
+ * {@link MediaFormat#KEY_WIDTH},
+ * {@link MediaFormat#KEY_HEIGHT},
+ * no {@code KEY_FRAME_RATE}		{@link MediaFormat#KEY_BITRATE_MODE},
+ * {@link MediaFormat#KEY_PROFILE} + * (and/or {@link MediaFormat#KEY_AAC_PROFILE}~),
+ * + * {@link MediaFormat#KEY_COMPLEXITY} + * (and/or {@link MediaFormat#KEY_FLAC_COMPRESSION_LEVEL}~)
{@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1} + * as above, plus
+ * {@link MediaFormat#KEY_FRAME_RATE}
{@link android.os.Build.VERSION_CODES#M} + *
{@link android.os.Build.VERSION_CODES#N} + * as above, plus
+ * {@link MediaFormat#KEY_PROFILE},
+ * + * {@link MediaFormat#KEY_BIT_RATE}		as above, plus
+ * {@link MediaFormat#KEY_PROFILE},
+ * {@link MediaFormat#KEY_LEVEL}+,
+ * + * {@link MediaFormat#KEY_BIT_RATE},
+ * {@link CodecCapabilities#FEATURE_IntraRefresh}E
+ *

Notes:
+ * *: must be specified; otherwise, method returns {@code false}.
+ * +: method does not verify that the format parameters are supported + * by the specified level.
+ * D: decoders only
+ * E: encoders only
+ * ~: if both keys are provided values must match + *

* * @param format media format with optional feature directives. * @throws IllegalArgumentException if format is not a valid media format. diff --git a/media/java/android/media/MediaCodecList.java b/media/java/android/media/MediaCodecList.java index 42ce5110f134..3cb4cbe99a4b 100644 --- a/media/java/android/media/MediaCodecList.java +++ b/media/java/android/media/MediaCodecList.java @@ -201,6 +201,9 @@ final public class MediaCodecList { * format.setString(MediaFormat.KEY_FRAME_RATE, null) * to clear any existing frame rate setting in the format. * + * @see MediaCodecList.CodecCapabilities.isFormatSupported for format keys + * considered per android versions when evaluating suitable codecs. + * * @param format A decoder media format with optional feature directives. * @throws IllegalArgumentException if format is not a valid media format. * @throws NullPointerException if format is null. @@ -222,6 +225,9 @@ final public class MediaCodecList { * format.setString(MediaFormat.KEY_FRAME_RATE, null) * to clear any existing frame rate setting in the format. * + * @see MediaCodecList.CodecCapabilities.isFormatSupported for format keys + * considered per android versions when evaluating suitable codecs. + * * @param format An encoder media format with optional feature directives. * @throws IllegalArgumentException if format is not a valid media format. * @throws NullPointerException if format is null. diff --git a/media/java/android/media/MediaExtractor.java b/media/java/android/media/MediaExtractor.java index 24a400e48189..6f5199b6959c 100644 --- a/media/java/android/media/MediaExtractor.java +++ b/media/java/android/media/MediaExtractor.java @@ -333,7 +333,113 @@ final public class MediaExtractor { /** * Get the track format at the specified index. + * * More detail on the representation can be found at {@link android.media.MediaCodec} + *

+ * The following table summarizes support for format keys across android releases: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
OS Version(s){@code MediaFormat} keys used for + *
All TracksAudio TracksVideo Tracks
{@link android.os.Build.VERSION_CODES#JELLY_BEAN}{@link MediaFormat#KEY_MIME},
+ * {@link MediaFormat#KEY_DURATION},
+ * {@link MediaFormat#KEY_MAX_INPUT_SIZE}		{@link MediaFormat#KEY_SAMPLE_RATE},
+ * {@link MediaFormat#KEY_CHANNEL_COUNT},
+ * {@link MediaFormat#KEY_CHANNEL_MASK},
+ * gapless playback information.mp3, .mp4,
+ * {@link MediaFormat#KEY_IS_ADTS}AAC if streaming,
+ * codec-specific dataAAC, Vorbis		{@link MediaFormat#KEY_WIDTH},
+ * {@link MediaFormat#KEY_HEIGHT},
+ * codec-specific dataAVC, MPEG4
{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR1}
{@link android.os.Build.VERSION_CODES#JELLY_BEAN_MR2}as above, plus
+ * Pixel aspect ratio informationAVC, *
{@link android.os.Build.VERSION_CODES#KITKAT}
{@link android.os.Build.VERSION_CODES#KITKAT_WATCH}
{@link android.os.Build.VERSION_CODES#LOLLIPOP}as above, plus
+ * {@link MediaFormat#KEY_BIT_RATE}AAC,
+ * codec-specific dataOpus		as above, plus
+ * {@link MediaFormat#KEY_ROTATION}.mp4,
+ * {@link MediaFormat#KEY_BIT_RATE}MPEG4,
+ * codec-specific dataHEVC
{@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1}
{@link android.os.Build.VERSION_CODES#M}as above, plus
+ * gapless playback informationOpus		as above, plus
+ * {@link MediaFormat#KEY_FRAME_RATE} (integer)
{@link android.os.Build.VERSION_CODES#N}as above, plus
+ * {@link MediaFormat#KEY_TRACK_ID},
+ * + * {@link MediaFormat#KEY_BIT_RATE}#, .mp4		as above, plus
+ * {@link MediaFormat#KEY_PCM_ENCODING},
+ * {@link MediaFormat#KEY_PROFILE}AAC		as above, plus
+ * {@link MediaFormat#KEY_HDR_STATIC_INFO}#, .webm,
+ * {@link MediaFormat#KEY_COLOR_STANDARD}#,
+ * {@link MediaFormat#KEY_COLOR_TRANSFER}#,
+ * {@link MediaFormat#KEY_COLOR_RANGE}#,
+ * {@link MediaFormat#KEY_PROFILE}MPEG2, H.263, MPEG4, AVC, HEVC, VP9,
+ * {@link MediaFormat#KEY_LEVEL}H.263, MPEG4, AVC, HEVC, VP9,
+ * codec-specific dataVP9
+ *

Notes:
+ * #: container-specified value only.
+ * .mp4, .webm…: for listed containers
+ * MPEG4, AAC…: for listed codecs + *

+ *

Note that that level information contained in the container many times + * does not match the level of the actual bitstream. You may want to clear the level using + * {@code MediaFormat.setString(KEY_LEVEL, null)} before using the track format to find a + * decoder that can play back a particular track. + *

+ *

*Pixel (sample) aspect ratio is returned in the following + * keys. The display width can be calculated for example as: + *

+ * display-width = display-height * crop-width / crop-height * sar-width / sar-height + *

Format KeyValue TypeDescription
{@code "sar-width"}IntegerPixel aspect ratio width
{@code "sar-height"}IntegerPixel aspect ratio height
+ * */ @NonNull public MediaFormat getTrackFormat(int index) { -- cgit v1.2.3-59-g8ed1b