Buffering
Module: Audio / Audio Definitions / Audio Output / Acoustics
Functions
| Name | |
|---|---|
| MLResult | MLAudioGetBufferedOutputDefaults(uint32_t channel_count, uint32_t samples_per_second, float max_pitch_change, 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 outputs. |
| MLResult | MLAudioGetBufferedOutputLatency(MLHandle handle, float * out_latency_in_msec) Queries the latency for a buffered sound output. |
| MLResult | MLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t * out_frames_played) Queries the number of audio frames played by a buffered output. |
| MLResult | MLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer * out_buf) Retrieves an empty buffer for writing audio data for a buffered sound output. |
| MLResult | MLAudioReleaseOutputBuffer(MLHandle handle) Releases a filled audio output buffer for playback through a buffered sound output. |
Detailed Description
BUFFERING.
Functions Documentation
MLAudioGetBufferedOutputDefaults
MLResult MLAudioGetBufferedOutputDefaults(
uint32_t channel_count,
uint32_t samples_per_second,
float max_pitch_change,
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 outputs.
Parameters
| uint32_t | channel_count | Number of audio channels. |
| uint32_t | samples_per_second | Sample rate for the buffered output. |
| float | max_pitch_change | Top pitch (1.0 - 2.0) for this sound output. |
| 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_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 MLAudioCreateSoundWithBufferedOutput. It queries the minimum and recommended buffer sizes for the specified settings of channel count, sample rate, and 'max pitch change'. The max pitch change parameter determines the additional buffer size required to support pitch values greater than 1. Applying a pitch change to a buffered output that is greater than the specified max pitch change can lead to undesirable results.
API Level:
- 7
MLAudioGetBufferedOutputLatency
MLResult MLAudioGetBufferedOutputLatency(
MLHandle handle,
float * out_latency_in_msec
)
Queries the latency for a buffered sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| 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 buffered sound output is the time between when a buffer is enqueued via MLAudioReleaseOutputBuffer and when the corresponding audio is heard from the active audio output device. Note that output latency may change depending on which output device is active (for example, Bluetooth earbuds typically add latency compared to the built-in speakers in the headset).
API Level:
- 7
MLAudioGetBufferedOutputFramesPlayed
MLResult MLAudioGetBufferedOutputFramesPlayed(
MLHandle handle,
uint64_t * out_frames_played
)
Queries the number of audio frames played by a buffered output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| uint64_t * | out_frames_played | Retrieved number of audio frames played. |
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. |
Required Permissions:
- None
This call queries the number of audio frames played by a buffered output since the last call to MLAudioStartSound. A subsequent call to MLAudioStartSound sets the count back to 0.
API Level:
- 7
MLAudioGetOutputBuffer
MLResult MLAudioGetOutputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)
Retrieves an empty buffer for writing audio data for a buffered sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| MLAudioBuffer * | out_buf | Retrieved MLAudioBuffer struct pointer to buffer for writing 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_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 MLAudioCreateSoundWithBufferedOutput. This call returns MLAudioResult_BufferNotReady if a buffer is not available for writing audio data, informing the caller to wait. Once filled, the buffer must be released by calling MLAudioReleaseOutputBuffer.
API Level:
- 7
MLAudioReleaseOutputBuffer
MLResult MLAudioReleaseOutputBuffer(
MLHandle handle
)
Releases a filled audio output buffer for playback through a buffered sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
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 filling a buffer retrieved by MLAudioGetOutputBuffer, the buffer must be released using this function in order to be played through a sound output.
API Level:
- 7