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