Home | History | Annotate | Download | only in media
      1 /*
      2  * Copyright (C) 2012 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 package android.media;
     18 
     19 import java.nio.ByteBuffer;
     20 import java.util.HashMap;
     21 import java.util.Map;
     22 
     23 /**
     24  * Encapsulates the information describing the format of media data,
     25  * be it audio or video.
     26  *
     27  * The format of the media data is specified as string/value pairs.
     28  *
     29  * Keys common to all audio/video formats, <b>all keys not marked optional are mandatory</b>:
     30  *
     31  * <table>
     32  * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr>
     33  * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr>
     34  * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr>
     35  * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr>
     36  * </table>
     37  *
     38  * Video formats have the following keys:
     39  * <table>
     40  * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr>
     41  * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr>
     42  * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr>
     43  * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user
     44  *         for encoders, readable in the output format of decoders</b></td></tr>
     45  * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td><b>encoder-only</b></td></tr>
     46  * <tr><td>{@link #KEY_CAPTURE_RATE}</td><td>Integer</td><td></td></tr>
     47 * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer</td><td><b>encoder-only</b></td></tr>
     48  * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr>
     49  * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr>
     50  * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>video encoder in surface-mode only</b></td></tr>
     51  * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>video decoder rendering to a surface only</b></td></tr>
     52  * </table>
     53  * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable
     54  * adaptive playback (seamless resolution change) for a video decoder that
     55  * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}).
     56  * The values are used as hints for the codec: they are the maximum expected
     57  * resolution to prepare for.  Depending on codec support, preparing for larger
     58  * maximum resolution may require more memory even if that resolution is never
     59  * reached.  These fields have no effect for codecs that do not support adaptive
     60  * playback.<br /><br />
     61  *
     62  * Audio formats have the following keys:
     63  * <table>
     64  * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr>
     65  * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr>
     66  * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr>
     67  * <tr><td>{@link #KEY_IS_ADTS}</td><td>Integer</td><td>optional, if <em>decoding</em> AAC audio content, setting this key to 1 indicates that each audio frame is prefixed by the ADTS header.</td></tr>
     68  * <tr><td>{@link #KEY_AAC_PROFILE}</td><td>Integer</td><td><b>encoder-only</b>, optional, if content is AAC audio, specifies the desired profile.</td></tr>
     69  * <tr><td>{@link #KEY_AAC_SBR_MODE}</td><td>Integer</td><td><b>encoder-only</b>, optional, if content is AAC audio, specifies the desired SBR mode.</td></tr>
     70  * <tr><td>{@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the target reference level.</td></tr>
     71  * <tr><td>{@link #KEY_AAC_ENCODED_TARGET_LEVEL}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the target reference level used at encoder.</td></tr>
     72  * <tr><td>{@link #KEY_AAC_DRC_BOOST_FACTOR}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the DRC boost factor.</td></tr>
     73  * <tr><td>{@link #KEY_AAC_DRC_ATTENUATION_FACTOR}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the DRC attenuation factor.</td></tr>
     74  * <tr><td>{@link #KEY_AAC_DRC_HEAVY_COMPRESSION}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies whether to use heavy compression.</td></tr>
     75  * <tr><td>{@link #KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the maximum number of channels the decoder outputs.</td></tr>
     76  * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr>
     77  * <tr><td>{@link #KEY_FLAC_COMPRESSION_LEVEL}</td><td>Integer</td><td><b>encoder-only</b>, optional, if content is FLAC audio, specifies the desired compression level.</td></tr>
     78  * </table>
     79  *
     80  * Subtitle formats have the following keys:
     81  * <table>
     82  * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr>
     83  * <tr><td>{@link #KEY_LANGUAGE}</td><td>String</td><td>The language of the content.</td></tr>
     84  * </table>
     85  */
     86 public final class MediaFormat {
     87     public static final String MIMETYPE_VIDEO_VP8 = "video/x-vnd.on2.vp8";
     88     public static final String MIMETYPE_VIDEO_VP9 = "video/x-vnd.on2.vp9";
     89     public static final String MIMETYPE_VIDEO_AVC = "video/avc";
     90     public static final String MIMETYPE_VIDEO_HEVC = "video/hevc";
     91     public static final String MIMETYPE_VIDEO_MPEG4 = "video/mp4v-es";
     92     public static final String MIMETYPE_VIDEO_H263 = "video/3gpp";
     93     public static final String MIMETYPE_VIDEO_MPEG2 = "video/mpeg2";
     94     public static final String MIMETYPE_VIDEO_RAW = "video/raw";
     95 
     96     public static final String MIMETYPE_AUDIO_AMR_NB = "audio/3gpp";
     97     public static final String MIMETYPE_AUDIO_AMR_WB = "audio/amr-wb";
     98     public static final String MIMETYPE_AUDIO_MPEG = "audio/mpeg";
     99     public static final String MIMETYPE_AUDIO_AAC = "audio/mp4a-latm";
    100     public static final String MIMETYPE_AUDIO_QCELP = "audio/qcelp";
    101     public static final String MIMETYPE_AUDIO_VORBIS = "audio/vorbis";
    102     public static final String MIMETYPE_AUDIO_OPUS = "audio/opus";
    103     public static final String MIMETYPE_AUDIO_G711_ALAW = "audio/g711-alaw";
    104     public static final String MIMETYPE_AUDIO_G711_MLAW = "audio/g711-mlaw";
    105     public static final String MIMETYPE_AUDIO_RAW = "audio/raw";
    106     public static final String MIMETYPE_AUDIO_FLAC = "audio/flac";
    107     public static final String MIMETYPE_AUDIO_MSGSM = "audio/gsm";
    108     public static final String MIMETYPE_AUDIO_AC3 = "audio/ac3";
    109     /**
    110      * @hide
    111      */
    112     public static final String MIMETYPE_AUDIO_EAC3 = "audio/eac3";
    113 
    114     /**
    115      * MIME type for WebVTT subtitle data.
    116      */
    117     public static final String MIMETYPE_TEXT_VTT = "text/vtt";
    118 
    119     /**
    120      * MIME type for CEA-608 closed caption data.
    121      */
    122     public static final String MIMETYPE_TEXT_CEA_608 = "text/cea-608";
    123 
    124     private Map<String, Object> mMap;
    125 
    126     /**
    127      * A key describing the mime type of the MediaFormat.
    128      * The associated value is a string.
    129      */
    130     public static final String KEY_MIME = "mime";
    131 
    132     /**
    133      * A key describing the language of the content, using either ISO 639-1
    134      * or 639-2/T codes.  The associated value is a string.
    135      */
    136     public static final String KEY_LANGUAGE = "language";
    137 
    138     /**
    139      * A key describing the sample rate of an audio format.
    140      * The associated value is an integer
    141      */
    142     public static final String KEY_SAMPLE_RATE = "sample-rate";
    143 
    144     /**
    145      * A key describing the number of channels in an audio format.
    146      * The associated value is an integer
    147      */
    148     public static final String KEY_CHANNEL_COUNT = "channel-count";
    149 
    150     /**
    151      * A key describing the width of the content in a video format.
    152      * The associated value is an integer
    153      */
    154     public static final String KEY_WIDTH = "width";
    155 
    156     /**
    157      * A key describing the height of the content in a video format.
    158      * The associated value is an integer
    159      */
    160     public static final String KEY_HEIGHT = "height";
    161 
    162     /**
    163      * A key describing the maximum expected width of the content in a video
    164      * decoder format, in case there are resolution changes in the video content.
    165      * The associated value is an integer
    166      */
    167     public static final String KEY_MAX_WIDTH = "max-width";
    168 
    169     /**
    170      * A key describing the maximum expected height of the content in a video
    171      * decoder format, in case there are resolution changes in the video content.
    172      * The associated value is an integer
    173      */
    174     public static final String KEY_MAX_HEIGHT = "max-height";
    175 
    176     /** A key describing the maximum size in bytes of a buffer of data
    177      * described by this MediaFormat.
    178      * The associated value is an integer
    179      */
    180     public static final String KEY_MAX_INPUT_SIZE = "max-input-size";
    181 
    182     /**
    183      * A key describing the bitrate in bits/sec.
    184      * The associated value is an integer
    185      */
    186     public static final String KEY_BIT_RATE = "bitrate";
    187 
    188     /**
    189      * A key describing the color format of the content in a video format.
    190      * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}.
    191      */
    192     public static final String KEY_COLOR_FORMAT = "color-format";
    193 
    194     /**
    195      * A key describing the frame rate of a video format in frames/sec.
    196      * The associated value is an integer or a float.
    197      */
    198     public static final String KEY_FRAME_RATE = "frame-rate";
    199 
    200     /**
    201      * A key describing the capture rate of a video format in frames/sec.
    202      * <p>
    203      * When capture rate is different than the frame rate, it means that the
    204      * video is acquired at a different rate than the playback, which produces
    205      * slow motion or timelapse effect during playback. Application can use the
    206      * value of this key to tell the relative speed ratio between capture and
    207      * playback rates when the video was recorded.
    208      * </p>
    209      * <p>
    210      * The associated value is an integer or a float.
    211      * </p>
    212      */
    213     public static final String KEY_CAPTURE_RATE = "capture-rate";
    214 
    215     /**
    216      * A key describing the frequency of I frames expressed in secs
    217      * between I frames.
    218      * The associated value is an integer.
    219      */
    220     public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval";
    221 
    222     /**
    223      * A key describing the temporal layering schema.  This is an optional parameter
    224      * that applies only to video encoders.  Use {@link MediaCodec#getInputFormat}
    225      * after {@link MediaCodec#configure configure} to query if the encoder supports
    226      * the desired schema. Supported values are {@code webrtc.vp8.1-layer},
    227      * {@code webrtc.vp8.2-layer}, {@code webrtc.vp8.3-layer}, and {@code none}.
    228      * If the encoder does not support temporal layering, the input format will
    229      * not have an entry with this key.
    230      * The associated value is a string.
    231      */
    232     public static final String KEY_TEMPORAL_LAYERING = "ts-schema";
    233 
    234     /**
    235      * @hide
    236      */
    237     public static final String KEY_STRIDE = "stride";
    238     /**
    239      * @hide
    240      */
    241     public static final String KEY_SLICE_HEIGHT = "slice-height";
    242 
    243     /**
    244      * Applies only when configuring a video encoder in "surface-input" mode.
    245      * The associated value is a long and gives the time in microseconds
    246      * after which the frame previously submitted to the encoder will be
    247      * repeated (once) if no new frame became available since.
    248      */
    249     public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER
    250         = "repeat-previous-frame-after";
    251 
    252     /**
    253      * If specified when configuring a video decoder rendering to a surface,
    254      * causes the decoder to output "blank", i.e. black frames to the surface
    255      * when stopped to clear out any previously displayed contents.
    256      * The associated value is an integer of value 1.
    257      */
    258     public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP
    259         = "push-blank-buffers-on-shutdown";
    260 
    261     /**
    262      * A key describing the duration (in microseconds) of the content.
    263      * The associated value is a long.
    264      */
    265     public static final String KEY_DURATION = "durationUs";
    266 
    267     /**
    268      * A key mapping to a value of 1 if the content is AAC audio and
    269      * audio frames are prefixed with an ADTS header.
    270      * The associated value is an integer (0 or 1).
    271      * This key is only supported when _decoding_ content, it cannot
    272      * be used to configure an encoder to emit ADTS output.
    273      */
    274     public static final String KEY_IS_ADTS = "is-adts";
    275 
    276     /**
    277      * A key describing the channel composition of audio content. This mask
    278      * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}.
    279      * The associated value is an integer.
    280      */
    281     public static final String KEY_CHANNEL_MASK = "channel-mask";
    282 
    283     /**
    284      * A key describing the AAC profile to be used (AAC audio formats only).
    285      * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}.
    286      */
    287     public static final String KEY_AAC_PROFILE = "aac-profile";
    288 
    289     /**
    290      * A key describing the AAC SBR mode to be used (AAC audio formats only).
    291      * The associated value is an integer and can be set to following values:
    292      * <ul>
    293      * <li>0 - no SBR should be applied</li>
    294      * <li>1 - single rate SBR</li>
    295      * <li>2 - double rate SBR</li>
    296      * </ul>
    297      * Note: If this key is not defined the default SRB mode for the desired AAC profile will
    298      * be used.
    299      * <p>This key is only used during encoding.
    300      */
    301     public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode";
    302 
    303     /**
    304      * A key describing the maximum number of channels that can be output by the AAC decoder.
    305      * By default, the decoder will output the same number of channels as present in the encoded
    306      * stream, if supported. Set this value to limit the number of output channels, and use
    307      * the downmix information in the stream, if available.
    308      * <p>Values larger than the number of channels in the content to decode are ignored.
    309      * <p>This key is only used during decoding.
    310      */
    311     public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count";
    312 
    313     /**
    314      * A key describing a gain to be applied so that the output loudness matches the
    315      * Target Reference Level. This is typically used to normalize loudness across program items.
    316      * The gain is derived as the difference between the Target Reference Level and the
    317      * Program Reference Level. The latter can be given in the bitstream and indicates the actual
    318      * loudness value of the program item.
    319      * <p>The value is given as an integer value between
    320      * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS.
    321      * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS.
    322      * <p>This key is only used during decoding.
    323      */
    324     public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level";
    325 
    326     /**
    327      * A key describing the target reference level that was assumed at the encoder for
    328      * calculation of attenuation gains for clipping prevention. This information can be provided
    329      * if it is known, otherwise a worst-case assumption is used.
    330      * <p>The value is given as an integer value between
    331      * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS.
    332      * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS.
    333      * The default value is the worst-case assumption of 127.
    334      * <p>The value is ignored when heavy compression is used (see
    335      * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}).
    336      * <p>This key is only used during decoding.
    337      */
    338     public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level";
    339 
    340     /**
    341      * A key describing the boost factor allowing to adapt the dynamics of the output to the
    342      * actual listening requirements. This relies on DRC gain sequences that can be transmitted in
    343      * the encoded bitstream to be able to reduce the dynamics of the output signal upon request.
    344      * This factor enables the user to select how much of the gains are applied.
    345      * <p>Positive gains (boost) and negative gains (attenuation, see
    346      * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match
    347      * to different use-cases.
    348      * <p>Typically, attenuation gains are sent for loud signal segments, and boost gains are sent
    349      * for soft signal segments. If the output is listened to in a noisy environment, for example,
    350      * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments
    351      * beyond the noise floor. But for listening late at night, the attenuation
    352      * factor is used to enable the negative gains, to prevent loud signal from surprising
    353      * the listener. In applications which generally need a low dynamic range, both the boost factor
    354      * and the attenuation factor are used in order to enable all DRC gains.
    355      * <p>In order to prevent clipping, it is also recommended to apply the attenuation factors
    356      * in case of a downmix and/or loudness normalization to high target reference levels.
    357      * <p>Both the boost and the attenuation factor parameters are given as integer values
    358      * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply)
    359      * to 1 (i.e. fully apply boost/attenuation factors respectively).
    360      * <p>This key is only used during decoding.
    361      */
    362     public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level";
    363 
    364     /**
    365      * A key describing the attenuation factor allowing to adapt the dynamics of the output to the
    366      * actual listening requirements.
    367      * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation
    368      * factor and the value range.
    369      * <p>This key is only used during decoding.
    370      */
    371     public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level";
    372 
    373     /**
    374      * A key describing the selection of the heavy compression profile for DRC.
    375      * Two separate DRC gain sequences can be transmitted in one bitstream: MPEG-4 DRC light
    376      * compression, and DVB-specific heavy compression. When selecting the application of the heavy
    377      * compression, one of the sequences is selected:
    378      * <ul>
    379      * <li>0 enables light compression,</li>
    380      * <li>1 enables heavy compression instead.
    381      * </ul>
    382      * Note that only light compression offers the features of scaling of DRC gains
    383      * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the
    384      * boost and attenuation factors, and frequency-selective (multiband) DRC.
    385      * Light compression usually contains clipping prevention for stereo downmixing while heavy
    386      * compression, if additionally provided in the bitstream, is usually stronger, and contains
    387      * clipping prevention for stereo and mono downmixing.
    388      * <p>The default is light compression.
    389      * <p>This key is only used during decoding.
    390      */
    391     public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression";
    392 
    393     /**
    394      * A key describing the FLAC compression level to be used (FLAC audio format only).
    395      * The associated value is an integer ranging from 0 (fastest, least compression)
    396      * to 8 (slowest, most compression).
    397      */
    398     public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level";
    399 
    400     /**
    401      * A key describing the encoding complexity.
    402      * The associated value is an integer.  These values are device and codec specific,
    403      * but lower values generally result in faster and/or less power-hungry encoding.
    404      *
    405      * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange()
    406      */
    407     public static final String KEY_COMPLEXITY = "complexity";
    408 
    409     /**
    410      * A key describing the desired encoding quality.
    411      * The associated value is an integer.  This key is only supported for encoders
    412      * that are configured in constant-quality mode.  These values are device and
    413      * codec specific, but lower values generally result in more efficient
    414      * (smaller-sized) encoding.
    415      *
    416      * @hide
    417      *
    418      * @see MediaCodecInfo.EncoderCapabilities#getQualityRange()
    419      */
    420     public static final String KEY_QUALITY = "quality";
    421 
    422     /**
    423      * A key describing the desired profile to be used by an encoder.
    424      * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}.
    425      * This key is only supported for codecs that specify a profile.
    426      *
    427      * @see MediaCodecInfo.CodecCapabilities#profileLevels
    428      */
    429     public static final String KEY_PROFILE = "profile";
    430 
    431     /**
    432      * A key describing the desired bitrate mode to be used by an encoder.
    433      * Constants are declared in {@link MediaCodecInfo.CodecCapabilities}.
    434      *
    435      * @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int)
    436      */
    437     public static final String KEY_BITRATE_MODE = "bitrate-mode";
    438 
    439     /**
    440      * A key describing the audio session ID of the AudioTrack associated
    441      * to a tunneled video codec.
    442      * The associated value is an integer.
    443      *
    444      * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback
    445      */
    446     public static final String KEY_AUDIO_SESSION_ID = "audio-session-id";
    447 
    448     /**
    449      * A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true
    450      * are considered when automatically selecting a track without specific user
    451      * choice, based on the current locale.
    452      * This is currently only used for subtitle tracks, when the user selected
    453      * 'Default' for the captioning locale.
    454      * The associated value is an integer, where non-0 means TRUE.  This is an optional
    455      * field; if not specified, AUTOSELECT defaults to TRUE.
    456      */
    457     public static final String KEY_IS_AUTOSELECT = "is-autoselect";
    458 
    459     /**
    460      * A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is
    461      * selected in the absence of a specific user choice.
    462      * This is currently only used for subtitle tracks, when the user selected
    463      * 'Default' for the captioning locale.
    464      * The associated value is an integer, where non-0 means TRUE.  This is an optional
    465      * field; if not specified, DEFAULT is considered to be FALSE.
    466      */
    467     public static final String KEY_IS_DEFAULT = "is-default";
    468 
    469 
    470     /**
    471      * A key for the FORCED field for subtitle tracks. True if it is a
    472      * forced subtitle track.  Forced subtitle tracks are essential for the
    473      * content and are shown even when the user turns off Captions.  They
    474      * are used for example to translate foreign/alien dialogs or signs.
    475      * The associated value is an integer, where non-0 means TRUE.  This is an
    476      * optional field; if not specified, FORCED defaults to FALSE.
    477      */
    478     public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle";
    479 
    480     /** @hide */
    481     public static final String KEY_IS_TIMED_TEXT = "is-timed-text";
    482 
    483     /* package private */ MediaFormat(Map<String, Object> map) {
    484         mMap = map;
    485     }
    486 
    487     /**
    488      * Creates an empty MediaFormat
    489      */
    490     public MediaFormat() {
    491         mMap = new HashMap();
    492     }
    493 
    494     /* package private */ Map<String, Object> getMap() {
    495         return mMap;
    496     }
    497 
    498     /**
    499      * Returns true iff a key of the given name exists in the format.
    500      */
    501     public final boolean containsKey(String name) {
    502         return mMap.containsKey(name);
    503     }
    504 
    505     /**
    506      * A key prefix used together with a {@link MediaCodecInfo.CodecCapabilities}
    507      * feature name describing a required or optional feature for a codec capabilities
    508      * query.
    509      * The associated value is an integer, where non-0 value means the feature is
    510      * requested to be present, while 0 value means the feature is requested to be not
    511      * present.
    512      * @see MediaCodecList#findDecoderForFormat
    513      * @see MediaCodecList#findEncoderForFormat
    514      * @see MediaCodecInfo.CodecCapabilities#isFormatSupported
    515      *
    516      * @hide
    517      */
    518     public static final String KEY_FEATURE_ = "feature-";
    519 
    520     /**
    521      * Returns the value of an integer key.
    522      */
    523     public final int getInteger(String name) {
    524         return ((Integer)mMap.get(name)).intValue();
    525     }
    526 
    527     /**
    528      * Returns the value of an integer key, or the default value if the
    529      * key is missing or is for another type value.
    530      * @hide
    531      */
    532     public final int getInteger(String name, int defaultValue) {
    533         try {
    534             return getInteger(name);
    535         }
    536         catch (NullPointerException  e) { /* no such field */ }
    537         catch (ClassCastException e) { /* field of different type */ }
    538         return defaultValue;
    539     }
    540 
    541     /**
    542      * Returns the value of a long key.
    543      */
    544     public final long getLong(String name) {
    545         return ((Long)mMap.get(name)).longValue();
    546     }
    547 
    548     /**
    549      * Returns the value of a float key.
    550      */
    551     public final float getFloat(String name) {
    552         return ((Float)mMap.get(name)).floatValue();
    553     }
    554 
    555     /**
    556      * Returns the value of a string key.
    557      */
    558     public final String getString(String name) {
    559         return (String)mMap.get(name);
    560     }
    561 
    562     /**
    563      * Returns the value of a ByteBuffer key.
    564      */
    565     public final ByteBuffer getByteBuffer(String name) {
    566         return (ByteBuffer)mMap.get(name);
    567     }
    568 
    569     /**
    570      * Returns whether a feature is to be enabled ({@code true}) or disabled
    571      * ({@code false}).
    572      *
    573      * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature.
    574      *
    575      * @throws IllegalArgumentException if the feature was neither set to be enabled
    576      *        nor to be disabled.
    577      */
    578     public boolean getFeatureEnabled(String feature) {
    579         Integer enabled = (Integer)mMap.get(KEY_FEATURE_ + feature);
    580         if (enabled == null) {
    581             throw new IllegalArgumentException("feature is not specified");
    582         }
    583         return enabled != 0;
    584     }
    585 
    586     /**
    587      * Sets the value of an integer key.
    588      */
    589     public final void setInteger(String name, int value) {
    590         mMap.put(name, new Integer(value));
    591     }
    592 
    593     /**
    594      * Sets the value of a long key.
    595      */
    596     public final void setLong(String name, long value) {
    597         mMap.put(name, new Long(value));
    598     }
    599 
    600     /**
    601      * Sets the value of a float key.
    602      */
    603     public final void setFloat(String name, float value) {
    604         mMap.put(name, new Float(value));
    605     }
    606 
    607     /**
    608      * Sets the value of a string key.
    609      */
    610     public final void setString(String name, String value) {
    611         mMap.put(name, value);
    612     }
    613 
    614     /**
    615      * Sets the value of a ByteBuffer key.
    616      */
    617     public final void setByteBuffer(String name, ByteBuffer bytes) {
    618         mMap.put(name, bytes);
    619     }
    620 
    621     /**
    622      * Sets whether a feature is to be enabled ({@code true}) or disabled
    623      * ({@code false}).
    624      *
    625      * If {@code enabled} is {@code true}, the feature is requested to be present.
    626      * Otherwise, the feature is requested to be not present.
    627      *
    628      * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature.
    629      *
    630      * @see MediaCodecList#findDecoderForFormat
    631      * @see MediaCodecList#findEncoderForFormat
    632      * @see MediaCodecInfo.CodecCapabilities#isFormatSupported
    633      */
    634     public void setFeatureEnabled(String feature, boolean enabled) {
    635         setInteger(KEY_FEATURE_ + feature, enabled ? 1 : 0);
    636     }
    637 
    638     /**
    639      * Creates a minimal audio format.
    640      * @param mime The mime type of the content.
    641      * @param sampleRate The sampling rate of the content.
    642      * @param channelCount The number of audio channels in the content.
    643      */
    644     public static final MediaFormat createAudioFormat(
    645             String mime,
    646             int sampleRate,
    647             int channelCount) {
    648         MediaFormat format = new MediaFormat();
    649         format.setString(KEY_MIME, mime);
    650         format.setInteger(KEY_SAMPLE_RATE, sampleRate);
    651         format.setInteger(KEY_CHANNEL_COUNT, channelCount);
    652 
    653         return format;
    654     }
    655 
    656     /**
    657      * Creates a minimal subtitle format.
    658      * @param mime The mime type of the content.
    659      * @param language The language of the content, using either ISO 639-1 or 639-2/T
    660      *        codes.  Specify null or "und" if language information is only included
    661      *        in the content.  (This will also work if there are multiple language
    662      *        tracks in the content.)
    663      */
    664     public static final MediaFormat createSubtitleFormat(
    665             String mime,
    666             String language) {
    667         MediaFormat format = new MediaFormat();
    668         format.setString(KEY_MIME, mime);
    669         format.setString(KEY_LANGUAGE, language);
    670 
    671         return format;
    672     }
    673 
    674     /**
    675      * Creates a minimal video format.
    676      * @param mime The mime type of the content.
    677      * @param width The width of the content (in pixels)
    678      * @param height The height of the content (in pixels)
    679      */
    680     public static final MediaFormat createVideoFormat(
    681             String mime,
    682             int width,
    683             int height) {
    684         MediaFormat format = new MediaFormat();
    685         format.setString(KEY_MIME, mime);
    686         format.setInteger(KEY_WIDTH, width);
    687         format.setInteger(KEY_HEIGHT, height);
    688 
    689         return format;
    690     }
    691 
    692     @Override
    693     public String toString() {
    694         return mMap.toString();
    695     }
    696 }
    697