public class MediaRecorder extends Object
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 setOnInfoListener(OnInfoListener)
setOnInfoListener and/or
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.
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.
Modifier and Type | Class and Description |
---|---|
class |
MediaRecorder.AudioEncoder
Defines the audio encoding.
|
class |
MediaRecorder.AudioSource
Defines the audio source.
|
static interface |
MediaRecorder.OnErrorListener
Interface definition for a callback to be invoked when an error
occurs while recording.
|
static interface |
MediaRecorder.OnInfoListener
Interface definition for a callback to be invoked when an error
occurs while recording.
|
class |
MediaRecorder.OutputFormat
Defines the output format.
|
class |
MediaRecorder.VideoEncoder
Defines the video encoding.
|
class |
MediaRecorder.VideoSource
Defines the video source.
|
Modifier and Type | Field and Description |
---|---|
static int |
MEDIA_ERROR_SERVER_DIED
Media server died.
|
static int |
MEDIA_RECORDER_ERROR_UNKNOWN
Unspecified media recorder error.
|
static int |
MEDIA_RECORDER_INFO_MAX_DURATION_REACHED
A maximum duration had been setup and has now been reached.
|
static int |
MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED
A maximum filesize had been setup and has now been reached.
|
static int |
MEDIA_RECORDER_INFO_UNKNOWN
Unspecified media recorder error.
|
static int |
MEDIA_RECORDER_TRACK_INFO_COMPLETION_STATUS
Signal the completion of the track for the recording session.
|
static int |
MEDIA_RECORDER_TRACK_INFO_DATA_KBYTES
Provide the total number of data (in kilo-bytes) encoded.
|
static int |
MEDIA_RECORDER_TRACK_INFO_DURATION_MS
Provide the track duration information.
|
static int |
MEDIA_RECORDER_TRACK_INFO_ENCODED_FRAMES
Provide the total number of recordd frames.
|
static int |
MEDIA_RECORDER_TRACK_INFO_INITIAL_DELAY_MS
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.
|
static int |
MEDIA_RECORDER_TRACK_INFO_LIST_END |
static int |
MEDIA_RECORDER_TRACK_INFO_LIST_START
informational events for individual tracks, for testing purpose.
|
static int |
MEDIA_RECORDER_TRACK_INFO_MAX_CHUNK_DUR_MS
Provide the max chunk duration in time (ms) for the given track.
|
static int |
MEDIA_RECORDER_TRACK_INFO_PROGRESS_IN_TIME
Indicate the recording progress in time (ms) during recording.
|
static int |
MEDIA_RECORDER_TRACK_INFO_START_OFFSET_MS
Provide the start time difference (delay) betweeen this track and
the start of the movie.
|
static int |
MEDIA_RECORDER_TRACK_INFO_TYPE
Indicate the track type: 0 for Audio and 1 for Video.
|
static int |
MEDIA_RECORDER_TRACK_INTER_CHUNK_TIME_MS
Provide the max spacing between neighboring chunks for the given track.
|
Constructor and Description |
---|
MediaRecorder()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
protected void |
finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
|
static int |
getAudioSourceMax()
Gets the maximum value for audio sources.
|
int |
getMaxAmplitude()
Returns the maximum absolute amplitude that was sampled since the last
call to this method.
|
void |
prepare()
Prepares the recorder to begin capturing and encoding data.
|
void |
release()
Releases resources associated with this MediaRecorder object.
|
void |
reset()
Restarts the MediaRecorder to its idle state.
|
void |
setAudioChannels(int numChannels)
Sets the number of audio channels for recording.
|
void |
setAudioEncoder(int audio_encoder)
Sets the audio encoder to be used for recording.
|
void |
setAudioEncodingBitRate(int bitRate)
Sets the audio encoding bit rate for recording.
|
void |
setAudioSamplingRate(int samplingRate)
Sets the audio sampling rate for recording.
|
void |
setAudioSource(int audio_source)
Sets the audio source to be used for recording.
|
void |
setAuxiliaryOutputFile(FileDescriptor fd)
Deprecated.
Time lapse mode video recording using camera still image capture
is not desirable, and will not be supported.
|
void |
setAuxiliaryOutputFile(String path)
Deprecated.
Time lapse mode video recording using camera still image capture
is not desirable, and will not be supported.
|
void |
setCamera(Camera c)
Sets a Camera to use for recording.
|
void |
setCaptureRate(double fps)
Set video frame capture rate.
|
void |
setLocation(float latitude,
float longitude)
Set and store the geodata (latitude and longitude) in the output file.
|
void |
setMaxDuration(int max_duration_ms)
Sets the maximum duration (in ms) of the recording session.
|
void |
setMaxFileSize(long max_filesize_bytes)
Sets the maximum filesize (in bytes) of the recording session.
|
void |
setOnErrorListener(MediaRecorder.OnErrorListener l)
Register a callback to be invoked when an error occurs while
recording.
|
void |
setOnInfoListener(MediaRecorder.OnInfoListener listener)
Register a callback to be invoked when an informational event occurs while
recording.
|
void |
setOrientationHint(int degrees)
Sets the orientation hint for output video playback.
|
void |
setOutputFile(FileDescriptor fd)
Pass in the file descriptor of the file to be written.
|
void |
setOutputFile(String path)
Sets the path of the output file to be produced.
|
void |
setOutputFormat(int output_format)
Sets the format of the output file produced during recording.
|
void |
setPreviewDisplay(Surface sv)
Sets a Surface to show a preview of recorded media (video).
|
void |
setProfile(CamcorderProfile profile)
Uses the settings from a CamcorderProfile object for recording.
|
void |
setVideoEncoder(int video_encoder)
Sets the video encoder to be used for recording.
|
void |
setVideoEncodingBitRate(int bitRate)
Sets the video encoding bit rate for recording.
|
void |
setVideoFrameRate(int rate)
Sets the frame rate of the video to be captured.
|
void |
setVideoSize(int width,
int height)
Sets the width and height of the video to be captured.
|
void |
setVideoSource(int video_source)
Sets the video source to be used for recording.
|
void |
start()
Begins capturing and encoding data to the file specified with
setOutputFile().
|
void |
stop()
Stops recording.
|
public static final int MEDIA_RECORDER_ERROR_UNKNOWN
public static final int MEDIA_ERROR_SERVER_DIED
public static final int MEDIA_RECORDER_INFO_UNKNOWN
public static final int MEDIA_RECORDER_INFO_MAX_DURATION_REACHED
public static final int MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED
public static final int MEDIA_RECORDER_TRACK_INFO_LIST_START
public static final int MEDIA_RECORDER_TRACK_INFO_COMPLETION_STATUS
public static final int MEDIA_RECORDER_TRACK_INFO_PROGRESS_IN_TIME
public static final int MEDIA_RECORDER_TRACK_INFO_TYPE
public static final int MEDIA_RECORDER_TRACK_INFO_DURATION_MS
public static final int MEDIA_RECORDER_TRACK_INFO_MAX_CHUNK_DUR_MS
public static final int MEDIA_RECORDER_TRACK_INFO_ENCODED_FRAMES
public static final int MEDIA_RECORDER_TRACK_INTER_CHUNK_TIME_MS
public static final int MEDIA_RECORDER_TRACK_INFO_INITIAL_DELAY_MS
public static final int MEDIA_RECORDER_TRACK_INFO_START_OFFSET_MS
public static final int MEDIA_RECORDER_TRACK_INFO_DATA_KBYTES
public static final int MEDIA_RECORDER_TRACK_INFO_LIST_END
public void setCamera(Camera c)
Camera.unlock()
should be
called before this. Must call before prepare().c
- the Camera to use for recordingpublic void setPreviewDisplay(Surface sv)
setCamera(Camera)
is used and the surface has been
already set to the camera, application do not need to call this. If
this is called with non-null surface, the preview surface of the camera
will be replaced by the new surface. If this method is called with null
surface or not called at all, media recorder will not change the preview
surface of the camera.sv
- the Surface to use for the previewCamera.setPreviewDisplay(android.view.SurfaceHolder)
public void setAudioSource(int audio_source) throws IllegalStateException
audio_source
- the audio source to useIllegalStateException
- if it is called after setOutputFormat()MediaRecorder.AudioSource
public static final int getAudioSourceMax()
MediaRecorder.AudioSource
public void setVideoSource(int video_source) throws IllegalStateException
video_source
- the video source to useIllegalStateException
- if it is called after setOutputFormat()MediaRecorder.VideoSource
public void setProfile(CamcorderProfile profile)
profile
- the CamcorderProfile to useCamcorderProfile
public void setCaptureRate(double fps)
fps
- Rate at which frames should be captured in frames per second.
The fps can go as low as desired. However the fastest fps will be limited by the hardware.
For resolutions that can be captured by the video camera, the fastest fps can be computed using
Camera.Parameters.getPreviewFpsRange(int[])
. For higher
resolutions the fastest fps may be more restrictive.
Note that the recorder cannot guarantee that frames will be captured at the
given rate due to camera/encoder limitations. However it tries to be as close as
possible.public void setOrientationHint(int degrees)
degrees
- the angle to be rotated clockwise in degrees.
The supported angles are 0, 90, 180, and 270 degrees.IllegalArgumentException
- if the angle is not supported.public void setLocation(float latitude, float longitude)
latitude
- latitude in degrees. Its value must be in the
range [-90, 90].longitude
- longitude in degrees. Its value must be in the
range [-180, 180].IllegalArgumentException
- if the given latitude or
longitude is out of range.public void setOutputFormat(int output_format) throws IllegalStateException
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.
output_format
- the output format to use. The output format
needs to be specified before setting recording-parameters or encoders.IllegalStateException
- if it is called after prepare() or before
setAudioSource()/setVideoSource().MediaRecorder.OutputFormat
public void setVideoSize(int width, int height) throws IllegalStateException
width
- the width of the video to be capturedheight
- the height of the video to be capturedIllegalStateException
- if it is called after
prepare() or before setOutputFormat()public void setVideoFrameRate(int rate) throws IllegalStateException
rate
- the number of frames per second of video to captureIllegalStateException
- 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 void setMaxDuration(int max_duration_ms) throws IllegalArgumentException
MediaRecorder.OnInfoListener
with a "what" code of 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.max_duration_ms
- the maximum duration in ms (if zero or negative, disables the duration limit)IllegalArgumentException
public void setMaxFileSize(long max_filesize_bytes) throws IllegalArgumentException
MediaRecorder.OnInfoListener
with a "what" code of 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.max_filesize_bytes
- the maximum filesize in bytes (if zero or negative, disables the limit)IllegalArgumentException
public void setAudioEncoder(int audio_encoder) throws IllegalStateException
audio_encoder
- the audio encoder to use.IllegalStateException
- if it is called before
setOutputFormat() or after prepare().MediaRecorder.AudioEncoder
public void setVideoEncoder(int video_encoder) throws IllegalStateException
video_encoder
- the video encoder to use.IllegalStateException
- if it is called before
setOutputFormat() or after prepare()MediaRecorder.VideoEncoder
public void setAudioSamplingRate(int samplingRate)
samplingRate
- the sampling rate for audio in samples per second.public void setAudioChannels(int numChannels)
numChannels
- the number of audio channels. Usually it is either 1 (mono) or 2
(stereo).public void setAudioEncodingBitRate(int bitRate)
bitRate
- the audio encoding bit rate in bits per second.public void setVideoEncodingBitRate(int bitRate)
bitRate
- the video encoding bit rate in bits per second.public void setAuxiliaryOutputFile(FileDescriptor fd)
public void setAuxiliaryOutputFile(String path)
public void setOutputFile(FileDescriptor fd) throws IllegalStateException
fd
- an open file descriptor to be written into.IllegalStateException
- if it is called before
setOutputFormat() or after prepare()public void setOutputFile(String path) throws IllegalStateException
path
- The pathname to use.IllegalStateException
- if it is called before
setOutputFormat() or after prepare()public void prepare() throws IllegalStateException, IOException
IllegalStateException
- if it is called after
start() or before setOutputFormat().IOException
- if prepare fails otherwise.public void start() throws IllegalStateException
Since API level 13, if applications set a camera via
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.
IllegalStateException
- if it is called before
prepare().public void stop() throws IllegalStateException
IllegalStateException
- if it is called before start()public void reset()
public int getMaxAmplitude() throws IllegalStateException
IllegalStateException
- if it is called before
the audio source has been set.public void setOnErrorListener(MediaRecorder.OnErrorListener l)
l
- the callback that will be runpublic void setOnInfoListener(MediaRecorder.OnInfoListener listener)
listener
- the callback that will be runpublic void release()
protected void finalize()
Object
Note that objects that override finalize
are significantly more expensive than
objects that don't. Finalizers may be run a long time after the object is no longer
reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup.
Note also that finalizers are run on a single VM-wide finalizer thread,
so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary
for a class that has a native peer and needs to call a native method to destroy that peer.
Even then, it's better to provide an explicit close
method (and implement
Closeable
), and insist that callers manually dispose of instances. This
works well for something like files, but less well for something like a BigInteger
where typical calling code would have to deal with lots of temporaries. Unfortunately,
code that creates lots of temporaries is the worst kind of code from the point of view of
the single finalizer thread.
If you must use finalizers, consider at least providing your own
ReferenceQueue
and having your own thread process that queue.
Unlike constructors, finalizers are not automatically chained. You are responsible for
calling super.finalize()
yourself.
Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.