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 android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.compat.annotation.UnsupportedAppUsage; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 import java.nio.ByteBuffer; 27 import java.nio.ByteOrder; 28 import java.util.AbstractSet; 29 import java.util.HashMap; 30 import java.util.Iterator; 31 import java.util.Map; 32 import java.util.Set; 33 import java.util.stream.Collectors; 34 35 /** 36 * Encapsulates the information describing the format of media data, be it audio or video, as 37 * well as optional feature metadata. 38 * <p> 39 * The format of the media data is specified as key/value pairs. Keys are strings. Values can 40 * be integer, long, float, String or ByteBuffer. 41 * <p> 42 * The feature metadata is specificed as string/boolean pairs. 43 * <p> 44 * Keys common to all audio/video formats, <b>all keys not marked optional are mandatory</b>: 45 * 46 * <table> 47 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 48 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 49 * <tr><td>{@link #KEY_CODECS_STRING}</td><td>String</td><td>optional, the RFC 6381 codecs string of the MediaFormat</td></tr> 50 * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr> 51 * <tr><td>{@link #KEY_PIXEL_ASPECT_RATIO_WIDTH}</td><td>Integer</td><td>optional, the pixel aspect ratio width</td></tr> 52 * <tr><td>{@link #KEY_PIXEL_ASPECT_RATIO_HEIGHT}</td><td>Integer</td><td>optional, the pixel aspect ratio height</td></tr> 53 * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr> 54 * <tr><td>{@link #KEY_DURATION}</td><td>long</td><td>the duration of the content (in microseconds)</td></tr> 55 * </table> 56 * 57 * Video formats have the following keys: 58 * <table> 59 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 60 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 61 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 62 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 63 * for encoders, readable in the output format of decoders</b></td></tr> 64 * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td>required for <b>encoders</b>, 65 * optional for <b>decoders</b></td></tr> 66 * <tr><td>{@link #KEY_CAPTURE_RATE}</td><td>Integer</td><td></td></tr> 67 * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer (or Float)</td><td><b>encoder-only</b>, 68 * time-interval between key frames. 69 * Float support added in {@link android.os.Build.VERSION_CODES#N_MR1}</td></tr> 70 * <tr><td>{@link #KEY_INTRA_REFRESH_PERIOD}</td><td>Integer</td><td><b>encoder-only</b>, optional</td></tr> 71 * <tr><td>{@link #KEY_LATENCY}</td><td>Integer</td><td><b>encoder-only</b>, optional</td></tr> 72 * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr> 73 * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr> 74 * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>encoder in surface-mode 75 * only</b>, optional</td></tr> 76 * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>decoder rendering 77 * to a surface only</b>, optional</td></tr> 78 * <tr><td>{@link #KEY_TEMPORAL_LAYERING}</td><td>String</td><td><b>encoder only</b>, optional, 79 * temporal-layering schema</td></tr> 80 * </table> 81 * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable 82 * adaptive playback (seamless resolution change) for a video decoder that 83 * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}). 84 * The values are used as hints for the codec: they are the maximum expected 85 * resolution to prepare for. Depending on codec support, preparing for larger 86 * maximum resolution may require more memory even if that resolution is never 87 * reached. These fields have no effect for codecs that do not support adaptive 88 * playback.<br /><br /> 89 * 90 * Audio formats have the following keys: 91 * <table> 92 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 93 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr> 94 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr> 95 * <tr><td>{@link #KEY_PCM_ENCODING}</td><td>Integer</td><td>optional</td></tr> 96 * <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> 97 * <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> 98 * <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> 99 * <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> 100 * <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> 101 * <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> 102 * <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> 103 * <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> 104 * <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> 105 * <tr><td>{@link #KEY_AAC_DRC_EFFECT_TYPE}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the MPEG-D DRC effect type to use.</td></tr> 106 * <tr><td>{@link #KEY_AAC_DRC_OUTPUT_LOUDNESS}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, returns the DRC output loudness.</td></tr> 107 * <tr><td>{@link #KEY_AAC_DRC_ALBUM_MODE}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the whether MPEG-D DRC Album Mode is active or not.</td></tr> 108 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr> 109 * <tr><td>{@link #KEY_ENCODER_DELAY}</td><td>Integer</td><td>optional, the number of frames to trim from the start of the decoded audio stream.</td></tr> 110 * <tr><td>{@link #KEY_ENCODER_PADDING}</td><td>Integer</td><td>optional, the number of frames to trim from the end of the decoded audio stream.</td></tr> 111 * <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> 112 * <tr><td>{@link #KEY_MPEGH_PROFILE_LEVEL_INDICATION}</td><td>Integer</td> 113 * <td><b>decoder-only</b>, optional, if content is MPEG-H audio, 114 * specifies the profile and level of the stream.</td></tr> 115 * <tr><td>{@link #KEY_MPEGH_COMPATIBLE_SETS}</td><td>ByteBuffer</td> 116 * <td><b>decoder-only</b>, optional, if content is MPEG-H audio, 117 * specifies the compatible sets (profile and level) of the stream.</td></tr> 118 * <tr><td>{@link #KEY_MPEGH_REFERENCE_CHANNEL_LAYOUT}</td> 119 * <td>Integer</td><td><b>decoder-only</b>, optional, if content is MPEG-H audio, 120 * specifies the preferred reference channel layout of the stream.</td></tr> 121 * </table> 122 * 123 * Subtitle formats have the following keys: 124 * <table> 125 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 126 * <tr><td>{@link #KEY_LANGUAGE}</td><td>String</td><td>The language of the content.</td></tr> 127 * <tr><td>{@link #KEY_CAPTION_SERVICE_NUMBER}</td><td>int</td><td>optional, the closed-caption service or channel number.</td></tr> 128 * </table> 129 * 130 * Image formats have the following keys: 131 * <table> 132 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 133 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 134 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 135 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 136 * for encoders, readable in the output format of decoders</b></td></tr> 137 * <tr><td>{@link #KEY_TILE_WIDTH}</td><td>Integer</td><td>required if the image has grid</td></tr> 138 * <tr><td>{@link #KEY_TILE_HEIGHT}</td><td>Integer</td><td>required if the image has grid</td></tr> 139 * <tr><td>{@link #KEY_GRID_ROWS}</td><td>Integer</td><td>required if the image has grid</td></tr> 140 * <tr><td>{@link #KEY_GRID_COLUMNS}</td><td>Integer</td><td>required if the image has grid</td></tr> 141 * </table> 142 */ 143 public final class MediaFormat { 144 public static final String MIMETYPE_VIDEO_VP8 = "video/x-vnd.on2.vp8"; 145 public static final String MIMETYPE_VIDEO_VP9 = "video/x-vnd.on2.vp9"; 146 public static final String MIMETYPE_VIDEO_AV1 = "video/av01"; 147 public static final String MIMETYPE_VIDEO_AVC = "video/avc"; 148 public static final String MIMETYPE_VIDEO_HEVC = "video/hevc"; 149 public static final String MIMETYPE_VIDEO_MPEG4 = "video/mp4v-es"; 150 public static final String MIMETYPE_VIDEO_H263 = "video/3gpp"; 151 public static final String MIMETYPE_VIDEO_MPEG2 = "video/mpeg2"; 152 public static final String MIMETYPE_VIDEO_RAW = "video/raw"; 153 public static final String MIMETYPE_VIDEO_DOLBY_VISION = "video/dolby-vision"; 154 public static final String MIMETYPE_VIDEO_SCRAMBLED = "video/scrambled"; 155 156 public static final String MIMETYPE_AUDIO_AMR_NB = "audio/3gpp"; 157 public static final String MIMETYPE_AUDIO_AMR_WB = "audio/amr-wb"; 158 public static final String MIMETYPE_AUDIO_MPEG = "audio/mpeg"; 159 public static final String MIMETYPE_AUDIO_AAC = "audio/mp4a-latm"; 160 public static final String MIMETYPE_AUDIO_QCELP = "audio/qcelp"; 161 public static final String MIMETYPE_AUDIO_VORBIS = "audio/vorbis"; 162 public static final String MIMETYPE_AUDIO_OPUS = "audio/opus"; 163 public static final String MIMETYPE_AUDIO_G711_ALAW = "audio/g711-alaw"; 164 public static final String MIMETYPE_AUDIO_G711_MLAW = "audio/g711-mlaw"; 165 public static final String MIMETYPE_AUDIO_RAW = "audio/raw"; 166 public static final String MIMETYPE_AUDIO_FLAC = "audio/flac"; 167 public static final String MIMETYPE_AUDIO_MSGSM = "audio/gsm"; 168 public static final String MIMETYPE_AUDIO_AC3 = "audio/ac3"; 169 public static final String MIMETYPE_AUDIO_EAC3 = "audio/eac3"; 170 public static final String MIMETYPE_AUDIO_EAC3_JOC = "audio/eac3-joc"; 171 public static final String MIMETYPE_AUDIO_AC4 = "audio/ac4"; 172 public static final String MIMETYPE_AUDIO_SCRAMBLED = "audio/scrambled"; 173 /** MIME type for MPEG-H Audio single stream */ 174 public static final String MIMETYPE_AUDIO_MPEGH_MHA1 = "audio/mha1"; 175 /** MIME type for MPEG-H Audio single stream, encapsulated in MHAS */ 176 public static final String MIMETYPE_AUDIO_MPEGH_MHM1 = "audio/mhm1"; 177 178 /** 179 * MIME type for HEIF still image data encoded in HEVC. 180 * 181 * To decode such an image, {@link MediaCodec} decoder for 182 * {@link #MIMETYPE_VIDEO_HEVC} shall be used. The client needs to form 183 * the correct {@link #MediaFormat} based on additional information in 184 * the track format, and send it to {@link MediaCodec#configure}. 185 * 186 * The track's MediaFormat will come with {@link #KEY_WIDTH} and 187 * {@link #KEY_HEIGHT} keys, which describes the width and height 188 * of the image. If the image doesn't contain grid (i.e. none of 189 * {@link #KEY_TILE_WIDTH}, {@link #KEY_TILE_HEIGHT}, 190 * {@link #KEY_GRID_ROWS}, {@link #KEY_GRID_COLUMNS} are present}), the 191 * track will contain a single sample of coded data for the entire image, 192 * and the image width and height should be used to set up the decoder. 193 * 194 * If the image does come with grid, each sample from the track will 195 * contain one tile in the grid, of which the size is described by 196 * {@link #KEY_TILE_WIDTH} and {@link #KEY_TILE_HEIGHT}. This size 197 * (instead of {@link #KEY_WIDTH} and {@link #KEY_HEIGHT}) should be 198 * used to set up the decoder. The track contains {@link #KEY_GRID_ROWS} 199 * by {@link #KEY_GRID_COLUMNS} samples in row-major, top-row first, 200 * left-to-right order. The output image should be reconstructed by 201 * first tiling the decoding results of the tiles in the correct order, 202 * then trimming (before rotation is applied) on the bottom and right 203 * side, if the tiled area is larger than the image width and height. 204 */ 205 public static final String MIMETYPE_IMAGE_ANDROID_HEIC = "image/vnd.android.heic"; 206 207 /** 208 * MIME type for WebVTT subtitle data. 209 */ 210 public static final String MIMETYPE_TEXT_VTT = "text/vtt"; 211 212 /** 213 * MIME type for SubRip (SRT) container. 214 */ 215 public static final String MIMETYPE_TEXT_SUBRIP = "application/x-subrip"; 216 217 /** 218 * MIME type for CEA-608 closed caption data. 219 */ 220 public static final String MIMETYPE_TEXT_CEA_608 = "text/cea-608"; 221 222 /** 223 * MIME type for CEA-708 closed caption data. 224 */ 225 public static final String MIMETYPE_TEXT_CEA_708 = "text/cea-708"; 226 227 @UnsupportedAppUsage 228 private Map<String, Object> mMap; 229 230 /** 231 * A key describing the log session ID for MediaCodec. The log session ID is a random 32-byte 232 * hexadecimal string that is used to associate metrics from multiple media codec instances 233 * to the same playback or recording session. 234 * The associated value is a string. 235 * @hide 236 */ 237 public static final String LOG_SESSION_ID = "log-session-id"; 238 239 /** 240 * A key describing the mime type of the MediaFormat. 241 * The associated value is a string. 242 */ 243 public static final String KEY_MIME = "mime"; 244 245 /** 246 * A key describing the codecs string of the MediaFormat. See RFC 6381 section 3.2 for the 247 * syntax of the value. The value does not hold {@link MediaCodec}-exposed codec names. 248 * The associated value is a string. 249 * 250 * @see MediaParser.TrackData#mediaFormat 251 */ 252 public static final String KEY_CODECS_STRING = "codecs-string"; 253 254 /** 255 * An optional key describing the low latency decoding mode. This is an optional parameter 256 * that applies only to decoders. If enabled, the decoder doesn't hold input and output 257 * data more than required by the codec standards. 258 * The associated value is an integer (0 or 1): 1 when low-latency decoding is enabled, 259 * 0 otherwise. The default value is 0. 260 */ 261 public static final String KEY_LOW_LATENCY = "low-latency"; 262 263 /** 264 * A key describing the language of the content, using either ISO 639-1 265 * or 639-2/T codes. The associated value is a string. 266 */ 267 public static final String KEY_LANGUAGE = "language"; 268 269 /** 270 * A key describing the closed caption service number. For CEA-608 caption tracks, holds the 271 * channel number. For CEA-708, holds the service number. 272 * The associated value is an int. 273 */ 274 public static final String KEY_CAPTION_SERVICE_NUMBER = "caption-service-number"; 275 276 /** 277 * A key describing the sample rate of an audio format. 278 * The associated value is an integer 279 */ 280 public static final String KEY_SAMPLE_RATE = "sample-rate"; 281 282 /** 283 * A key describing the number of channels in an audio format. 284 * The associated value is an integer 285 */ 286 public static final String KEY_CHANNEL_COUNT = "channel-count"; 287 288 /** 289 * A key describing the width of the content in a video format. 290 * The associated value is an integer 291 */ 292 public static final String KEY_WIDTH = "width"; 293 294 /** 295 * A key describing the height of the content in a video format. 296 * The associated value is an integer 297 */ 298 public static final String KEY_HEIGHT = "height"; 299 300 /** 301 * A key describing the maximum expected width of the content in a video 302 * decoder format, in case there are resolution changes in the video content. 303 * The associated value is an integer 304 */ 305 public static final String KEY_MAX_WIDTH = "max-width"; 306 307 /** 308 * A key describing the maximum expected height of the content in a video 309 * decoder format, in case there are resolution changes in the video content. 310 * The associated value is an integer 311 */ 312 public static final String KEY_MAX_HEIGHT = "max-height"; 313 314 /** A key describing the maximum size in bytes of a buffer of data 315 * described by this MediaFormat. 316 * The associated value is an integer 317 */ 318 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 319 320 /** 321 * A key describing the pixel aspect ratio width. 322 * The associated value is an integer 323 */ 324 public static final String KEY_PIXEL_ASPECT_RATIO_WIDTH = "sar-width"; 325 326 /** 327 * A key describing the pixel aspect ratio height. 328 * The associated value is an integer 329 */ 330 public static final String KEY_PIXEL_ASPECT_RATIO_HEIGHT = "sar-height"; 331 332 /** 333 * A key describing the average bitrate in bits/sec. 334 * The associated value is an integer 335 */ 336 public static final String KEY_BIT_RATE = "bitrate"; 337 338 /** 339 * A key describing the hardware AV sync id. 340 * The associated value is an integer 341 * 342 * See android.media.tv.tuner.Tuner#getAvSyncHwId. 343 */ 344 public static final String KEY_HARDWARE_AV_SYNC_ID = "hw-av-sync-id"; 345 346 /** 347 * A key describing the max bitrate in bits/sec. 348 * This is usually over a one-second sliding window (e.g. over any window of one second). 349 * The associated value is an integer 350 * @hide 351 */ 352 public static final String KEY_MAX_BIT_RATE = "max-bitrate"; 353 354 /** 355 * A key describing the color format of the content in a video format. 356 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 357 */ 358 public static final String KEY_COLOR_FORMAT = "color-format"; 359 360 /** 361 * A key describing the frame rate of a video format in frames/sec. 362 * The associated value is normally an integer when the value is used by the platform, 363 * but video codecs also accept float configuration values. 364 * Specifically, {@link MediaExtractor#getTrackFormat MediaExtractor} provides an integer 365 * value corresponding to the frame rate information of the track if specified and non-zero. 366 * Otherwise, this key is not present. {@link MediaCodec#configure MediaCodec} accepts both 367 * float and integer values. This represents the desired operating frame rate if the 368 * {@link #KEY_OPERATING_RATE} is not present and {@link #KEY_PRIORITY} is {@code 0} 369 * (realtime). For video encoders this value corresponds to the intended frame rate, 370 * although encoders are expected 371 * to support variable frame rate based on {@link MediaCodec.BufferInfo#presentationTimeUs 372 * buffer timestamp}. This key is not used in the {@code MediaCodec} 373 * {@link MediaCodec#getInputFormat input}/{@link MediaCodec#getOutputFormat output} formats, 374 * nor by {@link MediaMuxer#addTrack MediaMuxer}. 375 */ 376 public static final String KEY_FRAME_RATE = "frame-rate"; 377 378 /** 379 * A key describing the width (in pixels) of each tile of the content in a 380 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} track. The associated value is an integer. 381 * 382 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} on decoding instructions of such tracks. 383 * 384 * @see #KEY_TILE_HEIGHT 385 * @see #KEY_GRID_ROWS 386 * @see #KEY_GRID_COLUMNS 387 */ 388 public static final String KEY_TILE_WIDTH = "tile-width"; 389 390 /** 391 * A key describing the height (in pixels) of each tile of the content in a 392 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} track. The associated value is an integer. 393 * 394 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} on decoding instructions of such tracks. 395 * 396 * @see #KEY_TILE_WIDTH 397 * @see #KEY_GRID_ROWS 398 * @see #KEY_GRID_COLUMNS 399 */ 400 public static final String KEY_TILE_HEIGHT = "tile-height"; 401 402 /** 403 * A key describing the number of grid rows in the content in a 404 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} track. The associated value is an integer. 405 * 406 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} on decoding instructions of such tracks. 407 * 408 * @see #KEY_TILE_WIDTH 409 * @see #KEY_TILE_HEIGHT 410 * @see #KEY_GRID_COLUMNS 411 */ 412 public static final String KEY_GRID_ROWS = "grid-rows"; 413 414 /** 415 * A key describing the number of grid columns in the content in a 416 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} track. The associated value is an integer. 417 * 418 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} on decoding instructions of such tracks. 419 * 420 * @see #KEY_TILE_WIDTH 421 * @see #KEY_TILE_HEIGHT 422 * @see #KEY_GRID_ROWS 423 */ 424 public static final String KEY_GRID_COLUMNS = "grid-cols"; 425 426 /** 427 * A key describing the raw audio sample encoding/format. 428 * 429 * <p>The associated value is an integer, using one of the 430 * {@link AudioFormat}.ENCODING_PCM_ values.</p> 431 * 432 * <p>This is an optional key for audio decoders and encoders specifying the 433 * desired raw audio sample format during {@link MediaCodec#configure 434 * MediaCodec.configure(…)} call. Use {@link MediaCodec#getInputFormat 435 * MediaCodec.getInput}/{@link MediaCodec#getOutputFormat OutputFormat(…)} 436 * to confirm the actual format. For the PCM decoder this key specifies both 437 * input and output sample encodings.</p> 438 * 439 * <p>This key is also used by {@link MediaExtractor} to specify the sample 440 * format of audio data, if it is specified.</p> 441 * 442 * <p>If this key is missing, the raw audio sample format is signed 16-bit short.</p> 443 */ 444 public static final String KEY_PCM_ENCODING = "pcm-encoding"; 445 446 /** 447 * A key describing the capture rate of a video format in frames/sec. 448 * <p> 449 * When capture rate is different than the frame rate, it means that the 450 * video is acquired at a different rate than the playback, which produces 451 * slow motion or timelapse effect during playback. Application can use the 452 * value of this key to tell the relative speed ratio between capture and 453 * playback rates when the video was recorded. 454 * </p> 455 * <p> 456 * The associated value is an integer or a float. 457 * </p> 458 */ 459 public static final String KEY_CAPTURE_RATE = "capture-rate"; 460 461 /** 462 * A key for retrieving the slow-motion marker information associated with a video track. 463 * <p> 464 * The associated value is a ByteBuffer in {@link ByteOrder#BIG_ENDIAN} 465 * (networking order) of the following format: 466 * </p> 467 * <pre class="prettyprint"> 468 * float(32) playbackRate; 469 * unsigned int(32) numMarkers; 470 * for (i = 0;i < numMarkers; i++) { 471 * int(64) timestampUs; 472 * float(32) speedRatio; 473 * }</pre> 474 * The meaning of each field is as follows: 475 * <table border="1" width="90%" align="center" cellpadding="5"> 476 * <tbody> 477 * <tr> 478 * <td>playbackRate</td> 479 * <td>The frame rate at which the playback should happen (or the flattened 480 * clip should be).</td> 481 * </tr> 482 * <tr> 483 * <td>numMarkers</td> 484 * <td>The number of slow-motion markers that follows.</td> 485 * </tr> 486 * <tr> 487 * <td>timestampUs</td> 488 * <td>The starting point of a new segment.</td> 489 * </tr> 490 * <tr> 491 * <td>speedRatio</td> 492 * <td>The playback speed for that segment. The playback speed is a floating 493 * point number, indicating how fast the time progresses relative to that 494 * written in the container. (Eg. 4.0 means time goes 4x as fast, which 495 * makes 30fps become 120fps.)</td> 496 * </tr> 497 * </table> 498 * <p> 499 * The following constraints apply to the timestampUs of the markers: 500 * </p> 501 * <li>The timestampUs shall be monotonically increasing.</li> 502 * <li>The timestampUs shall fall within the time span of the video track.</li> 503 * <li>The first timestampUs should match that of the first video sample.</li> 504 */ 505 public static final String KEY_SLOW_MOTION_MARKERS = "slow-motion-markers"; 506 507 /** 508 * A key describing the frequency of key frames expressed in seconds between key frames. 509 * <p> 510 * This key is used by video encoders. 511 * A negative value means no key frames are requested after the first frame. 512 * A zero value means a stream containing all key frames is requested. 513 * <p class=note> 514 * Most video encoders will convert this value of the number of non-key-frames between 515 * key-frames, using the {@linkplain #KEY_FRAME_RATE frame rate} information; therefore, 516 * if the actual frame rate differs (e.g. input frames are dropped or the frame rate 517 * changes), the <strong>time interval</strong> between key frames will not be the 518 * configured value. 519 * <p> 520 * The associated value is an integer (or float since 521 * {@link android.os.Build.VERSION_CODES#N_MR1}). 522 */ 523 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 524 525 /** 526 * An optional key describing the period of intra refresh in frames. This is an 527 * optional parameter that applies only to video encoders. If encoder supports it 528 * ({@link MediaCodecInfo.CodecCapabilities#FEATURE_IntraRefresh}), the whole 529 * frame is completely refreshed after the specified period. Also for each frame, 530 * a fix subset of macroblocks must be intra coded which leads to more constant bitrate 531 * than inserting a key frame. This key is recommended for video streaming applications 532 * as it provides low-delay and good error-resilience. This key is ignored if the 533 * video encoder does not support the intra refresh feature. Use the output format to 534 * verify that this feature was enabled. 535 * The associated value is an integer. 536 */ 537 public static final String KEY_INTRA_REFRESH_PERIOD = "intra-refresh-period"; 538 539 /** 540 * An optional key describing whether encoders prepend headers to sync frames (e.g. 541 * SPS and PPS to IDR frames for H.264). This is an optional parameter that applies only 542 * to video encoders. A video encoder may not support this feature; the component will fail 543 * to configure in that case. For other components, this key is ignored. 544 * 545 * The value is an integer, with 1 indicating to prepend headers to every sync frames, 546 * or 0 otherwise. The default value is 0. 547 */ 548 public static final String KEY_PREPEND_HEADER_TO_SYNC_FRAMES = "prepend-sps-pps-to-idr-frames"; 549 550 /** 551 * A key describing the temporal layering schema. This is an optional parameter 552 * that applies only to video encoders. Use {@link MediaCodec#getOutputFormat} 553 * after {@link MediaCodec#configure configure} to query if the encoder supports 554 * the desired schema. Supported values are {@code webrtc.vp8.N-layer}, 555 * {@code android.generic.N}, {@code android.generic.N+M} and {@code none}, where 556 * {@code N} denotes the total number of non-bidirectional layers (which must be at least 1) 557 * and {@code M} denotes the total number of bidirectional layers (which must be non-negative). 558 * <p class=note>{@code android.generic.*} schemas have been added in {@link 559 * android.os.Build.VERSION_CODES#N_MR1}. 560 * <p> 561 * The encoder may support fewer temporal layers, in which case the output format 562 * will contain the configured schema. If the encoder does not support temporal 563 * layering, the output format will not have an entry with this key. 564 * The associated value is a string. 565 */ 566 public static final String KEY_TEMPORAL_LAYERING = "ts-schema"; 567 568 /** 569 * A key describing the stride of the video bytebuffer layout. 570 * Stride (or row increment) is the difference between the index of a pixel 571 * and that of the pixel directly underneath. For YUV 420 formats, the 572 * stride corresponds to the Y plane; the stride of the U and V planes can 573 * be calculated based on the color format, though it is generally undefined 574 * and depends on the device and release. 575 * The associated value is an integer, representing number of bytes. 576 */ 577 public static final String KEY_STRIDE = "stride"; 578 579 /** 580 * A key describing the plane height of a multi-planar (YUV) video bytebuffer layout. 581 * Slice height (or plane height/vertical stride) is the number of rows that must be skipped 582 * to get from the top of the Y plane to the top of the U plane in the bytebuffer. In essence 583 * the offset of the U plane is sliceHeight * stride. The height of the U/V planes 584 * can be calculated based on the color format, though it is generally undefined 585 * and depends on the device and release. 586 * The associated value is an integer, representing number of rows. 587 */ 588 public static final String KEY_SLICE_HEIGHT = "slice-height"; 589 590 /** 591 * Applies only when configuring a video encoder in "surface-input" mode. 592 * The associated value is a long and gives the time in microseconds 593 * after which the frame previously submitted to the encoder will be 594 * repeated (once) if no new frame became available since. 595 */ 596 public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER 597 = "repeat-previous-frame-after"; 598 599 /** 600 * Instruct the video encoder in "surface-input" mode to drop excessive 601 * frames from the source, so that the input frame rate to the encoder 602 * does not exceed the specified fps. 603 * 604 * The associated value is a float, representing the max frame rate to 605 * feed the encoder at. 606 * 607 */ 608 public static final String KEY_MAX_FPS_TO_ENCODER 609 = "max-fps-to-encoder"; 610 611 /** 612 * Instruct the video encoder in "surface-input" mode to limit the gap of 613 * timestamp between any two adjacent frames fed to the encoder to the 614 * specified amount (in micro-second). 615 * 616 * The associated value is a long int. When positive, it represents the max 617 * timestamp gap between two adjacent frames fed to the encoder. When negative, 618 * the absolute value represents a fixed timestamp gap between any two adjacent 619 * frames fed to the encoder. Note that this will also apply even when the 620 * original timestamp goes backward in time. Under normal conditions, such frames 621 * would be dropped and not sent to the encoder. 622 * 623 * The output timestamp will be restored to the original timestamp and will 624 * not be affected. 625 * 626 * This is used in some special scenarios where input frames arrive sparingly 627 * but it's undesirable to allocate more bits to any single frame, or when it's 628 * important to ensure all frames are captured (rather than captured in the 629 * correct order). 630 * 631 */ 632 public static final String KEY_MAX_PTS_GAP_TO_ENCODER 633 = "max-pts-gap-to-encoder"; 634 635 /** 636 * If specified when configuring a video encoder that's in "surface-input" 637 * mode, it will instruct the encoder to put the surface source in suspended 638 * state when it's connected. No video frames will be accepted until a resume 639 * operation (see {@link MediaCodec#PARAMETER_KEY_SUSPEND}), optionally with 640 * timestamp specified via {@link MediaCodec#PARAMETER_KEY_SUSPEND_TIME}, is 641 * received. 642 * 643 * The value is an integer, with 1 indicating to create with the surface 644 * source suspended, or 0 otherwise. The default value is 0. 645 * 646 * If this key is not set or set to 0, the surface source will accept buffers 647 * as soon as it's connected to the encoder (although they may not be encoded 648 * immediately). This key can be used when the client wants to prepare the 649 * encoder session in advance, but do not want to accept buffers immediately. 650 */ 651 public static final String KEY_CREATE_INPUT_SURFACE_SUSPENDED 652 = "create-input-buffers-suspended"; 653 654 /** 655 * If specified when configuring a video decoder rendering to a surface, 656 * causes the decoder to output "blank", i.e. black frames to the surface 657 * when stopped to clear out any previously displayed contents. 658 * The associated value is an integer of value 1. 659 */ 660 public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP 661 = "push-blank-buffers-on-shutdown"; 662 663 /** 664 * A key describing the duration (in microseconds) of the content. 665 * The associated value is a long. 666 */ 667 public static final String KEY_DURATION = "durationUs"; 668 669 /** 670 * A key mapping to a value of 1 if the content is AAC audio and 671 * audio frames are prefixed with an ADTS header. 672 * The associated value is an integer (0 or 1). 673 * This key is only supported when _decoding_ content, it cannot 674 * be used to configure an encoder to emit ADTS output. 675 */ 676 public static final String KEY_IS_ADTS = "is-adts"; 677 678 /** 679 * A key describing the channel composition of audio content. This mask 680 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 681 * The associated value is an integer. 682 */ 683 public static final String KEY_CHANNEL_MASK = "channel-mask"; 684 685 /** 686 * A key describing the maximum number of channels that can be output by an audio decoder. 687 * By default, the decoder will output the same number of channels as present in the encoded 688 * stream, if supported. Set this value to limit the number of output channels, and use 689 * the downmix information in the stream, if available. 690 * <p>Values larger than the number of channels in the content to decode behave like the number 691 * of channels in the content (if applicable), for instance passing 99 for a 5.1 audio stream 692 * behaves like passing 6. 693 * <p>This key is only used during decoding. 694 */ 695 public static final String KEY_MAX_OUTPUT_CHANNEL_COUNT = 696 "max-output-channel-count"; 697 698 /** 699 * A key describing the number of frames to trim from the start of the decoded audio stream. 700 * The associated value is an integer. 701 */ 702 public static final String KEY_ENCODER_DELAY = "encoder-delay"; 703 704 /** 705 * A key describing the number of frames to trim from the end of the decoded audio stream. 706 * The associated value is an integer. 707 */ 708 public static final String KEY_ENCODER_PADDING = "encoder-padding"; 709 710 /** 711 * A key describing the AAC profile to be used (AAC audio formats only). 712 * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. 713 */ 714 public static final String KEY_AAC_PROFILE = "aac-profile"; 715 716 /** 717 * A key describing the AAC SBR mode to be used (AAC audio formats only). 718 * The associated value is an integer and can be set to following values: 719 * <ul> 720 * <li>0 - no SBR should be applied</li> 721 * <li>1 - single rate SBR</li> 722 * <li>2 - double rate SBR</li> 723 * </ul> 724 * Note: If this key is not defined the default SRB mode for the desired AAC profile will 725 * be used. 726 * <p>This key is only used during encoding. 727 */ 728 public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode"; 729 730 /** 731 * A key describing the maximum number of channels that can be output by the AAC decoder. 732 * By default, the decoder will output the same number of channels as present in the encoded 733 * stream, if supported. Set this value to limit the number of output channels, and use 734 * the downmix information in the stream, if available. 735 * <p>Values larger than the number of channels in the content to decode are ignored. 736 * <p>This key is only used during decoding. 737 */ 738 public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count"; 739 740 /** 741 * A key describing the Target Reference Level (Target Loudness). 742 * <p>For normalizing loudness across program items, a gain is applied to the audio output so 743 * that the output loudness matches the Target Reference Level. The gain is derived as the 744 * difference between the Target Reference Level and the Program Reference Level (Program 745 * Loudness). The latter can be given in the bitstream and indicates the actual loudness value 746 * of the program item.</p> 747 * <p>The Target Reference Level controls loudness normalization for both MPEG-4 DRC and 748 * MPEG-D DRC. 749 * <p>The value is given as an integer value between 750 * 40 and 127, and is calculated as -4 * Target Reference Level in LKFS. 751 * Therefore, it represents the range of -10 to -31.75 LKFS. 752 * <p>For MPEG-4 DRC, a value of -1 switches off loudness normalization and DRC processing.</p> 753 * <p>For MPEG-D DRC, a value of -1 switches off loudness normalization only. For DRC processing 754 * options of MPEG-D DRC, see {@link #KEY_AAC_DRC_EFFECT_TYPE}</p> 755 * <p>The default value on mobile devices is 64 (-16 LKFS). 756 * <p>This key is only used during decoding. 757 */ 758 public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level"; 759 760 /** 761 * A key describing for selecting the DRC effect type for MPEG-D DRC. 762 * The supported values are defined in ISO/IEC 23003-4:2015 and are described as follows: 763 * <table> 764 * <tr><th>Value</th><th>Effect</th></tr> 765 * <tr><th>-1</th><th>Off</th></tr> 766 * <tr><th>0</th><th>None</th></tr> 767 * <tr><th>1</th><th>Late night</th></tr> 768 * <tr><th>2</th><th>Noisy environment</th></tr> 769 * <tr><th>3</th><th>Limited playback range</th></tr> 770 * <tr><th>4</th><th>Low playback level</th></tr> 771 * <tr><th>5</th><th>Dialog enhancement</th></tr> 772 * <tr><th>6</th><th>General compression</th></tr> 773 * </table> 774 * <p>The value -1 (Off) disables DRC processing, while loudness normalization may still be 775 * active and dependent on {@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}.<br> 776 * The value 0 (None) automatically enables DRC processing if necessary to prevent signal 777 * clipping<br> 778 * The value 6 (General compression) can be used for enabling MPEG-D DRC without particular 779 * DRC effect type request.<br> 780 * The default DRC effect type is 3 ("Limited playback range") on mobile devices. 781 * <p>This key is only used during decoding. 782 */ 783 public static final String KEY_AAC_DRC_EFFECT_TYPE = "aac-drc-effect-type"; 784 785 /** 786 * A key describing the target reference level that was assumed at the encoder for 787 * calculation of attenuation gains for clipping prevention. 788 * <p>If it is known, this information can be provided as an integer value between 789 * 0 and 127, which is calculated as -4 * Encoded Target Level in LKFS. 790 * If the Encoded Target Level is unknown, the value can be set to -1. 791 * <p>The default value is -1 (unknown). 792 * <p>The value is ignored when heavy compression (see {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}) 793 * or MPEG-D DRC is used. 794 * <p>This key is only used during decoding. 795 */ 796 public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level"; 797 798 /** 799 * A key describing the boost factor allowing to adapt the dynamics of the output to the 800 * actual listening requirements. This relies on DRC gain sequences that can be transmitted in 801 * the encoded bitstream to be able to reduce the dynamics of the output signal upon request. 802 * This factor enables the user to select how much of the gains are applied. 803 * <p>Positive gains (boost) and negative gains (attenuation, see 804 * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match 805 * to different use-cases. 806 * <p>Typically, attenuation gains are sent for loud signal segments, and boost gains are sent 807 * for soft signal segments. If the output is listened to in a noisy environment, for example, 808 * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments 809 * beyond the noise floor. But for listening late at night, the attenuation 810 * factor is used to enable the negative gains, to prevent loud signal from surprising 811 * the listener. In applications which generally need a low dynamic range, both the boost factor 812 * and the attenuation factor are used in order to enable all DRC gains. 813 * <p>In order to prevent clipping, it is also recommended to apply the attenuation gains 814 * in case of a downmix and/or loudness normalization to high target reference levels. 815 * <p>Both the boost and the attenuation factor parameters are given as integer values 816 * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply) 817 * to 1 (i.e. fully apply boost/attenuation gains respectively). 818 * <p>The default value is 127 (fully apply boost DRC gains). 819 * <p>This key is only used during decoding. 820 */ 821 public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level"; 822 823 /** 824 * A key describing the attenuation factor allowing to adapt the dynamics of the output to the 825 * actual listening requirements. 826 * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation 827 * factor and the value range. 828 * <p>The default value is 127 (fully apply attenuation DRC gains). 829 * <p>This key is only used during decoding. 830 */ 831 public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level"; 832 833 /** 834 * A key describing the selection of the heavy compression profile for MPEG-4 DRC. 835 * <p>Two separate DRC gain sequences can be transmitted in one bitstream: light compression 836 * and heavy compression. When selecting the application of the heavy compression, one of 837 * the sequences is selected: 838 * <ul> 839 * <li>0 enables light compression,</li> 840 * <li>1 enables heavy compression instead. 841 * </ul> 842 * Note that heavy compression doesn't offer the features of scaling of DRC gains 843 * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the 844 * boost and attenuation factors), and frequency-selective (multiband) DRC. 845 * Light compression usually contains clipping prevention for stereo downmixing while heavy 846 * compression, if additionally provided in the bitstream, is usually stronger, and contains 847 * clipping prevention for stereo and mono downmixing. 848 * <p>The default is 1 (heavy compression). 849 * <p>This key is only used during decoding. 850 */ 851 public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression"; 852 853 /** 854 * A key to retrieve the output loudness of a decoded bitstream. 855 * <p>If loudness normalization is active, the value corresponds to the Target Reference Level 856 * (see {@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}).<br> 857 * If loudness normalization is not active, the value corresponds to the loudness metadata 858 * given in the bitstream. 859 * <p>The value is retrieved with getInteger() and is given as an integer value between 0 and 860 * 231. It is calculated as -4 * Output Loudness in LKFS. Therefore, it represents the range of 861 * 0 to -57.75 LKFS. 862 * <p>A value of -1 indicates that no loudness metadata is present in the bitstream. 863 * <p>Loudness metadata can originate from MPEG-4 DRC or MPEG-D DRC. 864 * <p>This key is only used during decoding. 865 */ 866 public static final String KEY_AAC_DRC_OUTPUT_LOUDNESS = "aac-drc-output-loudness"; 867 868 /** 869 * A key describing the album mode for MPEG-D DRC as defined in ISO/IEC 23003-4. 870 * <p>The associated value is an integer and can be set to following values: 871 * <table> 872 * <tr><th>Value</th><th>Album Mode</th></tr> 873 * <tr><th>0</th><th>disabled</th></tr> 874 * <tr><th>1</th><th>enabled</th></tr> 875 * </table> 876 * <p>Disabled album mode leads to application of gain sequences for fading in and out, if 877 * provided in the bitstream. Enabled album mode makes use of dedicated album loudness 878 * information, if provided in the bitstream. 879 * <p>The default value is 0 (album mode disabled). 880 * <p>This key is only used during decoding. 881 */ 882 public static final String KEY_AAC_DRC_ALBUM_MODE = "aac-drc-album-mode"; 883 884 /** 885 * A key describing the FLAC compression level to be used (FLAC audio format only). 886 * The associated value is an integer ranging from 0 (fastest, least compression) 887 * to 8 (slowest, most compression). 888 */ 889 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 890 891 /** 892 * A key describing the MPEG-H stream profile-level indication. 893 * 894 * See ISO_IEC_23008-3;2019 MHADecoderConfigurationRecord mpegh3daProfileLevelIndication. 895 */ 896 public static final String KEY_MPEGH_PROFILE_LEVEL_INDICATION = 897 "mpegh-profile-level-indication"; 898 899 /** 900 * A key describing the MPEG-H stream compatible sets. 901 * 902 * See FDAmd_2 of ISO_IEC_23008-3;2019 MHAProfileAndLevelCompatibilitySetBox. 903 */ 904 public static final String KEY_MPEGH_COMPATIBLE_SETS = "mpegh-compatible-sets"; 905 906 /** 907 * A key describing the MPEG-H stream reference channel layout. 908 * 909 * See ISO_IEC_23008-3;2019 MHADecoderConfigurationRecord referenceChannelLayout 910 * and ISO_IEC_23001‐8 ChannelConfiguration value. 911 */ 912 public static final String KEY_MPEGH_REFERENCE_CHANNEL_LAYOUT = 913 "mpegh-reference-channel-layout"; 914 915 /** 916 * A key describing the encoding complexity. 917 * The associated value is an integer. These values are device and codec specific, 918 * but lower values generally result in faster and/or less power-hungry encoding. 919 * 920 * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange() 921 */ 922 public static final String KEY_COMPLEXITY = "complexity"; 923 924 /** 925 * A key describing the desired encoding quality. 926 * The associated value is an integer. This key is only supported for encoders 927 * that are configured in constant-quality mode. These values are device and 928 * codec specific, but lower values generally result in more efficient 929 * (smaller-sized) encoding. 930 * 931 * @see MediaCodecInfo.EncoderCapabilities#getQualityRange() 932 */ 933 public static final String KEY_QUALITY = "quality"; 934 935 /** 936 * A key describing the desired codec priority. 937 * <p> 938 * The associated value is an integer. Higher value means lower priority. 939 * <p> 940 * Currently, only two levels are supported:<br> 941 * 0: realtime priority - meaning that the codec shall support the given 942 * performance configuration (e.g. framerate) at realtime. This should 943 * only be used by media playback, capture, and possibly by realtime 944 * communication scenarios if best effort performance is not suitable.<br> 945 * 1: non-realtime priority (best effort). 946 * <p> 947 * This is a hint used at codec configuration and resource planning - to understand 948 * the realtime requirements of the application; however, due to the nature of 949 * media components, performance is not guaranteed. 950 * 951 */ 952 public static final String KEY_PRIORITY = "priority"; 953 954 /** 955 * A key describing the desired operating frame rate for video or sample rate for audio 956 * that the codec will need to operate at. 957 * <p> 958 * The associated value is an integer or a float representing frames-per-second or 959 * samples-per-second 960 * <p> 961 * This is used for cases like high-speed/slow-motion video capture, where the video encoder 962 * format contains the target playback rate (e.g. 30fps), but the component must be able to 963 * handle the high operating capture rate (e.g. 240fps). 964 * <p> 965 * This rate will be used by codec for resource planning and setting the operating points. 966 * 967 */ 968 public static final String KEY_OPERATING_RATE = "operating-rate"; 969 970 /** 971 * A key describing the desired profile to be used by an encoder. 972 * The associated value is an integer. 973 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 974 * This key is used as a hint, and is only supported for codecs 975 * that specify a profile. Note: Codecs are free to use all the available 976 * coding tools at the specified profile. 977 * 978 * @see MediaCodecInfo.CodecCapabilities#profileLevels 979 */ 980 public static final String KEY_PROFILE = "profile"; 981 982 /** 983 * A key describing the desired profile to be used by an encoder. 984 * The associated value is an integer. 985 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 986 * This key is used as a further hint when specifying a desired profile, 987 * and is only supported for codecs that specify a level. 988 * <p> 989 * This key is ignored if the {@link #KEY_PROFILE profile} is not specified. 990 * 991 * @see MediaCodecInfo.CodecCapabilities#profileLevels 992 */ 993 public static final String KEY_LEVEL = "level"; 994 995 /** 996 * An optional key describing the desired encoder latency in frames. This is an optional 997 * parameter that applies only to video encoders. If encoder supports it, it should ouput 998 * at least one output frame after being queued the specified number of frames. This key 999 * is ignored if the video encoder does not support the latency feature. Use the output 1000 * format to verify that this feature was enabled and the actual value used by the encoder. 1001 * <p> 1002 * If the key is not specified, the default latency will be implenmentation specific. 1003 * The associated value is an integer. 1004 */ 1005 public static final String KEY_LATENCY = "latency"; 1006 1007 /** 1008 * An optional key describing the maximum number of non-display-order coded frames. 1009 * This is an optional parameter that applies only to video encoders. Application should 1010 * check the value for this key in the output format to see if codec will produce 1011 * non-display-order coded frames. If encoder supports it, the output frames' order will be 1012 * different from the display order and each frame's display order could be retrived from 1013 * {@link MediaCodec.BufferInfo#presentationTimeUs}. Before API level 27, application may 1014 * receive non-display-order coded frames even though the application did not request it. 1015 * Note: Application should not rearrange the frames to display order before feeding them 1016 * to {@link MediaMuxer#writeSampleData}. 1017 * <p> 1018 * The default value is 0. 1019 */ 1020 public static final String KEY_OUTPUT_REORDER_DEPTH = "output-reorder-depth"; 1021 1022 /** 1023 * A key describing the desired clockwise rotation on an output surface. 1024 * This key is only used when the codec is configured using an output surface. 1025 * The associated value is an integer, representing degrees. Supported values 1026 * are 0, 90, 180 or 270. This is an optional field; if not specified, rotation 1027 * defaults to 0. 1028 * 1029 * @see MediaCodecInfo.CodecCapabilities#profileLevels 1030 */ 1031 public static final String KEY_ROTATION = "rotation-degrees"; 1032 1033 /** 1034 * A key describing the desired bitrate mode to be used by an encoder. 1035 * Constants are declared in {@link MediaCodecInfo.CodecCapabilities}. 1036 * 1037 * @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int) 1038 */ 1039 public static final String KEY_BITRATE_MODE = "bitrate-mode"; 1040 1041 /** 1042 * A key describing the maximum Quantization Parameter allowed for encoding video. 1043 * This key applies to all three video picture types (I, P, and B). 1044 * The value is used directly for picture type I; a per-mime formula is used 1045 * to calculate the value for the remaining picture types. 1046 * 1047 * This calculation can be avoided by directly specifying values for each picture type 1048 * using the type-specific keys {@link #KEY_VIDEO_QP_I_MAX}, {@link #KEY_VIDEO_QP_P_MAX}, 1049 * and {@link #KEY_VIDEO_QP_B_MAX}. 1050 * 1051 * The associated value is an integer. 1052 */ 1053 public static final String KEY_VIDEO_QP_MAX = "video-qp-max"; 1054 1055 /** 1056 * A key describing the minimum Quantization Parameter allowed for encoding video. 1057 * This key applies to all three video frame types (I, P, and B). 1058 * The value is used directly for picture type I; a per-mime formula is used 1059 * to calculate the value for the remaining picture types. 1060 * 1061 * This calculation can be avoided by directly specifying values for each picture type 1062 * using the type-specific keys {@link #KEY_VIDEO_QP_I_MIN}, {@link #KEY_VIDEO_QP_P_MIN}, 1063 * and {@link #KEY_VIDEO_QP_B_MIN}. 1064 * 1065 * The associated value is an integer. 1066 */ 1067 public static final String KEY_VIDEO_QP_MIN = "video-qp-min"; 1068 1069 /** 1070 * A key describing the maximum Quantization Parameter allowed for encoding video. 1071 * This value applies to video I-frames. 1072 * 1073 * The associated value is an integer. 1074 */ 1075 public static final String KEY_VIDEO_QP_I_MAX = "video-qp-i-max"; 1076 1077 /** 1078 * A key describing the minimum Quantization Parameter allowed for encoding video. 1079 * This value applies to video I-frames. 1080 * 1081 * The associated value is an integer. 1082 */ 1083 public static final String KEY_VIDEO_QP_I_MIN = "video-qp-i-min"; 1084 1085 /** 1086 * A key describing the maximum Quantization Parameter allowed for encoding video. 1087 * This value applies to video P-frames. 1088 * 1089 * The associated value is an integer. 1090 */ 1091 public static final String KEY_VIDEO_QP_P_MAX = "video-qp-p-max"; 1092 1093 /** 1094 * A key describing the minimum Quantization Parameter allowed for encoding video. 1095 * This value applies to video P-frames. 1096 * 1097 * The associated value is an integer. 1098 */ 1099 public static final String KEY_VIDEO_QP_P_MIN = "video-qp-p-min"; 1100 1101 /** 1102 * A key describing the maximum Quantization Parameter allowed for encoding video. 1103 * This value applies to video B-frames. 1104 * 1105 * The associated value is an integer. 1106 */ 1107 public static final String KEY_VIDEO_QP_B_MAX = "video-qp-b-max"; 1108 1109 /** 1110 * A key describing the minimum Quantization Parameter allowed for encoding video. 1111 * This value applies to video B-frames. 1112 * 1113 * The associated value is an integer. 1114 */ 1115 public static final String KEY_VIDEO_QP_B_MIN = "video-qp-b-min"; 1116 1117 /** 1118 * A key describing the audio session ID of the AudioTrack associated 1119 * to a tunneled video codec. 1120 * The associated value is an integer. 1121 * 1122 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 1123 */ 1124 public static final String KEY_AUDIO_SESSION_ID = "audio-session-id"; 1125 1126 /** 1127 * A key describing the audio hardware sync ID of the AudioTrack associated 1128 * to a tunneled video codec. The associated value is an integer. 1129 * 1130 * @hide 1131 * 1132 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 1133 * @see AudioManager#getAudioHwSyncForSession 1134 */ 1135 public static final String KEY_AUDIO_HW_SYNC = "audio-hw-sync"; 1136 1137 /** 1138 * A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true 1139 * are considered when automatically selecting a track without specific user 1140 * choice, based on the current locale. 1141 * This is currently only used for subtitle tracks, when the user selected 1142 * 'Default' for the captioning locale. 1143 * The associated value is an integer, where non-0 means TRUE. This is an optional 1144 * field; if not specified, AUTOSELECT defaults to TRUE. 1145 */ 1146 public static final String KEY_IS_AUTOSELECT = "is-autoselect"; 1147 1148 /** 1149 * A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is 1150 * selected in the absence of a specific user choice. 1151 * This is currently used in two scenarios: 1152 * 1) for subtitle tracks, when the user selected 'Default' for the captioning locale. 1153 * 2) for a {@link #MIMETYPE_IMAGE_ANDROID_HEIC} track, indicating the image is the 1154 * primary item in the file. 1155 1156 * The associated value is an integer, where non-0 means TRUE. This is an optional 1157 * field; if not specified, DEFAULT is considered to be FALSE. 1158 */ 1159 public static final String KEY_IS_DEFAULT = "is-default"; 1160 1161 /** 1162 * A key for the FORCED field for subtitle tracks. True if it is a 1163 * forced subtitle track. Forced subtitle tracks are essential for the 1164 * content and are shown even when the user turns off Captions. They 1165 * are used for example to translate foreign/alien dialogs or signs. 1166 * The associated value is an integer, where non-0 means TRUE. This is an 1167 * optional field; if not specified, FORCED defaults to FALSE. 1168 */ 1169 public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle"; 1170 1171 /** 1172 * A key describing the number of haptic channels in an audio format. 1173 * The associated value is an integer. 1174 */ 1175 public static final String KEY_HAPTIC_CHANNEL_COUNT = "haptic-channel-count"; 1176 1177 /** @hide */ 1178 public static final String KEY_IS_TIMED_TEXT = "is-timed-text"; 1179 1180 // The following color aspect values must be in sync with the ones in HardwareAPI.h. 1181 /** 1182 * An optional key describing the color primaries, white point and 1183 * luminance factors for video content. 1184 * 1185 * The associated value is an integer: 0 if unspecified, or one of the 1186 * COLOR_STANDARD_ values. 1187 */ 1188 public static final String KEY_COLOR_STANDARD = "color-standard"; 1189 1190 /** BT.709 color chromacity coordinates with KR = 0.2126, KB = 0.0722. */ 1191 public static final int COLOR_STANDARD_BT709 = 1; 1192 1193 /** BT.601 625 color chromacity coordinates with KR = 0.299, KB = 0.114. */ 1194 public static final int COLOR_STANDARD_BT601_PAL = 2; 1195 1196 /** BT.601 525 color chromacity coordinates with KR = 0.299, KB = 0.114. */ 1197 public static final int COLOR_STANDARD_BT601_NTSC = 4; 1198 1199 /** BT.2020 color chromacity coordinates with KR = 0.2627, KB = 0.0593. */ 1200 public static final int COLOR_STANDARD_BT2020 = 6; 1201 1202 /** @hide */ 1203 @IntDef({ 1204 COLOR_STANDARD_BT709, 1205 COLOR_STANDARD_BT601_PAL, 1206 COLOR_STANDARD_BT601_NTSC, 1207 COLOR_STANDARD_BT2020, 1208 }) 1209 @Retention(RetentionPolicy.SOURCE) 1210 public @interface ColorStandard {} 1211 1212 /** 1213 * An optional key describing the opto-electronic transfer function used 1214 * for the video content. 1215 * 1216 * The associated value is an integer: 0 if unspecified, or one of the 1217 * COLOR_TRANSFER_ values. 1218 */ 1219 public static final String KEY_COLOR_TRANSFER = "color-transfer"; 1220 1221 /** Linear transfer characteristic curve. */ 1222 public static final int COLOR_TRANSFER_LINEAR = 1; 1223 1224 /** SMPTE 170M transfer characteristic curve used by BT.601/BT.709/BT.2020. This is the curve 1225 * used by most non-HDR video content. */ 1226 public static final int COLOR_TRANSFER_SDR_VIDEO = 3; 1227 1228 /** SMPTE ST 2084 transfer function. This is used by some HDR video content. */ 1229 public static final int COLOR_TRANSFER_ST2084 = 6; 1230 1231 /** ARIB STD-B67 hybrid-log-gamma transfer function. This is used by some HDR video content. */ 1232 public static final int COLOR_TRANSFER_HLG = 7; 1233 1234 /** @hide */ 1235 @IntDef({ 1236 COLOR_TRANSFER_LINEAR, 1237 COLOR_TRANSFER_SDR_VIDEO, 1238 COLOR_TRANSFER_ST2084, 1239 COLOR_TRANSFER_HLG, 1240 }) 1241 @Retention(RetentionPolicy.SOURCE) 1242 public @interface ColorTransfer {} 1243 1244 /** 1245 * An optional key describing the range of the component values of the video content. 1246 * 1247 * The associated value is an integer: 0 if unspecified, or one of the 1248 * COLOR_RANGE_ values. 1249 */ 1250 public static final String KEY_COLOR_RANGE = "color-range"; 1251 1252 /** Limited range. Y component values range from 16 to 235 for 8-bit content. 1253 * Cr, Cy values range from 16 to 240 for 8-bit content. 1254 * This is the default for video content. */ 1255 public static final int COLOR_RANGE_LIMITED = 2; 1256 1257 /** Full range. Y, Cr and Cb component values range from 0 to 255 for 8-bit content. */ 1258 public static final int COLOR_RANGE_FULL = 1; 1259 1260 /** @hide */ 1261 @IntDef({ 1262 COLOR_RANGE_LIMITED, 1263 COLOR_RANGE_FULL, 1264 }) 1265 @Retention(RetentionPolicy.SOURCE) 1266 public @interface ColorRange {} 1267 1268 /** 1269 * An optional key describing the static metadata of HDR (high-dynamic-range) video content. 1270 * 1271 * The associated value is a ByteBuffer. This buffer contains the raw contents of the 1272 * Static Metadata Descriptor (including the descriptor ID) of an HDMI Dynamic Range and 1273 * Mastering InfoFrame as defined by CTA-861.3. This key must be provided to video decoders 1274 * for HDR video content unless this information is contained in the bitstream and the video 1275 * decoder supports an HDR-capable profile. This key must be provided to video encoders for 1276 * HDR video content. 1277 */ 1278 public static final String KEY_HDR_STATIC_INFO = "hdr-static-info"; 1279 1280 /** 1281 * An optional key describing the HDR10+ metadata of the video content. 1282 * 1283 * The associated value is a ByteBuffer containing HDR10+ metadata conforming to the 1284 * user_data_registered_itu_t_t35() syntax of SEI message for ST 2094-40. This key will 1285 * be present on: 1286 *<p> 1287 * - The formats of output buffers of a decoder configured for HDR10+ profiles (such as 1288 * {@link MediaCodecInfo.CodecProfileLevel#VP9Profile2HDR10Plus}, {@link 1289 * MediaCodecInfo.CodecProfileLevel#VP9Profile3HDR10Plus} or {@link 1290 * MediaCodecInfo.CodecProfileLevel#HEVCProfileMain10HDR10Plus}), or 1291 *<p> 1292 * - The formats of output buffers of an encoder configured for an HDR10+ profiles that 1293 * uses out-of-band metadata (such as {@link 1294 * MediaCodecInfo.CodecProfileLevel#VP9Profile2HDR10Plus} or {@link 1295 * MediaCodecInfo.CodecProfileLevel#VP9Profile3HDR10Plus}). 1296 * 1297 * @see MediaCodec#PARAMETER_KEY_HDR10_PLUS_INFO 1298 */ 1299 public static final String KEY_HDR10_PLUS_INFO = "hdr10-plus-info"; 1300 1301 /** 1302 * An optional key describing the opto-electronic transfer function 1303 * requested for the output video content. 1304 * 1305 * The associated value is an integer: 0 if unspecified, or one of the 1306 * COLOR_TRANSFER_ values. When unspecified the component will not touch the 1307 * video content; otherwise the component will tone-map the raw video frame 1308 * to match the requested transfer function. 1309 * 1310 * After configure, component's input format will contain this key to note 1311 * whether the request is supported or not. If the value in the input format 1312 * is the same as the requested value, the request is supported. The value 1313 * is set to 0 if unsupported. 1314 */ 1315 public static final String KEY_COLOR_TRANSFER_REQUEST = "color-transfer-request"; 1316 1317 /** 1318 * A key describing a unique ID for the content of a media track. 1319 * 1320 * <p>This key is used by {@link MediaExtractor}. Some extractors provide multiple encodings 1321 * of the same track (e.g. float audio tracks for FLAC and WAV may be expressed as two 1322 * tracks via MediaExtractor: a normal PCM track for backward compatibility, and a float PCM 1323 * track for added fidelity. Similarly, Dolby Vision extractor may provide a baseline SDR 1324 * version of a DV track.) This key can be used to identify which MediaExtractor tracks refer 1325 * to the same underlying content. 1326 * </p> 1327 * 1328 * The associated value is an integer. 1329 */ 1330 public static final String KEY_TRACK_ID = "track-id"; 1331 1332 /** 1333 * A key describing the system id of the conditional access system used to scramble 1334 * a media track. 1335 * <p> 1336 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 1337 * access system, regardless of the presence of a valid {@link MediaCas} object. 1338 * <p> 1339 * The associated value is an integer. 1340 * @hide 1341 */ 1342 public static final String KEY_CA_SYSTEM_ID = "ca-system-id"; 1343 1344 /** 1345 * A key describing the {@link MediaCas.Session} object associated with a media track. 1346 * <p> 1347 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 1348 * access system, after it receives a valid {@link MediaCas} object. 1349 * <p> 1350 * The associated value is a ByteBuffer. 1351 * @hide 1352 */ 1353 public static final String KEY_CA_SESSION_ID = "ca-session-id"; 1354 1355 /** 1356 * A key describing the private data in the CA_descriptor associated with a media track. 1357 * <p> 1358 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 1359 * access system, before it receives a valid {@link MediaCas} object. 1360 * <p> 1361 * The associated value is a ByteBuffer. 1362 * @hide 1363 */ 1364 public static final String KEY_CA_PRIVATE_DATA = "ca-private-data"; 1365 1366 /** 1367 * A key describing the maximum number of B frames between I or P frames, 1368 * to be used by a video encoder. 1369 * The associated value is an integer. The default value is 0, which means 1370 * that no B frames are allowed. Note that non-zero value does not guarantee 1371 * B frames; it's up to the encoder to decide. 1372 */ 1373 public static final String KEY_MAX_B_FRAMES = "max-bframes"; 1374 1375 /** 1376 * A key for applications to opt out of allowing 1377 * a Surface to discard undisplayed/unconsumed frames 1378 * as means to catch up after falling behind. 1379 * This value is an integer. 1380 * The value 0 indicates the surface is not allowed to drop frames. 1381 * The value 1 indicates the surface is allowed to drop frames. 1382 * 1383 * {@link MediaCodec} describes the semantics. 1384 */ 1385 public static final String KEY_ALLOW_FRAME_DROP = "allow-frame-drop"; 1386 MediaFormat(@onNull Map<String, Object> map)1387 /* package private */ MediaFormat(@NonNull Map<String, Object> map) { 1388 mMap = map; 1389 } 1390 1391 /** 1392 * Creates an empty MediaFormat 1393 */ MediaFormat()1394 public MediaFormat() { 1395 mMap = new HashMap(); 1396 } 1397 1398 @UnsupportedAppUsage getMap()1399 /* package private */ Map<String, Object> getMap() { 1400 return mMap; 1401 } 1402 1403 /** 1404 * Returns true iff a key of the given name exists in the format. 1405 */ containsKey(@onNull String name)1406 public final boolean containsKey(@NonNull String name) { 1407 return mMap.containsKey(name); 1408 } 1409 1410 /** 1411 * Returns true iff a feature of the given name exists in the format. 1412 */ containsFeature(@onNull String name)1413 public final boolean containsFeature(@NonNull String name) { 1414 return mMap.containsKey(KEY_FEATURE_ + name); 1415 } 1416 1417 public static final int TYPE_NULL = 0; 1418 public static final int TYPE_INTEGER = 1; 1419 public static final int TYPE_LONG = 2; 1420 public static final int TYPE_FLOAT = 3; 1421 public static final int TYPE_STRING = 4; 1422 public static final int TYPE_BYTE_BUFFER = 5; 1423 1424 /** @hide */ 1425 @IntDef({ 1426 TYPE_NULL, 1427 TYPE_INTEGER, 1428 TYPE_LONG, 1429 TYPE_FLOAT, 1430 TYPE_STRING, 1431 TYPE_BYTE_BUFFER 1432 }) 1433 @Retention(RetentionPolicy.SOURCE) 1434 public @interface Type {} 1435 1436 /** 1437 * Returns the value type for a key. If the key does not exist, it returns TYPE_NULL. 1438 */ getValueTypeForKey(@onNull String name)1439 public final @Type int getValueTypeForKey(@NonNull String name) { 1440 Object value = mMap.get(name); 1441 if (value == null) { 1442 return TYPE_NULL; 1443 } else if (value instanceof Integer) { 1444 return TYPE_INTEGER; 1445 } else if (value instanceof Long) { 1446 return TYPE_LONG; 1447 } else if (value instanceof Float) { 1448 return TYPE_FLOAT; 1449 } else if (value instanceof String) { 1450 return TYPE_STRING; 1451 } else if (value instanceof ByteBuffer) { 1452 return TYPE_BYTE_BUFFER; 1453 } 1454 throw new RuntimeException("invalid value for key"); 1455 } 1456 1457 /** 1458 * A key prefix used together with a {@link MediaCodecInfo.CodecCapabilities} 1459 * feature name describing a required or optional feature for a codec capabilities 1460 * query. 1461 * The associated value is an integer, where non-0 value means the feature is 1462 * requested to be present, while 0 value means the feature is requested to be not 1463 * present. 1464 * @see MediaCodecList#findDecoderForFormat 1465 * @see MediaCodecList#findEncoderForFormat 1466 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 1467 * 1468 * @hide 1469 */ 1470 public static final String KEY_FEATURE_ = "feature-"; 1471 1472 /** 1473 * Returns the value of a numeric key. This is provided as a convenience method for keys 1474 * that may take multiple numeric types, such as {@link #KEY_FRAME_RATE}, or {@link 1475 * #KEY_I_FRAME_INTERVAL}. 1476 * 1477 * @return null if the key does not exist or the stored value for the key is null 1478 * @throws ClassCastException if the stored value for the key is ByteBuffer or String 1479 */ getNumber(@onNull String name)1480 public final @Nullable Number getNumber(@NonNull String name) { 1481 return (Number) mMap.get(name); 1482 } 1483 1484 /** 1485 * Returns the value of a numeric key, or the default value if the key is missing. 1486 * 1487 * @return defaultValue if the key does not exist or the stored value for the key is null 1488 * @throws ClassCastException if the stored value for the key is ByteBuffer or String 1489 */ getNumber(@onNull String name, @NonNull Number defaultValue)1490 public final @NonNull Number getNumber(@NonNull String name, @NonNull Number defaultValue) { 1491 Number ret = getNumber(name); 1492 return ret == null ? defaultValue : ret; 1493 } 1494 1495 /** 1496 * Returns the value of an integer key. 1497 * 1498 * @throws NullPointerException if the key does not exist or the stored value for the key is 1499 * null 1500 * @throws ClassCastException if the stored value for the key is long, float, ByteBuffer or 1501 * String 1502 */ getInteger(@onNull String name)1503 public final int getInteger(@NonNull String name) { 1504 return (int) mMap.get(name); 1505 } 1506 1507 /** 1508 * Returns the value of an integer key, or the default value if the key is missing. 1509 * 1510 * @return defaultValue if the key does not exist or the stored value for the key is null 1511 * @throws ClassCastException if the stored value for the key is long, float, ByteBuffer or 1512 * String 1513 */ getInteger(@onNull String name, int defaultValue)1514 public final int getInteger(@NonNull String name, int defaultValue) { 1515 try { 1516 return getInteger(name); 1517 } catch (NullPointerException e) { 1518 /* no such field or field is null */ 1519 return defaultValue; 1520 } 1521 } 1522 1523 /** 1524 * Returns the value of a long key. 1525 * 1526 * @throws NullPointerException if the key does not exist or the stored value for the key is 1527 * null 1528 * @throws ClassCastException if the stored value for the key is int, float, ByteBuffer or 1529 * String 1530 */ getLong(@onNull String name)1531 public final long getLong(@NonNull String name) { 1532 return (long) mMap.get(name); 1533 } 1534 1535 /** 1536 * Returns the value of a long key, or the default value if the key is missing. 1537 * 1538 * @return defaultValue if the key does not exist or the stored value for the key is null 1539 * @throws ClassCastException if the stored value for the key is int, float, ByteBuffer or 1540 * String 1541 */ getLong(@onNull String name, long defaultValue)1542 public final long getLong(@NonNull String name, long defaultValue) { 1543 try { 1544 return getLong(name); 1545 } catch (NullPointerException e) { 1546 /* no such field or field is null */ 1547 return defaultValue; 1548 } 1549 } 1550 1551 /** 1552 * Returns the value of a float key. 1553 * 1554 * @throws NullPointerException if the key does not exist or the stored value for the key is 1555 * null 1556 * @throws ClassCastException if the stored value for the key is int, long, ByteBuffer or 1557 * String 1558 */ getFloat(@onNull String name)1559 public final float getFloat(@NonNull String name) { 1560 return (float) mMap.get(name); 1561 } 1562 1563 /** 1564 * Returns the value of a float key, or the default value if the key is missing. 1565 * 1566 * @return defaultValue if the key does not exist or the stored value for the key is null 1567 * @throws ClassCastException if the stored value for the key is int, long, ByteBuffer or 1568 * String 1569 */ getFloat(@onNull String name, float defaultValue)1570 public final float getFloat(@NonNull String name, float defaultValue) { 1571 Object value = mMap.get(name); 1572 return value != null ? (float) value : defaultValue; 1573 } 1574 1575 /** 1576 * Returns the value of a string key. 1577 * 1578 * @return null if the key does not exist or the stored value for the key is null 1579 * @throws ClassCastException if the stored value for the key is int, long, float or ByteBuffer 1580 */ getString(@onNull String name)1581 public final @Nullable String getString(@NonNull String name) { 1582 return (String)mMap.get(name); 1583 } 1584 1585 /** 1586 * Returns the value of a string key, or the default value if the key is missing. 1587 * 1588 * @return defaultValue if the key does not exist or the stored value for the key is null 1589 * @throws ClassCastException if the stored value for the key is int, long, float or ByteBuffer 1590 */ getString(@onNull String name, @NonNull String defaultValue)1591 public final @NonNull String getString(@NonNull String name, @NonNull String defaultValue) { 1592 String ret = getString(name); 1593 return ret == null ? defaultValue : ret; 1594 } 1595 1596 /** 1597 * Returns the value of a ByteBuffer key. 1598 * 1599 * @return null if the key does not exist or the stored value for the key is null 1600 * @throws ClassCastException if the stored value for the key is int, long, float or String 1601 */ getByteBuffer(@onNull String name)1602 public final @Nullable ByteBuffer getByteBuffer(@NonNull String name) { 1603 return (ByteBuffer)mMap.get(name); 1604 } 1605 1606 /** 1607 * Returns the value of a ByteBuffer key, or the default value if the key is missing. 1608 * 1609 * @return defaultValue if the key does not exist or the stored value for the key is null 1610 * @throws ClassCastException if the stored value for the key is int, long, float or String 1611 */ getByteBuffer( @onNull String name, @NonNull ByteBuffer defaultValue)1612 public final @NonNull ByteBuffer getByteBuffer( 1613 @NonNull String name, @NonNull ByteBuffer defaultValue) { 1614 ByteBuffer ret = getByteBuffer(name); 1615 return ret == null ? defaultValue : ret; 1616 } 1617 1618 /** 1619 * Returns whether a feature is to be enabled ({@code true}) or disabled 1620 * ({@code false}). 1621 * 1622 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 1623 * 1624 * @throws IllegalArgumentException if the feature was neither set to be enabled 1625 * nor to be disabled. 1626 */ getFeatureEnabled(@onNull String feature)1627 public boolean getFeatureEnabled(@NonNull String feature) { 1628 Integer enabled = (Integer)mMap.get(KEY_FEATURE_ + feature); 1629 if (enabled == null) { 1630 throw new IllegalArgumentException("feature is not specified"); 1631 } 1632 return enabled != 0; 1633 } 1634 1635 /** 1636 * Sets the value of an integer key. 1637 */ setInteger(@onNull String name, int value)1638 public final void setInteger(@NonNull String name, int value) { 1639 mMap.put(name, value); 1640 } 1641 1642 /** 1643 * Sets the value of a long key. 1644 */ setLong(@onNull String name, long value)1645 public final void setLong(@NonNull String name, long value) { 1646 mMap.put(name, value); 1647 } 1648 1649 /** 1650 * Sets the value of a float key. 1651 */ setFloat(@onNull String name, float value)1652 public final void setFloat(@NonNull String name, float value) { 1653 mMap.put(name, value); 1654 } 1655 1656 /** 1657 * Sets the value of a string key. 1658 * <p> 1659 * If value is {@code null}, it sets a null value that behaves similarly to a missing key. 1660 * This could be used prior to API level {@link android os.Build.VERSION_CODES#Q} to effectively 1661 * remove a key. 1662 */ setString(@onNull String name, @Nullable String value)1663 public final void setString(@NonNull String name, @Nullable String value) { 1664 mMap.put(name, value); 1665 } 1666 1667 /** 1668 * Sets the value of a ByteBuffer key. 1669 * <p> 1670 * If value is {@code null}, it sets a null value that behaves similarly to a missing key. 1671 * This could be used prior to API level {@link android os.Build.VERSION_CODES#Q} to effectively 1672 * remove a key. 1673 */ setByteBuffer(@onNull String name, @Nullable ByteBuffer bytes)1674 public final void setByteBuffer(@NonNull String name, @Nullable ByteBuffer bytes) { 1675 mMap.put(name, bytes); 1676 } 1677 1678 /** 1679 * Removes a value of a given key if present. Has no effect if the key is not present. 1680 */ removeKey(@onNull String name)1681 public final void removeKey(@NonNull String name) { 1682 // exclude feature mappings 1683 if (!name.startsWith(KEY_FEATURE_)) { 1684 mMap.remove(name); 1685 } 1686 } 1687 1688 /** 1689 * Removes a given feature setting if present. Has no effect if the feature setting is not 1690 * present. 1691 */ removeFeature(@onNull String name)1692 public final void removeFeature(@NonNull String name) { 1693 mMap.remove(KEY_FEATURE_ + name); 1694 } 1695 1696 /** 1697 * A Partial set view for a portion of the keys in a MediaFormat object. 1698 * 1699 * This class is needed as we want to return a portion of the actual format keys in getKeys() 1700 * and another portion of the keys in getFeatures(), and still allow the view properties. 1701 */ 1702 private abstract class FilteredMappedKeySet extends AbstractSet<String> { 1703 private Set<String> mKeys; 1704 1705 // Returns true if this set should include this key keepKey(String key)1706 abstract protected boolean keepKey(String key); 1707 1708 // Maps a key from the underlying key set into its new value in this key set mapKeyToItem(String key)1709 abstract protected String mapKeyToItem(String key); 1710 1711 // Maps a key from this key set into its original value in the underlying key set mapItemToKey(String item)1712 abstract protected String mapItemToKey(String item); 1713 FilteredMappedKeySet()1714 public FilteredMappedKeySet() { 1715 mKeys = mMap.keySet(); 1716 } 1717 1718 // speed up contains and remove from abstract implementation (that would iterate 1719 // over each element) 1720 @Override contains(Object o)1721 public boolean contains(Object o) { 1722 if (o instanceof String) { 1723 String key = mapItemToKey((String)o); 1724 return keepKey(key) && mKeys.contains(key); 1725 } 1726 return false; 1727 } 1728 1729 @Override remove(Object o)1730 public boolean remove(Object o) { 1731 if (o instanceof String) { 1732 String key = mapItemToKey((String)o); 1733 if (keepKey(key) && mKeys.remove(key)) { 1734 mMap.remove(key); 1735 return true; 1736 } 1737 } 1738 return false; 1739 } 1740 1741 private class KeyIterator implements Iterator<String> { 1742 Iterator<String> mIterator; 1743 String mLast; 1744 KeyIterator()1745 public KeyIterator() { 1746 // We must create a copy of the filtered stream, as remove operation has to modify 1747 // the underlying data structure (mMap), so the iterator's operation is undefined. 1748 // Use a list as it is likely less memory consuming than the other alternative: set. 1749 mIterator = 1750 mKeys.stream().filter(k -> keepKey(k)).collect(Collectors.toList()).iterator(); 1751 } 1752 1753 @Override hasNext()1754 public boolean hasNext() { 1755 return mIterator.hasNext(); 1756 } 1757 1758 @Override next()1759 public String next() { 1760 mLast = mIterator.next(); 1761 return mapKeyToItem(mLast); 1762 } 1763 1764 @Override remove()1765 public void remove() { 1766 mIterator.remove(); 1767 mMap.remove(mLast); 1768 } 1769 } 1770 1771 @Override iterator()1772 public Iterator<String> iterator() { 1773 return new KeyIterator(); 1774 } 1775 1776 @Override size()1777 public int size() { 1778 return (int) mKeys.stream().filter(this::keepKey).count(); 1779 } 1780 } 1781 1782 /** 1783 * A Partial set view for a portion of the keys in a MediaFormat object for keys that 1784 * don't start with a prefix, such as "feature-" 1785 */ 1786 private class UnprefixedKeySet extends FilteredMappedKeySet { 1787 private String mPrefix; 1788 UnprefixedKeySet(String prefix)1789 public UnprefixedKeySet(String prefix) { 1790 super(); 1791 mPrefix = prefix; 1792 } 1793 keepKey(String key)1794 protected boolean keepKey(String key) { 1795 return !key.startsWith(mPrefix); 1796 } 1797 mapKeyToItem(String key)1798 protected String mapKeyToItem(String key) { 1799 return key; 1800 } 1801 mapItemToKey(String item)1802 protected String mapItemToKey(String item) { 1803 return item; 1804 } 1805 } 1806 1807 /** 1808 * A Partial set view for a portion of the keys in a MediaFormat object for keys that 1809 * start with a prefix, such as "feature-", with the prefix removed 1810 */ 1811 private class PrefixedKeySetWithPrefixRemoved extends FilteredMappedKeySet { 1812 private String mPrefix; 1813 private int mPrefixLength; 1814 PrefixedKeySetWithPrefixRemoved(String prefix)1815 public PrefixedKeySetWithPrefixRemoved(String prefix) { 1816 super(); 1817 mPrefix = prefix; 1818 mPrefixLength = prefix.length(); 1819 } 1820 keepKey(String key)1821 protected boolean keepKey(String key) { 1822 return key.startsWith(mPrefix); 1823 } 1824 mapKeyToItem(String key)1825 protected String mapKeyToItem(String key) { 1826 return key.substring(mPrefixLength); 1827 } 1828 mapItemToKey(String item)1829 protected String mapItemToKey(String item) { 1830 return mPrefix + item; 1831 } 1832 } 1833 1834 1835 /** 1836 * Returns a {@link java.util.Set Set} view of the keys contained in this MediaFormat. 1837 * 1838 * The set is backed by the MediaFormat object, so changes to the format are reflected in the 1839 * set, and vice-versa. If the format is modified while an iteration over the set is in progress 1840 * (except through the iterator's own remove operation), the results of the iteration are 1841 * undefined. The set supports element removal, which removes the corresponding mapping from the 1842 * format, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. 1843 * It does not support the add or addAll operations. 1844 */ getKeys()1845 public final @NonNull java.util.Set<String> getKeys() { 1846 return new UnprefixedKeySet(KEY_FEATURE_); 1847 } 1848 1849 /** 1850 * Returns a {@link java.util.Set Set} view of the features contained in this MediaFormat. 1851 * 1852 * The set is backed by the MediaFormat object, so changes to the format are reflected in the 1853 * set, and vice-versa. If the format is modified while an iteration over the set is in progress 1854 * (except through the iterator's own remove operation), the results of the iteration are 1855 * undefined. The set supports element removal, which removes the corresponding mapping from the 1856 * format, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. 1857 * It does not support the add or addAll operations. 1858 */ getFeatures()1859 public final @NonNull java.util.Set<String> getFeatures() { 1860 return new PrefixedKeySetWithPrefixRemoved(KEY_FEATURE_); 1861 } 1862 1863 /** 1864 * Create a copy of a media format object. 1865 */ MediaFormat(@onNull MediaFormat other)1866 public MediaFormat(@NonNull MediaFormat other) { 1867 this(); 1868 mMap.putAll(other.mMap); 1869 } 1870 1871 /** 1872 * Sets whether a feature is to be enabled ({@code true}) or disabled 1873 * ({@code false}). 1874 * 1875 * If {@code enabled} is {@code true}, the feature is requested to be present. 1876 * Otherwise, the feature is requested to be not present. 1877 * 1878 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 1879 * 1880 * @see MediaCodecList#findDecoderForFormat 1881 * @see MediaCodecList#findEncoderForFormat 1882 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 1883 */ setFeatureEnabled(@onNull String feature, boolean enabled)1884 public void setFeatureEnabled(@NonNull String feature, boolean enabled) { 1885 setInteger(KEY_FEATURE_ + feature, enabled ? 1 : 0); 1886 } 1887 1888 /** 1889 * Creates a minimal audio format. 1890 * @param mime The mime type of the content. 1891 * @param sampleRate The sampling rate of the content. 1892 * @param channelCount The number of audio channels in the content. 1893 */ createAudioFormat( @onNull String mime, int sampleRate, int channelCount)1894 public static final @NonNull MediaFormat createAudioFormat( 1895 @NonNull String mime, 1896 int sampleRate, 1897 int channelCount) { 1898 MediaFormat format = new MediaFormat(); 1899 format.setString(KEY_MIME, mime); 1900 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 1901 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 1902 1903 return format; 1904 } 1905 1906 /** 1907 * Creates a minimal subtitle format. 1908 * @param mime The mime type of the content. 1909 * @param language The language of the content, using either ISO 639-1 or 639-2/T 1910 * codes. Specify null or "und" if language information is only included 1911 * in the content. (This will also work if there are multiple language 1912 * tracks in the content.) 1913 */ createSubtitleFormat( @onNull String mime, String language)1914 public static final @NonNull MediaFormat createSubtitleFormat( 1915 @NonNull String mime, 1916 String language) { 1917 MediaFormat format = new MediaFormat(); 1918 format.setString(KEY_MIME, mime); 1919 format.setString(KEY_LANGUAGE, language); 1920 1921 return format; 1922 } 1923 1924 /** 1925 * Creates a minimal video format. 1926 * @param mime The mime type of the content. 1927 * @param width The width of the content (in pixels) 1928 * @param height The height of the content (in pixels) 1929 */ createVideoFormat( @onNull String mime, int width, int height)1930 public static final @NonNull MediaFormat createVideoFormat( 1931 @NonNull String mime, 1932 int width, 1933 int height) { 1934 MediaFormat format = new MediaFormat(); 1935 format.setString(KEY_MIME, mime); 1936 format.setInteger(KEY_WIDTH, width); 1937 format.setInteger(KEY_HEIGHT, height); 1938 1939 return format; 1940 } 1941 1942 @Override toString()1943 public @NonNull String toString() { 1944 return mMap.toString(); 1945 } 1946 } 1947
