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