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