AudioRecord

Kotlin |Java

open class AudioRecord : AudioRecordingMonitor, AudioRouting, MicrophoneDirection

kotlin.Any
↳	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(java.nio.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.

Applications creating an AudioRecord instance need android.Manifest.permission#RECORD_AUDIO or the Builder will throw java.lang.UnsupportedOperationException on build(), and the constructor will return an instance in state STATE_UNINITIALIZED.

Summary

Nested classes
open	`Builder` Builder class for `AudioRecord` objects.
	`MetricsConstants`
abstract	`OnRecordPositionUpdateListener` Interface definition for a callback to be invoked when an AudioRecord has reached a notification marker set by `AudioRecord.setNotificationMarkerPosition(int)` or for periodic updates on the progress of the record head, as set by `AudioRecord.setPositionNotificationPeriod(int)`.
abstract	`OnRoutingChangedListener` Defines the interface by which applications can receive notifications of routing changes for the associated `AudioRecord`.

Constants
static Int	`ERROR` Denotes a generic operation failure.
static Int	`ERROR_BAD_VALUE` Denotes a failure due to the use of an invalid value.
static Int	`ERROR_DEAD_OBJECT` An error code indicating that the object reporting it is no longer valid and needs to be recreated.
static Int	`ERROR_INVALID_OPERATION` Denotes a failure due to the improper use of a method.
static Int	`READ_BLOCKING` The read mode indicating the read operation will block until all data requested has been read.
static Int	`READ_NON_BLOCKING` The read mode indicating the read operation will return immediately after reading as much audio data as possible without blocking.
static Int	`RECORDSTATE_RECORDING` indicates AudioRecord recording state is recording
static Int	`RECORDSTATE_STOPPED` indicates AudioRecord recording state is not recording
static Int	`STATE_INITIALIZED` indicates AudioRecord state is ready to be used
static Int	`STATE_UNINITIALIZED` indicates AudioRecord state is not successfully initialized.
static Int	`SUCCESS` Denotes a successful operation.

Inherited constants

From class MicrophoneDirection

`Int`	`MIC_DIRECTION_AWAY_FROM_USER` Optimize capture for audio coming from the side of the device pointing away from the user. In the typical case, a device with a single screen, screen-side camera/microphone and non-screen-side camera/microphone, this will be the non-screen side. For a different device geometry, it is the side for which the expectation is to be facing away from the user. This is the "taking a video of something else" case.
`Int`	`MIC_DIRECTION_EXTERNAL` Optimize capture for audio coming from an off-device microphone.
`Int`	`MIC_DIRECTION_TOWARDS_USER` Optimize capture for audio coming from the side of the device facing the user. In the typical case, a device with a single screen, screen-side camera/microphone and non-screen-side camera/microphone, this will be the screen side (as in a "selfie"). For a different device geometry, it is the side for which the expectation is to be facing the user.
`Int`	`MIC_DIRECTION_UNSPECIFIED` Don't do any directionality processing of the activated microphone(s).

Public constructors
`AudioRecord(audioSource: Int, sampleRateInHz: Int, channelConfig: Int, audioFormat: Int, bufferSizeInBytes: Int)` Class constructor.

Public methods
open Unit	`addOnRoutingChangedListener(listener: AudioRecord.OnRoutingChangedListener!, handler: Handler!)` Adds an `OnRoutingChangedListener` to receive notifications of routing changes on this AudioRecord.
open Unit	`addOnRoutingChangedListener(listener: AudioRouting.OnRoutingChangedListener!, handler: Handler!)` Adds an `AudioRouting.OnRoutingChangedListener` to receive notifications of routing changes on this AudioRecord.
open MutableList<MicrophoneInfo!>!	`getActiveMicrophones()` Returns a lists of `MicrophoneInfo` representing the active microphones.
open AudioRecordingConfiguration?	`getActiveRecordingConfiguration()` Returns the current active audio recording for this audio recorder.
open Int	`getAudioFormat()` Returns the configured audio data encoding.
open Int	`getAudioSessionId()` Returns the audio session ID.
open Int	`getAudioSource()` Returns the audio recording source.
open Int	`getBufferSizeInFrames()` Returns the frame count of the native `AudioRecord` buffer.
open Int	`getChannelConfiguration()` Returns the configured channel position mask.
open Int	`getChannelCount()` Returns the configured number of channels.
open AudioFormat	`getFormat()` Returns the configured `AudioRecord` format.
open LogSessionId	`getLogSessionId()` Returns the `LogSessionId`.
open PersistableBundle!	`getMetrics()` Return Metrics data about the current AudioTrack instance.
open static Int	`getMinBufferSize(sampleRateInHz: Int, channelConfig: Int, audioFormat: Int)` Returns the minimum buffer size required for the successful creation of an AudioRecord object, in byte units.
open Int	`getNotificationMarkerPosition()` Returns the notification marker position expressed in frames.
open Int	`getPositionNotificationPeriod()` Returns the notification update period expressed in frames.
open AudioDeviceInfo!	`getPreferredDevice()` Returns the selected input specified by `setPreferredDevice`.
open Int	`getRecordingState()` Returns the recording state of the AudioRecord instance.
open AudioDeviceInfo!	`getRoutedDevice()` Returns an `AudioDeviceInfo` identifying the current routing of this AudioRecord.
open Int	`getSampleRate()` Returns the configured audio sink sample rate in Hz.
open Int	`getState()` Returns the state of the AudioRecord instance.
open Int	`getTimestamp(outTimestamp: AudioTimestamp, timebase: Int)` Poll for an `AudioTimestamp` on demand.
open Boolean	`isPrivacySensitive()` Returns whether this AudioRecord is marked as privacy sensitive or not.
open Int	`read(audioData: ByteArray, offsetInBytes: Int, sizeInBytes: Int)` Reads audio data from the audio hardware for recording into a byte array.
open Int	`read(audioData: ByteArray, offsetInBytes: Int, sizeInBytes: Int, readMode: Int)` Reads audio data from the audio hardware for recording into a byte array.
open Int	`read(audioData: FloatArray, offsetInFloats: Int, sizeInFloats: Int, readMode: Int)` Reads audio data from the audio hardware for recording into a float array.
open Int	`read(audioBuffer: ByteBuffer, sizeInBytes: Int)` Reads audio data from the audio hardware for recording into a direct buffer.
open Int	`read(audioBuffer: ByteBuffer, sizeInBytes: Int, readMode: Int)` Reads audio data from the audio hardware for recording into a direct buffer.
open Int	`read(audioData: ShortArray, offsetInShorts: Int, sizeInShorts: Int)` Reads audio data from the audio hardware for recording into a short array.
open Int	`read(audioData: ShortArray, offsetInShorts: Int, sizeInShorts: Int, readMode: Int)` Reads audio data from the audio hardware for recording into a short array.
open Unit	`registerAudioRecordingCallback(executor: Executor, cb: AudioManager.AudioRecordingCallback)` Register a callback to be notified of audio capture changes via a `AudioManager.AudioRecordingCallback`.
open Unit	`release()` Releases the native AudioRecord resources.
open Unit	`removeOnRoutingChangedListener(listener: AudioRecord.OnRoutingChangedListener!)` Removes an `OnRoutingChangedListener` which has been previously added to receive rerouting notifications.
open Unit	`removeOnRoutingChangedListener(listener: AudioRouting.OnRoutingChangedListener!)` Removes an `AudioRouting.OnRoutingChangedListener` which has been previously added to receive rerouting notifications.
open Unit	`setLogSessionId(logSessionId: LogSessionId)` Sets a `LogSessionId` instance to this AudioRecord for metrics collection.
open Int	`setNotificationMarkerPosition(markerInFrames: Int)` Sets the marker position at which the listener is called, if set with `setRecordPositionUpdateListener(android.media.AudioRecord.OnRecordPositionUpdateListener)` or `setRecordPositionUpdateListener(android.media.AudioRecord.OnRecordPositionUpdateListener,android.os.Handler)`.
open Int	`setPositionNotificationPeriod(periodInFrames: Int)` Sets the period at which the listener is called, if set with `setRecordPositionUpdateListener(android.media.AudioRecord.OnRecordPositionUpdateListener)` or `setRecordPositionUpdateListener(android.media.AudioRecord.OnRecordPositionUpdateListener,android.os.Handler)`.
open Boolean	`setPreferredDevice(deviceInfo: AudioDeviceInfo!)` Specifies an audio device (via an `AudioDeviceInfo` object) to route the input to this AudioRecord.
open Boolean	`setPreferredMicrophoneDirection(direction: Int)` Specifies the logical microphone (for processing).
open Boolean	`setPreferredMicrophoneFieldDimension(zoom: Float)` Specifies the zoom factor (i.e. the field dimension) for the selected microphone (for processing).
open Unit	`setRecordPositionUpdateListener(listener: AudioRecord.OnRecordPositionUpdateListener!)` Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update.
open Unit	`setRecordPositionUpdateListener(listener: AudioRecord.OnRecordPositionUpdateListener!, handler: Handler!)` Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update.
open Unit	`startRecording()` Starts recording from the AudioRecord instance.
open Unit	`startRecording(syncEvent: MediaSyncEvent!)` Starts recording from the AudioRecord instance when the specified synchronization event occurs on the specified audio session.
open Unit	`stop()` Stops recording.
open Unit	`unregisterAudioRecordingCallback(cb: AudioManager.AudioRecordingCallback)` Unregister an audio recording callback previously registered with `registerAudioRecordingCallback(java.util.concurrent.Executor,android.media.AudioManager.AudioRecordingCallback)`.

Protected methods
open Unit	`finalize()`

Parameters
`audioSource`	Int: the recording source. See `MediaRecorder.AudioSource` for the recording source definitions.
`sampleRateInHz`	Int: 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. `AudioFormat.SAMPLE_RATE_UNSPECIFIED` means to use a route-dependent value which is usually the sample rate of the source. `getSampleRate()` can be used to retrieve the actual sample rate chosen.
`channelConfig`	Int: describes the configuration of the audio channels. See `AudioFormat.CHANNEL_IN_MONO` and `AudioFormat.CHANNEL_IN_STEREO`. `AudioFormat.CHANNEL_IN_MONO` is guaranteed to work on all devices.
`audioFormat`	Int: the format in which the audio data is to be returned. See `AudioFormat.ENCODING_PCM_8BIT`, `AudioFormat.ENCODING_PCM_16BIT`, and `AudioFormat.ENCODING_PCM_FLOAT`.
`bufferSizeInBytes`	Int: 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.

Parameters
`listener`	AudioRecord.OnRoutingChangedListener!: The `OnRoutingChangedListener` interface to receive notifications of rerouting events.
`handler`	Handler!: Specifies the `Handler` object for the thread on which to execute the callback. If `null`, the `Handler` associated with the main `Looper` will be used.

Parameters
`listener`	AudioRouting.OnRoutingChangedListener!: The `AudioRouting.OnRoutingChangedListener` interface to receive notifications of rerouting events.
`handler`	Handler!: Specifies the `Handler` object for the thread on which to execute the callback. If `null`, the `Handler` associated with the main `Looper` will be used.

Parameters
`outTimestamp`	AudioTimestamp: a caller provided non-null AudioTimestamp instance, which is updated with the AudioRecord frame delivery information upon success.
`timebase`	Int: one of `AudioTimestamp.TIMEBASE_BOOTTIME` or `AudioTimestamp.TIMEBASE_MONOTONIC`, used to select the clock for the AudioTimestamp time. Value is `android.media.AudioTimestamp#TIMEBASE_MONOTONIC`, or `android.media.AudioTimestamp#TIMEBASE_BOOTTIME`

Parameters
`audioData`	ByteArray: the array to which the recorded audio data is written. This value cannot be `null`.
`offsetInBytes`	Int: index in audioData from which the data is written expressed in bytes.
`sizeInBytes`	Int: the number of requested bytes.

Parameters
`audioData`	FloatArray: the array to which the recorded audio data is written. This value cannot be `null`.
`offsetInFloats`	Int: index in audioData from which the data is written. Must not be negative, or cause the data access to go out of bounds of the array.
`sizeInFloats`	Int: the number of requested floats. Must not be negative, or cause the data access to go out of bounds of the array.
`readMode`	Int: one of `READ_BLOCKING`, `READ_NON_BLOCKING`. With `READ_BLOCKING`, the read will block until all the requested data is read. With `READ_NON_BLOCKING`, the read will return immediately after reading as much audio data as possible without blocking. Value is `android.media.AudioRecord#READ_BLOCKING`, or `android.media.AudioRecord#READ_NON_BLOCKING`

Parameters
`audioBuffer`	ByteBuffer: the direct buffer to which the recorded audio data is written. Data is written to audioBuffer.position(). This value cannot be `null`.
`sizeInBytes`	Int: the number of requested bytes. It is recommended but not enforced that the number of bytes requested be a multiple of the frame size (sample size in bytes multiplied by the channel count).

Parameters
`audioData`	ShortArray: the array to which the recorded audio data is written. This value cannot be `null`.
`offsetInShorts`	Int: index in audioData to which the data is written expressed in shorts. Must not be negative, or cause the data access to go out of bounds of the array.
`sizeInShorts`	Int: the number of requested shorts. Must not be negative, or cause the data access to go out of bounds of the array.

Parameters
`executor`	Executor: `Executor` to handle the callbacks. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`cb`	AudioManager.AudioRecordingCallback: non-null callback to register

Parameters
`listener`	AudioRecord.OnRecordPositionUpdateListener!:
`handler`	Handler!: the Handler that will receive the event notification messages.

AudioRecord

Summary

Constants

ERROR

ERROR_BAD_VALUE

ERROR_DEAD_OBJECT

ERROR_INVALID_OPERATION

READ_BLOCKING

READ_NON_BLOCKING

RECORDSTATE_RECORDING

RECORDSTATE_STOPPED

STATE_INITIALIZED

STATE_UNINITIALIZED

SUCCESS

Public constructors

AudioRecord

Public methods

addOnRoutingChangedListener

addOnRoutingChangedListener

getActiveMicrophones

getActiveRecordingConfiguration

getAudioFormat

getAudioSessionId

getAudioSource

getBufferSizeInFrames

getChannelConfiguration

getChannelCount

getFormat

getLogSessionId

getMetrics

getMinBufferSize

getNotificationMarkerPosition

getPositionNotificationPeriod

getPreferredDevice

getRecordingState

getRoutedDevice

getSampleRate

getState

getTimestamp

isPrivacySensitive

read

read

read

read

read

read

read

registerAudioRecordingCallback

release

removeOnRoutingChangedListener

removeOnRoutingChangedListener

setLogSessionId

setNotificationMarkerPosition

setPositionNotificationPeriod

setPreferredDevice

setPreferredMicrophoneDirection

setPreferredMicrophoneFieldDimension

setRecordPositionUpdateListener

setRecordPositionUpdateListener

startRecording

startRecording

stop

unregisterAudioRecordingCallback

Protected methods

finalize