MediaFormat.java revision 8a39021dfaf401cabb7f46b83d936ed88bf209d9
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 17package android.media; 18 19import java.nio.ByteBuffer; 20import java.util.HashMap; 21import java.util.Map; 22 23/** 24 * Encapsulates the information describing the format of media data, 25 * be it audio or video. 26 * 27 * The format of the media data is specified as string/value pairs. 28 * 29 * Keys common to all audio/video formats, <b>all keys not marked optional are mandatory</b>: 30 * 31 * <table> 32 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 33 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 34 * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr> 35 * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr> 36 * </table> 37 * 38 * Video formats have the following keys: 39 * <table> 40 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 41 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 42 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 43 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 44 * for encoders, readable in the output format of decoders</b></td></tr> 45 * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td><b>encoder-only</b></td></tr> 46 * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer</td><td><b>encoder-only</b></td></tr> 47 * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr> 48 * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr> 49 * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>video encoder in surface-mode only</b></td></tr> 50 * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>video decoder rendering to a surface only</b></td></tr> 51 * </table> 52 * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable 53 * adaptive playback (seamless resolution change) for a video decoder that 54 * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}). 55 * The values are used as hints for the codec: they are the maximum expected 56 * resolution to prepare for. Depending on codec support, preparing for larger 57 * maximum resolution may require more memory even if that resolution is never 58 * reached. These fields have no effect for codecs that do not support adaptive 59 * playback.<br /><br /> 60 * 61 * Audio formats have the following keys: 62 * <table> 63 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 64 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr> 65 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr> 66 * <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> 67 * <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> 68 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr> 69 * <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> 70 * </table> 71 * 72 * Subtitle formats have the following keys: 73 * <table> 74 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 75 * <tr><td>{@link #KEY_LANGUAGE}</td><td>String</td><td>The language of the content.</td></tr> 76 * </table> 77 */ 78public final class MediaFormat { 79 private Map<String, Object> mMap; 80 81 /** 82 * A key describing the mime type of the MediaFormat. 83 * The associated value is a string. 84 */ 85 public static final String KEY_MIME = "mime"; 86 87 /** 88 * A key describing the language of the content, using either ISO 639-1 89 * or 639-2/T codes. The associated value is a string. 90 */ 91 public static final String KEY_LANGUAGE = "language"; 92 93 /** 94 * A key describing the sample rate of an audio format. 95 * The associated value is an integer 96 */ 97 public static final String KEY_SAMPLE_RATE = "sample-rate"; 98 99 /** 100 * A key describing the number of channels in an audio format. 101 * The associated value is an integer 102 */ 103 public static final String KEY_CHANNEL_COUNT = "channel-count"; 104 105 /** 106 * A key describing the width of the content in a video format. 107 * The associated value is an integer 108 */ 109 public static final String KEY_WIDTH = "width"; 110 111 /** 112 * A key describing the height of the content in a video format. 113 * The associated value is an integer 114 */ 115 public static final String KEY_HEIGHT = "height"; 116 117 /** 118 * A key describing the maximum expected width of the content in a video 119 * decoder format, in case there are resolution changes in the video content. 120 * The associated value is an integer 121 */ 122 public static final String KEY_MAX_WIDTH = "max-width"; 123 124 /** 125 * A key describing the maximum expected height of the content in a video 126 * decoder format, in case there are resolution changes in the video content. 127 * The associated value is an integer 128 */ 129 public static final String KEY_MAX_HEIGHT = "max-height"; 130 131 /** A key describing the maximum size in bytes of a buffer of data 132 * described by this MediaFormat. 133 * The associated value is an integer 134 */ 135 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 136 137 /** 138 * A key describing the bitrate in bits/sec. 139 * The associated value is an integer 140 */ 141 public static final String KEY_BIT_RATE = "bitrate"; 142 143 /** 144 * A key describing the color format of the content in a video format. 145 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 146 */ 147 public static final String KEY_COLOR_FORMAT = "color-format"; 148 149 /** 150 * A key describing the frame rate of a video format in frames/sec. 151 * The associated value is an integer or a float. 152 */ 153 public static final String KEY_FRAME_RATE = "frame-rate"; 154 155 /** 156 * A key describing the frequency of I frames expressed in secs 157 * between I frames. 158 * The associated value is an integer. 159 */ 160 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 161 162 /** 163 * @hide 164 */ 165 public static final String KEY_STRIDE = "stride"; 166 /** 167 * @hide 168 */ 169 public static final String KEY_SLICE_HEIGHT = "slice-height"; 170 171 /** 172 * Applies only when configuring a video encoder in "surface-input" mode. 173 * The associated value is a long and gives the time in microseconds 174 * after which the frame previously submitted to the encoder will be 175 * repeated (once) if no new frame became available since. 176 */ 177 public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER 178 = "repeat-previous-frame-after"; 179 180 /** 181 * If specified when configuring a video decoder rendering to a surface, 182 * causes the decoder to output "blank", i.e. black frames to the surface 183 * when stopped to clear out any previously displayed contents. 184 * The associated value is an integer of value 1. 185 */ 186 public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP 187 = "push-blank-buffers-on-shutdown"; 188 189 /** 190 * A key describing the duration (in microseconds) of the content. 191 * The associated value is a long. 192 */ 193 public static final String KEY_DURATION = "durationUs"; 194 195 /** 196 * A key mapping to a value of 1 if the content is AAC audio and 197 * audio frames are prefixed with an ADTS header. 198 * The associated value is an integer (0 or 1). 199 * This key is only supported when _decoding_ content, it cannot 200 * be used to configure an encoder to emit ADTS output. 201 */ 202 public static final String KEY_IS_ADTS = "is-adts"; 203 204 /** 205 * A key describing the channel composition of audio content. This mask 206 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 207 * The associated value is an integer. 208 */ 209 public static final String KEY_CHANNEL_MASK = "channel-mask"; 210 211 /** 212 * A key describing the AAC profile to be used (AAC audio formats only). 213 * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. 214 */ 215 public static final String KEY_AAC_PROFILE = "aac-profile"; 216 217 /** 218 * A key describing the FLAC compression level to be used (FLAC audio format only). 219 * The associated value is an integer ranging from 0 (fastest, least compression) 220 * to 8 (slowest, most compression). 221 */ 222 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 223 224 /** 225 * A key for boolean AUTOSELECT field. Tracks with AUTOSELECT=true are 226 * considered when automatically selecting a track without specific user 227 * choice (as defined by HLS). 228 * @hide 229 */ 230 public static final String KEY_AUTOSELECT = "autoselect"; 231 232 /** 233 * A key for boolean DEFAULT field. The track with DEFAULT=true is selected 234 * in the absence of a specific user choice (as defined by HLS). 235 * @hide 236 */ 237 public static final String KEY_DEFAULT = "default"; 238 239 /** 240 * A key for boolean FORCED field for subtitle tracks. True if it is a 241 * forced subtitle track. 242 * @hide 243 */ 244 public static final String KEY_FORCED = "forced"; 245 246 /* package private */ MediaFormat(Map<String, Object> map) { 247 mMap = map; 248 } 249 250 /** 251 * Creates an empty MediaFormat 252 */ 253 public MediaFormat() { 254 mMap = new HashMap(); 255 } 256 257 /* package private */ Map<String, Object> getMap() { 258 return mMap; 259 } 260 261 /** 262 * Returns true iff a key of the given name exists in the format. 263 */ 264 public final boolean containsKey(String name) { 265 return mMap.containsKey(name); 266 } 267 268 /** 269 * Returns the value of an integer key. 270 */ 271 public final int getInteger(String name) { 272 return ((Integer)mMap.get(name)).intValue(); 273 } 274 275 /** 276 * Returns the value of an integer key, or the default value if the 277 * key is missing or is for another type value. 278 * @hide 279 */ 280 public final int getInteger(String name, int defaultValue) { 281 try { 282 return getInteger(name); 283 } 284 catch (NullPointerException e) { /* no such field */ } 285 catch (ClassCastException e) { /* field of different type */ } 286 return defaultValue; 287 } 288 289 /** 290 * Returns the value of a long key. 291 */ 292 public final long getLong(String name) { 293 return ((Long)mMap.get(name)).longValue(); 294 } 295 296 /** 297 * Returns the value of a float key. 298 */ 299 public final float getFloat(String name) { 300 return ((Float)mMap.get(name)).floatValue(); 301 } 302 303 /** 304 * Returns the value of a string key. 305 */ 306 public final String getString(String name) { 307 return (String)mMap.get(name); 308 } 309 310 /** 311 * Returns the value of a ByteBuffer key. 312 */ 313 public final ByteBuffer getByteBuffer(String name) { 314 return (ByteBuffer)mMap.get(name); 315 } 316 317 /** 318 * Sets the value of an integer key. 319 */ 320 public final void setInteger(String name, int value) { 321 mMap.put(name, new Integer(value)); 322 } 323 324 /** 325 * Sets the value of a long key. 326 */ 327 public final void setLong(String name, long value) { 328 mMap.put(name, new Long(value)); 329 } 330 331 /** 332 * Sets the value of a float key. 333 */ 334 public final void setFloat(String name, float value) { 335 mMap.put(name, new Float(value)); 336 } 337 338 /** 339 * Sets the value of a string key. 340 */ 341 public final void setString(String name, String value) { 342 mMap.put(name, value); 343 } 344 345 /** 346 * Sets the value of a ByteBuffer key. 347 */ 348 public final void setByteBuffer(String name, ByteBuffer bytes) { 349 mMap.put(name, bytes); 350 } 351 352 /** 353 * Creates a minimal audio format. 354 * @param mime The mime type of the content. 355 * @param sampleRate The sampling rate of the content. 356 * @param channelCount The number of audio channels in the content. 357 */ 358 public static final MediaFormat createAudioFormat( 359 String mime, 360 int sampleRate, 361 int channelCount) { 362 MediaFormat format = new MediaFormat(); 363 format.setString(KEY_MIME, mime); 364 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 365 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 366 367 return format; 368 } 369 370 /** 371 * Creates a minimal subtitle format. 372 * @param mime The mime type of the content. 373 * @param language The language of the content, using either ISO 639-1 or 639-2/T 374 * codes. Specify null or "und" if language information is only included 375 * in the content. (This will also work if there are multiple language 376 * tracks in the content.) 377 */ 378 public static final MediaFormat createSubtitleFormat( 379 String mime, 380 String language) { 381 MediaFormat format = new MediaFormat(); 382 format.setString(KEY_MIME, mime); 383 format.setString(KEY_LANGUAGE, language); 384 385 return format; 386 } 387 388 /** 389 * Creates a minimal video format. 390 * @param mime The mime type of the content. 391 * @param width The width of the content (in pixels) 392 * @param height The height of the content (in pixels) 393 */ 394 public static final MediaFormat createVideoFormat( 395 String mime, 396 int width, 397 int height) { 398 MediaFormat format = new MediaFormat(); 399 format.setString(KEY_MIME, mime); 400 format.setInteger(KEY_WIDTH, width); 401 format.setInteger(KEY_HEIGHT, height); 402 403 return format; 404 } 405 406 @Override 407 public String toString() { 408 return mMap.toString(); 409 } 410} 411