CamcorderProfile.java revision d48a15c3fead59a1aa710a16bb5f923164475918 
1/*
2 * Copyright (C) 2010 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
19/**
20 * The CamcorderProfile class is used to retrieve the
21 * predefined camcorder profile settings for camcorder applications.
22 * These settings are read-only.
23 *
24 * The compressed output from a recording session with a given
25 * CamcorderProfile contains two tracks: one for auido and one for video.
26 *
27 * <p>Each profile specifies the following set of parameters:
28 * <ul>
29 * <li> The file output format
30 * <li> Video codec format
31 * <li> Video bit rate in bits per second
32 * <li> Video frame rate in frames per second
33 * <li> Video frame width and height,
34 * <li> Audio codec format
35 * <li> Audio bit rate in bits per second,
36 * <li> Audio sample rate
37 * <li> Number of audio channels for recording.
38 * </ul>
39 */
40public class CamcorderProfile
41{
42    // Do not change these values/ordinals without updating their counterpart
43    // in include/media/MediaProfiles.h!
44
45    /**
46     * Quality level corresponding to the lowest available resolution.
47     */
48    public static final int QUALITY_LOW  = 0;
49
50    /**
51     * Quality level corresponding to the highest available resolution.
52     */
53    public static final int QUALITY_HIGH = 1;
54
55    /**
56     * Quality level corresponding to the qcif (176 x 144) resolution.
57     */
58    public static final int QUALITY_QCIF = 2;
59
60    /**
61     * Quality level corresponding to the cif (352 x 288) resolution.
62     */
63    public static final int QUALITY_CIF = 3;
64
65    /**
66     * Quality level corresponding to the 480p (720 x 480) resolution.
67     */
68    public static final int QUALITY_480P = 4;
69
70    /**
71     * Quality level corresponding to the 720p (1280 x 720) resolution.
72     */
73    public static final int QUALITY_720P = 5;
74
75    /**
76     * Quality level corresponding to the 1080p (1920 x 1088) resolution.
77     */
78    public static final int QUALITY_1080P = 6;
79
80    /**
81     * Time lapse quality level corresponding to the lowest available resolution.
82     */
83    public static final int QUALITY_TIME_LAPSE_LOW  = 1000;
84
85    /**
86     * Time lapse quality level corresponding to the highest available resolution.
87     */
88    public static final int QUALITY_TIME_LAPSE_HIGH = 1001;
89
90    /**
91     * Time lapse quality level corresponding to the qcif (176 x 144) resolution.
92     */
93    public static final int QUALITY_TIME_LAPSE_QCIF = 1002;
94
95    /**
96     * Time lapse quality level corresponding to the cif (352 x 288) resolution.
97     */
98    public static final int QUALITY_TIME_LAPSE_CIF = 1003;
99
100    /**
101     * Time lapse quality level corresponding to the 480p (720 x 480) resolution.
102     */
103    public static final int QUALITY_TIME_LAPSE_480P = 1004;
104
105    /**
106     * Time lapse quality level corresponding to the 720p (1280 x 720) resolution.
107     */
108    public static final int QUALITY_TIME_LAPSE_720P = 1005;
109
110    /**
111     * Time lapse quality level corresponding to the 1080p (1920 x 1088) resolution.
112     */
113    public static final int QUALITY_TIME_LAPSE_1080P = 1006;
114
115    /**
116     * Default recording duration in seconds before the session is terminated.
117     * This is useful for applications like MMS has limited file size requirement.
118     */
119    public int duration;
120
121    /**
122     * The quality level of the camcorder profile
123     */
124    public int quality;
125
126    /**
127     * The file output format of the camcorder profile
128     * @see android.media.MediaRecorder.OutputFormat
129     */
130    public int fileFormat;
131
132    /**
133     * The video encoder being used for the video track
134     * @see android.media.MediaRecorder.VideoEncoder
135     */
136    public int videoCodec;
137
138    /**
139     * The target video output bit rate in bits per second
140     */
141    public int videoBitRate;
142
143    /**
144     * The target video frame rate in frames per second
145     */
146    public int videoFrameRate;
147
148    /**
149     * The target video frame width in pixels
150     */
151    public int videoFrameWidth;
152
153    /**
154     * The target video frame height in pixels
155     */
156    public int videoFrameHeight;
157
158    /**
159     * The audio encoder being used for the audio track.
160     * @see android.media.MediaRecorder.AudioEncoder
161     */
162    public int audioCodec;
163
164    /**
165     * The target audio output bit rate in bits per second
166     */
167    public int audioBitRate;
168
169    /**
170     * The audio sampling rate used for the audio track
171     */
172    public int audioSampleRate;
173
174    /**
175     * The number of audio channels used for the audio track
176     */
177    public int audioChannels;
178
179    /**
180     * Returns the camcorder profile for the default camera at the given
181     * quality level.
182     * @param quality the target quality level for the camcorder profile
183     * @see #get(int, int)
184     */
185    public static CamcorderProfile get(int quality) {
186        return get(android.hardware.Camera.CAMERA_ID_DEFAULT, quality);
187    }
188
189    /**
190     * Returns the camcorder profile for the given camera at the given
191     * quality level.
192     *
193     * Quality levels QUALITY_LOW, QUALITY_HIGH are guaranteed to be supported, while
194     * other levels may or may not be supported. The supported levels can be checked using
195     * {@link #hasProfile(int, int)}.
196     * QUALITY_LOW refers to the lowest quality available, while QUALITY_HIGH refers to
197     * the highest quality available.
198     * QUALITY_LOW/QUALITY_HIGH have to match one of qcif, cif, 480p, 720p, or 1080p.
199     * E.g. if the device supports 480p, 720p, and 1080p, then low is 480p and high is
200     * 1080p.
201     *
202     * The same is true for time lapse quality levels, i.e. QUALITY_TIME_LAPSE_LOW,
203     * QUALITY_TIME_LAPSE_HIGH are guaranteed to be supported and have to match one of
204     * qcif, cif, 480p, 720p, or 1080p.
205     *
206     * A camcorder recording session with higher quality level usually has higher output
207     * bit rate, better video and/or audio recording quality, larger video frame
208     * resolution and higher audio sampling rate, etc, than those with lower quality
209     * level.
210     *
211     * @param cameraId the id for the camera
212     * @param quality the target quality level for the camcorder profile.
213     * @see #QUALITY_LOW
214     * @see #QUALITY_HIGH
215     * @see #QUALITY_QCIF
216     * @see #QUALITY_CIF
217     * @see #QUALITY_480P
218     * @see #QUALITY_720P
219     * @see #QUALITY_1080P
220     * @see #QUALITY_TIME_LAPSE_LOW
221     * @see #QUALITY_TIME_LAPSE_HIGH
222     * @see #QUALITY_TIME_LAPSE_QCIF
223     * @see #QUALITY_TIME_LAPSE_CIF
224     * @see #QUALITY_TIME_LAPSE_480P
225     * @see #QUALITY_TIME_LAPSE_720P
226     * @see #QUALITY_TIME_LAPSE_1080P
227     */
228    public static CamcorderProfile get(int cameraId, int quality) {
229        if (!((quality >= QUALITY_LOW && quality <= QUALITY_1080P) ||
230                (quality >= QUALITY_TIME_LAPSE_LOW && quality <= QUALITY_TIME_LAPSE_1080P))) {
231            String errMessage = "Unsupported quality level: " + quality;
232            throw new IllegalArgumentException(errMessage);
233        }
234        return native_get_camcorder_profile(cameraId, quality);
235    }
236
237    /**
238     * Returns true if camcorder profile exists for the default camera at
239     * the given quality level.
240     * @param quality the target quality level for the camcorder profile
241     */
242    public static boolean hasProfile(int quality) {
243        return hasProfile(android.hardware.Camera.CAMERA_ID_DEFAULT, quality);
244    }
245
246    /**
247     * Returns true if camcorder profile exists for the given camera at
248     * the given quality level.
249     * @param cameraId the id for the camera
250     * @param quality the target quality level for the camcorder profile
251     */
252    public static boolean hasProfile(int cameraId, int quality) {
253        return native_has_camcorder_profile(cameraId, quality);
254    }
255
256    static {
257        System.loadLibrary("media_jni");
258        native_init();
259    }
260
261    // Private constructor called by JNI
262    private CamcorderProfile(int duration,
263                             int quality,
264                             int fileFormat,
265                             int videoCodec,
266                             int videoBitRate,
267                             int videoFrameRate,
268                             int videoWidth,
269                             int videoHeight,
270                             int audioCodec,
271                             int audioBitRate,
272                             int audioSampleRate,
273                             int audioChannels) {
274
275        this.duration         = duration;
276        this.quality          = quality;
277        this.fileFormat       = fileFormat;
278        this.videoCodec       = videoCodec;
279        this.videoBitRate     = videoBitRate;
280        this.videoFrameRate   = videoFrameRate;
281        this.videoFrameWidth  = videoWidth;
282        this.videoFrameHeight = videoHeight;
283        this.audioCodec       = audioCodec;
284        this.audioBitRate     = audioBitRate;
285        this.audioSampleRate  = audioSampleRate;
286        this.audioChannels    = audioChannels;
287    }
288
289    // Methods implemented by JNI
290    private static native final void native_init();
291    private static native final CamcorderProfile native_get_camcorder_profile(
292            int cameraId, int quality);
293    private static native final boolean native_has_camcorder_profile(
294            int cameraId, int quality);
295}
296