MediaFormat.java revision 158754b1bfc9e0a03a6d9bcd999bdcbd42cedd30
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 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 * </table> 48 * 49 * Audio formats have the following keys: 50 * <table> 51 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 52 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr> 53 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr> 54 * <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> 55 * <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> 56 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr> 57 * <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> 58 * </table> 59 * 60 */ 61public final class MediaFormat { 62 private Map<String, Object> mMap; 63 64 /** 65 * A key describing the mime type of the MediaFormat. 66 * The associated value is a string. 67 */ 68 public static final String KEY_MIME = "mime"; 69 70 /** 71 * A key describing the sample rate of an audio format. 72 * The associated value is an integer 73 */ 74 public static final String KEY_SAMPLE_RATE = "sample-rate"; 75 76 /** 77 * A key describing the number of channels in an audio format. 78 * The associated value is an integer 79 */ 80 public static final String KEY_CHANNEL_COUNT = "channel-count"; 81 82 /** 83 * A key describing the width of the content in a video format. 84 * The associated value is an integer 85 */ 86 public static final String KEY_WIDTH = "width"; 87 88 /** 89 * A key describing the height of the content in a video format. 90 * The associated value is an integer 91 */ 92 public static final String KEY_HEIGHT = "height"; 93 94 /** A key describing the maximum size in bytes of a buffer of data 95 * described by this MediaFormat. 96 * The associated value is an integer 97 */ 98 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 99 100 /** 101 * A key describing the bitrate in bits/sec. 102 * The associated value is an integer 103 */ 104 public static final String KEY_BIT_RATE = "bitrate"; 105 106 /** 107 * A key describing the color format of the content in a video format. 108 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 109 */ 110 public static final String KEY_COLOR_FORMAT = "color-format"; 111 112 /** 113 * A key describing the frame rate of a video format in frames/sec. 114 * The associated value is an integer or a float. 115 */ 116 public static final String KEY_FRAME_RATE = "frame-rate"; 117 118 /** 119 * A key describing the frequency of I frames expressed in secs 120 * between I frames. 121 * The associated value is an integer. 122 */ 123 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 124 125 /** 126 * @hide 127 */ 128 public static final String KEY_STRIDE = "stride"; 129 /** 130 * @hide 131 */ 132 public static final String KEY_SLICE_HEIGHT = "slice-height"; 133 134 /** 135 * A key describing the duration (in microseconds) of the content. 136 * The associated value is a long. 137 */ 138 public static final String KEY_DURATION = "durationUs"; 139 140 /** 141 * A key mapping to a value of 1 if the content is AAC audio and 142 * audio frames are prefixed with an ADTS header. 143 * The associated value is an integer (0 or 1). 144 * This key is only supported when _decoding_ content, it cannot 145 * be used to configure an encoder to emit ADTS output. 146 */ 147 public static final String KEY_IS_ADTS = "is-adts"; 148 149 /** 150 * A key describing the channel composition of audio content. This mask 151 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 152 * The associated value is an integer. 153 */ 154 public static final String KEY_CHANNEL_MASK = "channel-mask"; 155 156 /** 157 * A key describing the AAC profile to be used (AAC audio formats only). 158 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 159 */ 160 public static final String KEY_AAC_PROFILE = "aac-profile"; 161 162 /** 163 * A key describing the FLAC compression level to be used (FLAC audio format only). 164 * The associated value is an integer ranging from 0 (fastest, least compression) 165 * to 8 (slowest, most compression). 166 */ 167 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 168 169 /* package private */ MediaFormat(Map<String, Object> map) { 170 mMap = map; 171 } 172 173 /** 174 * Creates an empty MediaFormat 175 */ 176 public MediaFormat() { 177 mMap = new HashMap(); 178 } 179 180 /* package private */ Map<String, Object> getMap() { 181 return mMap; 182 } 183 184 /** 185 * Returns true iff a key of the given name exists in the format. 186 */ 187 public final boolean containsKey(String name) { 188 return mMap.containsKey(name); 189 } 190 191 /** 192 * Returns the value of an integer key. 193 */ 194 public final int getInteger(String name) { 195 return ((Integer)mMap.get(name)).intValue(); 196 } 197 198 /** 199 * Returns the value of a long key. 200 */ 201 public final long getLong(String name) { 202 return ((Long)mMap.get(name)).longValue(); 203 } 204 205 /** 206 * Returns the value of a float key. 207 */ 208 public final float getFloat(String name) { 209 return ((Float)mMap.get(name)).floatValue(); 210 } 211 212 /** 213 * Returns the value of a string key. 214 */ 215 public final String getString(String name) { 216 return (String)mMap.get(name); 217 } 218 219 /** 220 * Returns the value of a ByteBuffer key. 221 */ 222 public final ByteBuffer getByteBuffer(String name) { 223 return (ByteBuffer)mMap.get(name); 224 } 225 226 /** 227 * Sets the value of an integer key. 228 */ 229 public final void setInteger(String name, int value) { 230 mMap.put(name, new Integer(value)); 231 } 232 233 /** 234 * Sets the value of a long key. 235 */ 236 public final void setLong(String name, long value) { 237 mMap.put(name, new Long(value)); 238 } 239 240 /** 241 * Sets the value of a float key. 242 */ 243 public final void setFloat(String name, float value) { 244 mMap.put(name, new Float(value)); 245 } 246 247 /** 248 * Sets the value of a string key. 249 */ 250 public final void setString(String name, String value) { 251 mMap.put(name, value); 252 } 253 254 /** 255 * Sets the value of a ByteBuffer key. 256 */ 257 public final void setByteBuffer(String name, ByteBuffer bytes) { 258 mMap.put(name, bytes); 259 } 260 261 /** 262 * Creates a minimal audio format. 263 * @param mime The mime type of the content. 264 * @param sampleRate The sampling rate of the content. 265 * @param channelCount The number of audio channels in the content. 266 */ 267 public static final MediaFormat createAudioFormat( 268 String mime, 269 int sampleRate, 270 int channelCount) { 271 MediaFormat format = new MediaFormat(); 272 format.setString(KEY_MIME, mime); 273 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 274 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 275 276 return format; 277 } 278 279 /** 280 * Creates a minimal video format. 281 * @param mime The mime type of the content. 282 * @param width The width of the content (in pixels) 283 * @param height The height of the content (in pixels) 284 */ 285 public static final MediaFormat createVideoFormat( 286 String mime, 287 int width, 288 int height) { 289 MediaFormat format = new MediaFormat(); 290 format.setString(KEY_MIME, mime); 291 format.setInteger(KEY_WIDTH, width); 292 format.setInteger(KEY_HEIGHT, height); 293 294 return format; 295 } 296 297 @Override 298 public String toString() { 299 return mMap.toString(); 300 } 301} 302