| java.lang.Object | |
| ↳ | android.media.AudioRecord |
The AudioRecord class manages the audio resources for Java applications
to record audio from the audio input hardware of the platform. This is
achieved by "pulling" (reading) the data from the AudioRecord object. The
application is responsible for polling the AudioRecord object in time using one of
the following three methods: read(byte[], int, int), read(short[], int, int)
or read(ByteBuffer, int). The choice of which method to use will be based
on the audio data storage format that is the most convenient for the user of AudioRecord.
Upon creation, an AudioRecord object initializes its associated audio buffer that it will fill with the new audio data. The size of this buffer, specified during the construction, determines how long an AudioRecord can record before "over-running" data that has not been read yet. Data should be read from the audio hardware in chunks of sizes inferior to the total recording buffer size.
| Nested Classes | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| AudioRecord.OnRecordPositionUpdateListener | Interface definition for a callback to be invoked when an AudioRecord has
reached a notification marker set by setNotificationMarkerPosition(int)
or for periodic updates on the progress of the record head, as set by
setPositionNotificationPeriod(int). |
||||||||||
| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| int | ERROR | Denotes a generic operation failure. | |||||||||
| int | ERROR_BAD_VALUE | Denotes a failure due to the use of an invalid value. | |||||||||
| int | ERROR_INVALID_OPERATION | Denotes a failure due to the improper use of a method. | |||||||||
| int | RECORDSTATE_RECORDING | indicates AudioRecord recording state is recording | |||||||||
| int | RECORDSTATE_STOPPED | indicates AudioRecord recording state is not recording | |||||||||
| int | STATE_INITIALIZED | indicates AudioRecord state is ready to be used | |||||||||
| int | STATE_UNINITIALIZED | indicates AudioRecord state is not successfully initialized. | |||||||||
| int | SUCCESS | Denotes a successful operation. | |||||||||
| Public Constructors | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Class constructor.
| |||||||||||
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Returns the configured audio data format.
| |||||||||||
Returns the audio session ID.
| |||||||||||
Returns the audio recording source.
| |||||||||||
Returns the configured channel configuration.
| |||||||||||
Returns the configured number of channels.
| |||||||||||
Returns the minimum buffer size required for the successful creation of an AudioRecord
object.
| |||||||||||
Returns the notification marker position expressed in frames.
| |||||||||||
Returns the notification update period expressed in frames.
| |||||||||||
Returns the recording state of the AudioRecord instance.
| |||||||||||
Returns the configured audio data sample rate in Hz
| |||||||||||
Returns the state of the AudioRecord instance.
| |||||||||||
Reads audio data from the audio hardware for recording into a buffer.
| |||||||||||
Reads audio data from the audio hardware for recording into a buffer.
| |||||||||||
Reads audio data from the audio hardware for recording into a direct buffer.
| |||||||||||
Releases the native AudioRecord resources.
| |||||||||||
Sets the marker position at which the listener is called, if set with
setRecordPositionUpdateListener(OnRecordPositionUpdateListener) or
setRecordPositionUpdateListener(OnRecordPositionUpdateListener, Handler). | |||||||||||
Sets the period at which the listener is called, if set with
setRecordPositionUpdateListener(OnRecordPositionUpdateListener) or
setRecordPositionUpdateListener(OnRecordPositionUpdateListener, Handler). | |||||||||||
Sets the listener the AudioRecord notifies when a previously set marker is reached or
for each periodic record head position update.
| |||||||||||
Sets the listener the AudioRecord notifies when a previously set marker is reached or
for each periodic record head position update.
| |||||||||||
Starts recording from the AudioRecord instance.
| |||||||||||
Starts recording from the AudioRecord instance when the specified synchronization event
occurs on the specified audio session.
| |||||||||||
Stops recording.
| |||||||||||
| Protected Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
Invoked when the garbage collector has detected that this instance is no longer reachable.
| |||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
Denotes a generic operation failure.
Denotes a failure due to the use of an invalid value.
Denotes a failure due to the improper use of a method.
indicates AudioRecord recording state is recording
indicates AudioRecord recording state is not recording
indicates AudioRecord state is ready to be used
indicates AudioRecord state is not successfully initialized.
Denotes a successful operation.
Class constructor.
| audioSource | the recording source. See MediaRecorder.AudioSource for
recording source definitions. |
|---|---|
| sampleRateInHz | the sample rate expressed in Hertz. 44100Hz is currently the only rate that is guaranteed to work on all devices, but other rates such as 22050, 16000, and 11025 may work on some devices. |
| channelConfig | describes the configuration of the audio channels.
See CHANNEL_IN_MONO and
CHANNEL_IN_STEREO. CHANNEL_IN_MONO is guaranteed
to work on all devices. |
| audioFormat | the format in which the audio data is represented.
See ENCODING_PCM_16BIT and
ENCODING_PCM_8BIT |
| bufferSizeInBytes | the total size (in bytes) of the buffer where audio data is written
to during the recording. New audio data can be read from this buffer in smaller chunks
than this size. See getMinBufferSize(int, int, int) to determine the minimum
required buffer size for the successful creation of an AudioRecord instance. Using values
smaller than getMinBufferSize() will result in an initialization failure. |
| IllegalArgumentException |
|---|
Returns the configured audio data format. See ENCODING_PCM_16BIT
and ENCODING_PCM_8BIT.
Returns the audio session ID.
Returns the configured channel configuration.
See CHANNEL_IN_MONO
and CHANNEL_IN_STEREO.
Returns the minimum buffer size required for the successful creation of an AudioRecord object. Note that this size doesn't guarantee a smooth recording under load, and higher values should be chosen according to the expected frequency at which the AudioRecord instance will be polled for new data.
| sampleRateInHz | the sample rate expressed in Hertz. |
|---|---|
| channelConfig | describes the configuration of the audio channels.
See CHANNEL_IN_MONO and
CHANNEL_IN_STEREO |
| audioFormat | the format in which the audio data is represented.
See ENCODING_PCM_16BIT. |
ERROR_BAD_VALUE if the recording parameters are not supported by the
hardware, or an invalid parameter was passed,
or ERROR if the implementation was unable to query the hardware for its
output properties,
or the minimum buffer size expressed in bytes.Returns the notification marker position expressed in frames.
Returns the notification update period expressed in frames.
Returns the recording state of the AudioRecord instance.
Returns the configured audio data sample rate in Hz
Returns the state of the AudioRecord instance. This is useful after the AudioRecord instance has been created to check if it was initialized properly. This ensures that the appropriate hardware resources have been acquired.
Reads audio data from the audio hardware for recording into a buffer.
| audioData | the array to which the recorded audio data is written. |
|---|---|
| offsetInShorts | index in audioData from which the data is written expressed in shorts. |
| sizeInShorts | the number of requested shorts. |
ERROR_INVALID_OPERATION
if the object wasn't properly initialized, or ERROR_BAD_VALUE if
the parameters don't resolve to valid data and indexes.
The number of shorts will not exceed sizeInShorts.
Reads audio data from the audio hardware for recording into a buffer.
| audioData | the array to which the recorded audio data is written. |
|---|---|
| offsetInBytes | index in audioData from which the data is written expressed in bytes. |
| sizeInBytes | the number of requested bytes. |
ERROR_INVALID_OPERATION
if the object wasn't properly initialized, or ERROR_BAD_VALUE if
the parameters don't resolve to valid data and indexes.
The number of bytes will not exceed sizeInBytes.
Reads audio data from the audio hardware for recording into a direct buffer. If this buffer is not a direct buffer, this method will always return 0.
| audioBuffer | the direct buffer to which the recorded audio data is written. |
|---|---|
| sizeInBytes | the number of requested bytes. |
ERROR_INVALID_OPERATION
if the object wasn't properly initialized, or ERROR_BAD_VALUE if
the parameters don't resolve to valid data and indexes.
The number of bytes will not exceed sizeInBytes.
Releases the native AudioRecord resources. The object can no longer be used and the reference should be set to null after a call to release()
Sets the marker position at which the listener is called, if set with
setRecordPositionUpdateListener(OnRecordPositionUpdateListener) or
setRecordPositionUpdateListener(OnRecordPositionUpdateListener, Handler).
| markerInFrames | marker position expressed in frames |
|---|
SUCCESS, ERROR_BAD_VALUE,
ERROR_INVALID_OPERATION
Sets the period at which the listener is called, if set with
setRecordPositionUpdateListener(OnRecordPositionUpdateListener) or
setRecordPositionUpdateListener(OnRecordPositionUpdateListener, Handler).
| periodInFrames | update period expressed in frames |
|---|
SUCCESS, ERROR_INVALID_OPERATION
Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update. Use this method to receive AudioRecord events in the Handler associated with another thread than the one in which you created the AudioTrack instance.
| handler | the Handler that will receive the event notification messages. |
|---|
Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update.
Starts recording from the AudioRecord instance.
| IllegalStateException |
|---|
Starts recording from the AudioRecord instance when the specified synchronization event occurs on the specified audio session.
| syncEvent | event that triggers the capture. |
|---|
| IllegalStateException | |
| IllegalStateException |
Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.
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.