Buffering
Module: Audio / Audio Definitions / Audio Output / Audio Input
Functions
| Name | |
|---|---|
| MLResult | MLAudioGetBufferedInputDefaults(uint32_t channel_count, uint32_t samples_per_second, MLAudioBufferFormat out_format, uint32_t out_recommended_size_in_bytes, uint32_t * out_min_size_in_bytes) Queries the minimum and recommended settings for buffered sound inputs. |
| MLResult | MLAudioGetBufferedInputLatency(MLHandle handle, float * out_latency_in_msec) Queries the latency for a sound input. |
| MLResult | MLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer * out_buf) Retrieves a full buffer of audio data from a sound input. |
| MLResult | MLAudioReleaseInputBuffer(MLHandle handle) Releases an input buffer once it has been consumed. |
Detailed Description
BUFFERING.
Functions Documentation
MLAudioGetBufferedInputDefaults
MLResult MLAudioGetBufferedInputDefaults(
uint32_t channel_count,
uint32_t samples_per_second,
MLAudioBufferFormat * out_format,
uint32_t * out_recommended_size_in_bytes,
uint32_t * out_min_size_in_bytes
)
Queries the minimum and recommended settings for buffered sound inputs.
Parameters
| uint32_t | channel_count | Number of audio channels. |
| uint32_t | samples_per_second | Sample rate for the buffered input. |
| MLAudioBufferFormat * | out_format | MLAudioBufferFormat struct to be filled with recommended format properties. |
| uint32_t * | out_recommended_size_in_bytes | Retrieved recommended size. |
| uint32_t * | out_min_size_in_bytes | Retrieved minimum allowable size. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully retrieved the properties. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InvalidChannelCount | Failed due to an invalid channel count. |
| MLResult | MLAudioResult_InvalidSampleRate | Failed due to an invalid sample rate. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
This function is typically called before one of the MLAudioCreateInput... calls. It queries the minimum and recommended buffer sizes for the specified settings of channel count and sample rate.
API Level:
- 7
MLAudioGetBufferedInputLatency
MLResult MLAudioGetBufferedInputLatency(
MLHandle handle,
float * out_latency_in_msec
)
Queries the latency for a sound input.
Parameters
| MLHandle | handle | MLHandle of the sound input. |
| float * | out_latency_in_msec | Retrieved latency in milliseconds. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully retrieved the value. |
| 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. |
| MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
The latency for a sound input is the time between when a sound is picked up at the microphone and when the corresponding audio becomes available via a call to MLAudioGetInputBuffer.
API Level:
- 7
MLAudioGetInputBuffer
MLResult MLAudioGetInputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)
Retrieves a full buffer of audio data from a sound input.
Parameters
| MLHandle | handle | MLHandle of the sound input. |
| MLAudioBuffer * | out_buf | Retrieved MLAudioBuffer struct pointer to buffer for reading audio data. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully retrieved the buffer. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_BufferNotReady | Failed because buffer was not ready. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
| MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
Standard usage is to call this function by polling or within a callback of type MLAudioBufferCallback registered with one of the MLAudioCreateInput... calls. This call returns MLAudioResult_BufferNotReady if a buffer is not available for reading audio data, informing the caller to wait. Once consumed, the buffer must be released by calling MLAudioReleaseInputBuffer.
API Level:
- 7
MLAudioReleaseInputBuffer
MLResult MLAudioReleaseInputBuffer(
MLHandle handle
)
Releases an input buffer once it has been consumed.
Parameters
| MLHandle | handle | MLHandle of the sound input. |
Returns
| MLResult | MLResult_Ok | Successfully released the buffer. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_BufferNotReady | Failed because buffer was not ready. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
| MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
After consuming a buffer retrieved by MLAudioGetInputBuffer, the buffer must be released using this function in order to indicate that the buffer has been consumed and can now be refilled.
API Level:
- 7