Allocation
Module: Audio / Audio Definitions / Audio Output / Audio Input
Functions
| Name | |
|---|---|
| MLResult | MLAudioCreateInputFromMicCapture(MLAudioMicCaptureType mic_capture_type, const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle) Creates a new sound input that provides audio from the wearable microphones. |
| MLResult | MLAudioCreateInputFromVirtualCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void context, MLHandle * out_handle) Creates a new sound input that provides a virtual capture stream. |
| MLResult | MLAudioCreateInputFromMixedCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void context, MLHandle * out_handle) Creates a new sound input that provides a mixed capture stream. |
| MLResult | MLAudioDestroyInput(MLHandle handle) Destroys a sound input. |
Detailed Description
ALLOCATION.
Functions Documentation
MLAudioCreateInputFromMicCapture
MLResult MLAudioCreateInputFromMicCapture(
MLAudioMicCaptureType mic_capture_type,
const MLAudioBufferFormat * format,
uint32_t buffer_size_in_bytes,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)
Creates a new sound input that provides audio from the wearable microphones.
Parameters
| MLAudioMicCaptureType | mic_capture_type | MLAudioMicCaptureType enum specifying the type of mic capture created. |
| const MLAudioBufferFormat * | format | MLAudioBufferFormat struct specifying the format properties. |
| uint32_t | buffer_size | Requested size in bytes for each of the two stream buffers. |
| MLAudioBufferCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
| MLHandle * | out_handle | MLHandle to be used in subsequent calls. |
Returns
| MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully created a sound input. |
| MLResult | MLResult_PermissionDenied | Failed due to lack of permission. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidBitsPerSample | Failed due to an invalid bits per sample. |
| MLResult | MLAudioResult_InvalidBufferSize | Failed due to an invalid buffer size. |
| MLResult | MLAudioResult_InvalidChannelCount | Failed due to an invalid channel count. |
| MLResult | MLAudioResult_InvalidSampleFormat | Failed due to an invalid sample format. |
| MLResult | MLAudioResult_InvalidSampleRate | Failed due to an invalid sample rate. |
| MLResult | MLAudioResult_InvalidValidBits | Failed due to an invalid valid bits per sample. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- android.permission.RECORD_AUDIO (protection level: dangerous)
The various mic capture streams represent different configurations of the input from the wearable microphones, intended for different purposes. The 'format' argument must be populated with the correct settings for the mic capture type being requested:
MLAudioMicCaptureType_VoiceComm is intended for remote communications, and uses a channel count of 1 and a sample rate of 16,000.
MLAudioMicCaptureType_VoiceCapture is intended for device-local applications involving user voice, and uses a channel count of 1 and a sample rate of 48,000.
MLAudioMicCaptureType_WorldCapture provides a stereo capture of the user's physical environment, and uses a channel count of 2 and a sample rate of 48,000.
MLAudioMicCaptureType_RawMicsAndAECRef provides a 6-channel capture comprising all 4 mics (unprocessed) plus the AEC reference signal from the amplifier, and uses a channel count of 6 and a sample rate of 48,000.
After creation, the input is started by calling MLAudioStartInput. After the input has been started, the next available full buffer is retrieved by calling MLAudioGetInputBuffer. This can be done on a polling basis, or a callback can be set using the 'callback' argument of the present function to notify when a buffer is available. After retrieving and consuming the next available buffer, MLAudioReleaseInputBuffer must be called to indicate that the buffer has been consumed and is ready to be refilled. MLAudioGetInputBuffer and MLAudioReleaseInputBuffer are valid to call within the callback. The 'buffer_size' argument will use the recommended size if 0 is passed in.
API Level:
- 20
MLAudioCreateInputFromVirtualCapture
MLResult MLAudioCreateInputFromVirtualCapture(
const MLAudioBufferFormat * format,
uint32_t buffer_size,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)
Creates a new sound input that provides a virtual capture stream.
Parameters
| const MLAudioBufferFormat * | format | MLAudioBufferFormat struct specifying the format properties. |
| uint32_t | buffer_size | Requested size in bytes of the buffers. |
| MLAudioBufferCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
| MLHandle * | out_handle | MLHandle to be used in subsequent calls. |
Returns
| MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully created sound input. |
| MLResult | MLResult_PermissionDenied | Failed due to lack of permission. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidBitsPerSample | Failed due to an invalid bits per sample. |
| MLResult | MLAudioResult_InvalidBufferSize | Failed due to an invalid buffer size. |
| MLResult | MLAudioResult_InvalidChannelCount | Failed due to an invalid channel count. |
| MLResult | MLAudioResult_InvalidSampleFormat | Failed due to an invalid sample format. |
| MLResult | MLAudioResult_InvalidSampleRate | Failed due to an invalid sample rate. |
| MLResult | MLAudioResult_InvalidValidBits | Failed due to an invalid valid bits per sample. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- android.permission.RECORD_AUDIO (protection level: dangerous)
The Virtual Capture stream is a stereo stream capturing the combined audio output mix of the capture-eligible sounds (typically app-generated) currently being played by the audio rendering engine. The 'format' argument must be populated with the correct settings for virtual capture, which uses a channel count of 2 and a sample rate of 48,000.
After creation, the input is started by calling MLAudioStartInput. After the input has been started, the next available full buffer is retrieved by calling MLAudioGetInputBuffer. This can be done on a polling basis, or a callback can be set using the 'callback' argument of the present function to notify when a buffer is available. After retrieving and consuming the next available buffer, MLAudioReleaseInputBuffer must be called to indicate that the buffer has been consumed and is ready to be refilled. MLAudioGetInputBuffer and MLAudioReleaseInputBuffer are valid to call within the callback. The 'buffer_size' argument will use the recommended size if 0 is passed in.
MLAudioCreateInputFromMixedCapture
MLResult MLAudioCreateInputFromMixedCapture(
const MLAudioBufferFormat * format,
uint32_t buffer_size,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)
Creates a new sound input that provides a mixed capture stream.
Parameters
| const MLAudioBufferFormat * | format | MLAudioBufferFormat struct specifying the format properties. |
| uint32_t | buffer_size | Requested size in bytes of the buffers. |
| MLAudioBufferCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
| MLHandle * | out_handle | MLHandle to be used in subsequent calls. |
Returns
| MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully created sound input. |
| MLResult | MLResult_PermissionDenied | Failed due to lack of permission. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidBitsPerSample | Failed due to an invalid bits per sample. |
| MLResult | MLAudioResult_InvalidBufferSize | Failed due to an invalid buffer size. |
| MLResult | MLAudioResult_InvalidChannelCount | Failed due to an invalid channel count. |
| MLResult | MLAudioResult_InvalidSampleFormat | Failed due to an invalid sample format. |
| MLResult | MLAudioResult_InvalidSampleRate | Failed due to an invalid sample rate. |
| MLResult | MLAudioResult_InvalidValidBits | Failed due to an invalid valid bits per sample. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- android.permission.RECORD_AUDIO (protection level: dangerous)
The Mixed Capture stream is intended for capturing the audible user experience, including both sounds from the physical environment and sounds produced by the device. The stream includes a mix of the 'Virtual Capture' stream, the MLAudioMicCaptureType_VoiceCapture stream, and the MLAudioMicCaptureType_WorldCapture stream. By default the World Capture stream is silent and the other two streams are full volume. These levels can be adjusted by calling MLAudioSetMixedCaptureMix. Independent of the specified MixedCaptureMix, the Voice Capture and World Capture mic signals are scaled on a curve based on the current setting of Master Volume to keep the real and virtual signals in good balance. The Mixed Capture stream uses a channel count of 2 and a sample rate of 48,000.
After creation, the input is started by calling MLAudioStartInput. After the input has been started, the next available full buffer is retrieved by calling MLAudioGetInputBuffer. This can be done on a polling basis, or a callback can be set using the 'callback' argument of the present function to notify when a buffer is available. After retrieving and consuming the next available buffer, MLAudioReleaseInputBuffer must be called to indicate that the buffer has been consumed and is ready to be refilled. MLAudioGetInputBuffer and MLAudioReleaseInputBuffer are valid to call within the callback. The 'buffer_size' argument will use the recommended size if 0 is passed in.
MLAudioDestroyInput
MLResult MLAudioDestroyInput(
MLHandle handle
)
Destroys a sound input.
Parameters
| MLHandle | handle | MLHandle of the sound input. |
Returns
| MLResult | MLResult_Ok | Successfully destroyed a sound input. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None