/*
* Copyright (C) 2007 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.media;
import android.hardware.Camera;
import android.os.Handler;
import android.os.Looper;
import android.os.Message;
import android.util.Log;
import android.view.Surface;
import java.io.FileDescriptor;
import java.io.FileOutputStream;
import java.io.IOException;
import java.lang.ref.WeakReference;
/**
* Used to record audio and video. The recording control is based on a
* simple state machine (see below).
*
* 
*
*
* A common case of using MediaRecorder to record audio works as follows:
*
*
MediaRecorder recorder = new MediaRecorder();
* recorder.setAudioSource(MediaRecorder.AudioSource.MIC);
* recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP);
* recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB);
* recorder.setOutputFile(PATH_NAME);
* recorder.prepare();
* recorder.start(); // Recording is now started
* ...
* recorder.stop();
* recorder.reset(); // You can reuse the object by going back to setAudioSource() step
* recorder.release(); // Now the object cannot be reused
*
*
* Applications may want to register for informational and error
* events in order to be informed of some internal update and possible
* runtime errors during recording. Registration for such events is
* done by setting the appropriate listeners (via calls
* (to {@link #setOnInfoListener(OnInfoListener)}setOnInfoListener and/or
* {@link #setOnErrorListener(OnErrorListener)}setOnErrorListener).
* In order to receive the respective callback associated with these listeners,
* applications are required to create MediaRecorder objects on threads with a
* Looper running (the main UI thread by default already has a Looper running).
*
*
Note: Currently, MediaRecorder does not work on the emulator.
*
*
*
Developer Guides
*
For more information about how to use MediaRecorder for recording video, read the
* Camera developer guide.
* For more information about how to use MediaRecorder for recording sound, read the
* Audio Capture developer guide.
*
It is recommended to always use 3GP format when using the H.263
* video encoder and AMR audio encoder. Using an MPEG-4 container format
* may confuse some desktop players.
*
* @param output_format the output format to use. The output format
* needs to be specified before setting recording-parameters or encoders.
* @throws IllegalStateException if it is called after prepare() or before
* setAudioSource()/setVideoSource().
* @see android.media.MediaRecorder.OutputFormat
*/
public native void setOutputFormat(int output_format)
throws IllegalStateException;
/**
* Sets the width and height of the video to be captured. Must be called
* after setVideoSource(). Call this after setOutFormat() but before
* prepare().
*
* @param width the width of the video to be captured
* @param height the height of the video to be captured
* @throws IllegalStateException if it is called after
* prepare() or before setOutputFormat()
*/
public native void setVideoSize(int width, int height)
throws IllegalStateException;
/**
* Sets the frame rate of the video to be captured. Must be called
* after setVideoSource(). Call this after setOutFormat() but before
* prepare().
*
* @param rate the number of frames per second of video to capture
* @throws IllegalStateException if it is called after
* prepare() or before setOutputFormat().
*
* NOTE: On some devices that have auto-frame rate, this sets the
* maximum frame rate, not a constant frame rate. Actual frame rate
* will vary according to lighting conditions.
*/
public native void setVideoFrameRate(int rate) throws IllegalStateException;
/**
* Sets the maximum duration (in ms) of the recording session.
* Call this after setOutFormat() but before prepare().
* After recording reaches the specified duration, a notification
* will be sent to the {@link android.media.MediaRecorder.OnInfoListener}
* with a "what" code of {@link #MEDIA_RECORDER_INFO_MAX_DURATION_REACHED}
* and recording will be stopped. Stopping happens asynchronously, there
* is no guarantee that the recorder will have stopped by the time the
* listener is notified.
*
* @param max_duration_ms the maximum duration in ms (if zero or negative, disables the duration limit)
*
*/
public native void setMaxDuration(int max_duration_ms) throws IllegalArgumentException;
/**
* Sets the maximum filesize (in bytes) of the recording session.
* Call this after setOutFormat() but before prepare().
* After recording reaches the specified filesize, a notification
* will be sent to the {@link android.media.MediaRecorder.OnInfoListener}
* with a "what" code of {@link #MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED}
* and recording will be stopped. Stopping happens asynchronously, there
* is no guarantee that the recorder will have stopped by the time the
* listener is notified.
*
* @param max_filesize_bytes the maximum filesize in bytes (if zero or negative, disables the limit)
*
*/
public native void setMaxFileSize(long max_filesize_bytes) throws IllegalArgumentException;
/**
* Sets the audio encoder to be used for recording. If this method is not
* called, the output file will not contain an audio track. Call this after
* setOutputFormat() but before prepare().
*
* @param audio_encoder the audio encoder to use.
* @throws IllegalStateException if it is called before
* setOutputFormat() or after prepare().
* @see android.media.MediaRecorder.AudioEncoder
*/
public native void setAudioEncoder(int audio_encoder)
throws IllegalStateException;
/**
* Sets the video encoder to be used for recording. If this method is not
* called, the output file will not contain an video track. Call this after
* setOutputFormat() and before prepare().
*
* @param video_encoder the video encoder to use.
* @throws IllegalStateException if it is called before
* setOutputFormat() or after prepare()
* @see android.media.MediaRecorder.VideoEncoder
*/
public native void setVideoEncoder(int video_encoder)
throws IllegalStateException;
/**
* Sets the audio sampling rate for recording. Call this method before prepare().
* Prepare() may perform additional checks on the parameter to make sure whether
* the specified audio sampling rate is applicable. The sampling rate really depends
* on the format for the audio recording, as well as the capabilities of the platform.
* For instance, the sampling rate supported by AAC audio coding standard ranges
* from 8 to 96 kHz, the sampling rate supported by AMRNB is 8kHz, and the sampling
* rate supported by AMRWB is 16kHz. Please consult with the related audio coding
* standard for the supported audio sampling rate.
*
* @param samplingRate the sampling rate for audio in samples per second.
*/
public void setAudioSamplingRate(int samplingRate) {
if (samplingRate <= 0) {
throw new IllegalArgumentException("Audio sampling rate is not positive");
}
setParameter("audio-param-sampling-rate=" + samplingRate);
}
/**
* Sets the number of audio channels for recording. Call this method before prepare().
* Prepare() may perform additional checks on the parameter to make sure whether the
* specified number of audio channels are applicable.
*
* @param numChannels the number of audio channels. Usually it is either 1 (mono) or 2
* (stereo).
*/
public void setAudioChannels(int numChannels) {
if (numChannels <= 0) {
throw new IllegalArgumentException("Number of channels is not positive");
}
setParameter("audio-param-number-of-channels=" + numChannels);
}
/**
* Sets the audio encoding bit rate for recording. Call this method before prepare().
* Prepare() may perform additional checks on the parameter to make sure whether the
* specified bit rate is applicable, and sometimes the passed bitRate will be clipped
* internally to ensure the audio recording can proceed smoothly based on the
* capabilities of the platform.
*
* @param bitRate the audio encoding bit rate in bits per second.
*/
public void setAudioEncodingBitRate(int bitRate) {
if (bitRate <= 0) {
throw new IllegalArgumentException("Audio encoding bit rate is not positive");
}
setParameter("audio-param-encoding-bitrate=" + bitRate);
}
/**
* Sets the video encoding bit rate for recording. Call this method before prepare().
* Prepare() may perform additional checks on the parameter to make sure whether the
* specified bit rate is applicable, and sometimes the passed bitRate will be
* clipped internally to ensure the video recording can proceed smoothly based on
* the capabilities of the platform.
*
* @param bitRate the video encoding bit rate in bits per second.
*/
public void setVideoEncodingBitRate(int bitRate) {
if (bitRate <= 0) {
throw new IllegalArgumentException("Video encoding bit rate is not positive");
}
setParameter("video-param-encoding-bitrate=" + bitRate);
}
/**
* Currently not implemented. It does nothing.
* @deprecated Time lapse mode video recording using camera still image capture
* is not desirable, and will not be supported.
* @hide
*/
public void setAuxiliaryOutputFile(FileDescriptor fd)
{
Log.w(TAG, "setAuxiliaryOutputFile(FileDescriptor) is no longer supported.");
}
/**
* Currently not implemented. It does nothing.
* @deprecated Time lapse mode video recording using camera still image capture
* is not desirable, and will not be supported.
* @hide
*/
public void setAuxiliaryOutputFile(String path)
{
Log.w(TAG, "setAuxiliaryOutputFile(String) is no longer supported.");
}
/**
* Pass in the file descriptor of the file to be written. Call this after
* setOutputFormat() but before prepare().
*
* @param fd an open file descriptor to be written into.
* @throws IllegalStateException if it is called before
* setOutputFormat() or after prepare()
*/
public void setOutputFile(FileDescriptor fd) throws IllegalStateException
{
mPath = null;
mFd = fd;
}
/**
* Sets the path of the output file to be produced. Call this after
* setOutputFormat() but before prepare().
*
* @param path The pathname to use.
* @throws IllegalStateException if it is called before
* setOutputFormat() or after prepare()
*/
public void setOutputFile(String path) throws IllegalStateException
{
mFd = null;
mPath = path;
}
// native implementation
private native void _setOutputFile(FileDescriptor fd, long offset, long length)
throws IllegalStateException, IOException;
private native void _prepare() throws IllegalStateException, IOException;
/**
* Prepares the recorder to begin capturing and encoding data. This method
* must be called after setting up the desired audio and video sources,
* encoders, file format, etc., but before start().
*
* @throws IllegalStateException if it is called after
* start() or before setOutputFormat().
* @throws IOException if prepare fails otherwise.
*/
public void prepare() throws IllegalStateException, IOException
{
if (mPath != null) {
FileOutputStream fos = new FileOutputStream(mPath);
try {
_setOutputFile(fos.getFD(), 0, 0);
} finally {
fos.close();
}
} else if (mFd != null) {
_setOutputFile(mFd, 0, 0);
} else {
throw new IOException("No valid output file");
}
_prepare();
}
/**
* Begins capturing and encoding data to the file specified with
* setOutputFile(). Call this after prepare().
*
* Since API level 13, if applications set a camera via
* {@link #setCamera(Camera)}, the apps can use the camera after this method
* call. The apps do not need to lock the camera again. However, if this
* method fails, the apps should still lock the camera back. The apps should
* not start another recording session during recording.
*
* @throws IllegalStateException if it is called before
* prepare().
*/
public native void start() throws IllegalStateException;
/**
* Stops recording. Call this after start(). Once recording is stopped,
* you will have to configure it again as if it has just been constructed.
* Note that a RuntimeException is intentionally thrown to the
* application, if no valid audio/video data has been received when stop()
* is called. This happens if stop() is called immediately after
* start(). The failure lets the application take action accordingly to
* clean up the output file (delete the output file, for instance), since
* the output file is not properly constructed when this happens.
*
* @throws IllegalStateException if it is called before start()
*/
public native void stop() throws IllegalStateException;
/**
* Restarts the MediaRecorder to its idle state. After calling
* this method, you will have to configure it again as if it had just been
* constructed.
*/
public void reset() {
native_reset();
// make sure none of the listeners get called anymore
mEventHandler.removeCallbacksAndMessages(null);
}
private native void native_reset();
/**
* Returns the maximum absolute amplitude that was sampled since the last
* call to this method. Call this only after the setAudioSource().
*
* @return the maximum absolute amplitude measured since the last call, or
* 0 when called for the first time
* @throws IllegalStateException if it is called before
* the audio source has been set.
*/
public native int getMaxAmplitude() throws IllegalStateException;
/* Do not change this value without updating its counterpart
* in include/media/mediarecorder.h!
*/
/** Unspecified media recorder error.
* @see android.media.MediaRecorder.OnErrorListener
*/
public static final int MEDIA_RECORDER_ERROR_UNKNOWN = 1;
/**
* Interface definition for a callback to be invoked when an error
* occurs while recording.
*/
public interface OnErrorListener
{
/**
* Called when an error occurs while recording.
*
* @param mr the MediaRecorder that encountered the error
* @param what the type of error that has occurred:
*
* - {@link #MEDIA_RECORDER_ERROR_UNKNOWN}
*
* @param extra an extra code, specific to the error type
*/
void onError(MediaRecorder mr, int what, int extra);
}
/**
* Register a callback to be invoked when an error occurs while
* recording.
*
* @param l the callback that will be run
*/
public void setOnErrorListener(OnErrorListener l)
{
mOnErrorListener = l;
}
/* Do not change these values without updating their counterparts
* in include/media/mediarecorder.h!
*/
/** Unspecified media recorder error.
* @see android.media.MediaRecorder.OnInfoListener
*/
public static final int MEDIA_RECORDER_INFO_UNKNOWN = 1;
/** A maximum duration had been setup and has now been reached.
* @see android.media.MediaRecorder.OnInfoListener
*/
public static final int MEDIA_RECORDER_INFO_MAX_DURATION_REACHED = 800;
/** A maximum filesize had been setup and has now been reached.
* @see android.media.MediaRecorder.OnInfoListener
*/
public static final int MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED = 801;
/** informational events for individual tracks, for testing purpose.
* The track informational event usually contains two parts in the ext1
* arg of the onInfo() callback: bit 31-28 contains the track id; and
* the rest of the 28 bits contains the informational event defined here.
* For example, ext1 = (1 << 28 | MEDIA_RECORDER_TRACK_INFO_TYPE) if the
* track id is 1 for informational event MEDIA_RECORDER_TRACK_INFO_TYPE;
* while ext1 = (0 << 28 | MEDIA_RECORDER_TRACK_INFO_TYPE) if the track
* id is 0 for informational event MEDIA_RECORDER_TRACK_INFO_TYPE. The
* application should extract the track id and the type of informational
* event from ext1, accordingly.
*
* FIXME:
* Please update the comment for onInfo also when these
* events are unhidden so that application knows how to extract the track
* id and the informational event type from onInfo callback.
*
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_LIST_START = 1000;
/** Signal the completion of the track for the recording session.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_COMPLETION_STATUS = 1000;
/** Indicate the recording progress in time (ms) during recording.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_PROGRESS_IN_TIME = 1001;
/** Indicate the track type: 0 for Audio and 1 for Video.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_TYPE = 1002;
/** Provide the track duration information.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_DURATION_MS = 1003;
/** Provide the max chunk duration in time (ms) for the given track.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_MAX_CHUNK_DUR_MS = 1004;
/** Provide the total number of recordd frames.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_ENCODED_FRAMES = 1005;
/** Provide the max spacing between neighboring chunks for the given track.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INTER_CHUNK_TIME_MS = 1006;
/** Provide the elapsed time measuring from the start of the recording
* till the first output frame of the given track is received, excluding
* any intentional start time offset of a recording session for the
* purpose of eliminating the recording sound in the recorded file.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_INITIAL_DELAY_MS = 1007;
/** Provide the start time difference (delay) betweeen this track and
* the start of the movie.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_START_OFFSET_MS = 1008;
/** Provide the total number of data (in kilo-bytes) encoded.
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_DATA_KBYTES = 1009;
/**
* {@hide}
*/
public static final int MEDIA_RECORDER_TRACK_INFO_LIST_END = 2000;
/**
* Interface definition for a callback to be invoked when an error
* occurs while recording.
*/
public interface OnInfoListener
{
/**
* Called when an error occurs while recording.
*
* @param mr the MediaRecorder that encountered the error
* @param what the type of error that has occurred:
*
* - {@link #MEDIA_RECORDER_INFO_UNKNOWN}
*
- {@link #MEDIA_RECORDER_INFO_MAX_DURATION_REACHED}
*
- {@link #MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED}
*
* @param extra an extra code, specific to the error type
*/
void onInfo(MediaRecorder mr, int what, int extra);
}
/**
* Register a callback to be invoked when an informational event occurs while
* recording.
*
* @param listener the callback that will be run
*/
public void setOnInfoListener(OnInfoListener listener)
{
mOnInfoListener = listener;
}
private class EventHandler extends Handler
{
private MediaRecorder mMediaRecorder;
public EventHandler(MediaRecorder mr, Looper looper) {
super(looper);
mMediaRecorder = mr;
}
/* Do not change these values without updating their counterparts
* in include/media/mediarecorder.h!
*/
private static final int MEDIA_RECORDER_EVENT_LIST_START = 1;
private static final int MEDIA_RECORDER_EVENT_ERROR = 1;
private static final int MEDIA_RECORDER_EVENT_INFO = 2;
private static final int MEDIA_RECORDER_EVENT_LIST_END = 99;
/* Events related to individual tracks */
private static final int MEDIA_RECORDER_TRACK_EVENT_LIST_START = 100;
private static final int MEDIA_RECORDER_TRACK_EVENT_ERROR = 100;
private static final int MEDIA_RECORDER_TRACK_EVENT_INFO = 101;
private static final int MEDIA_RECORDER_TRACK_EVENT_LIST_END = 1000;
@Override
public void handleMessage(Message msg) {
if (mMediaRecorder.mNativeContext == 0) {
Log.w(TAG, "mediarecorder went away with unhandled events");
return;
}
switch(msg.what) {
case MEDIA_RECORDER_EVENT_ERROR:
case MEDIA_RECORDER_TRACK_EVENT_ERROR:
if (mOnErrorListener != null)
mOnErrorListener.onError(mMediaRecorder, msg.arg1, msg.arg2);
return;
case MEDIA_RECORDER_EVENT_INFO:
case MEDIA_RECORDER_TRACK_EVENT_INFO:
if (mOnInfoListener != null)
mOnInfoListener.onInfo(mMediaRecorder, msg.arg1, msg.arg2);
return;
default:
Log.e(TAG, "Unknown message type " + msg.what);
return;
}
}
}
/**
* Called from native code when an interesting event happens. This method
* just uses the EventHandler system to post the event back to the main app thread.
* We use a weak reference to the original MediaRecorder object so that the native
* code is safe from the object disappearing from underneath it. (This is
* the cookie passed to native_setup().)
*/
private static void postEventFromNative(Object mediarecorder_ref,
int what, int arg1, int arg2, Object obj)
{
MediaRecorder mr = (MediaRecorder)((WeakReference)mediarecorder_ref).get();
if (mr == null) {
return;
}
if (mr.mEventHandler != null) {
Message m = mr.mEventHandler.obtainMessage(what, arg1, arg2, obj);
mr.mEventHandler.sendMessage(m);
}
}
/**
* Releases resources associated with this MediaRecorder object.
* It is good practice to call this method when you're done
* using the MediaRecorder. In particular, whenever an Activity
* of an application is paused (its onPause() method is called),
* or stopped (its onStop() method is called), this method should be
* invoked to release the MediaRecorder object, unless the application
* has a special need to keep the object around. In addition to
* unnecessary resources (such as memory and instances of codecs)
* being held, failure to call this method immediately if a
* MediaRecorder object is no longer needed may also lead to
* continuous battery consumption for mobile devices, and recording
* failure for other applications if no multiple instances of the
* same codec are supported on a device. Even if multiple instances
* of the same codec are supported, some performance degradation
* may be expected when unnecessary multiple instances are used
* at the same time.
*/
public native void release();
private static native final void native_init();
private native final void native_setup(Object mediarecorder_this) throws IllegalStateException;
private native final void native_finalize();
private native void setParameter(String nameValuePair);
@Override
protected void finalize() { native_finalize(); }
}