Allocation
Module: Audio / Audio Definitions / Audio Output
Functions
| Name | |
|---|---|
| MLResult | MLAudioCreateSoundWithLoadedFile(int file, bool auto_destroy, bool dynamic_decode, MLHandle * out_handle) Creates a sound output that uses audio data loaded from a file descriptor into memory. |
| MLResult | MLAudioCreateSoundWithStreamedFile(int file, bool auto_destroy, MLHandle * out_handle) Creates a sound output that streams audio data from flash memory via a file descriptor. |
| MLResult | MLAudioCreateSoundWithBufferedOutput(const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle) Creates a sound output that plays a client-provided stream of buffered audio data. |
| MLResult | MLAudioDestroySound(MLHandle handle) Destroys a previously created sound output. |
Detailed Description
ALLOCATION.
Functions Documentation
MLAudioCreateSoundWithLoadedFile
MLResult MLAudioCreateSoundWithLoadedFile(
int file,
bool auto_destroy,
bool dynamic_decode,
MLHandle * out_handle
)
Creates a sound output that uses audio data loaded from a file descriptor into memory.
Parameters
| int | file | File descriptor specifying the audio file. |
| bool | auto_destroy | If true, the sound output is destroyed when playback reaches end of file. |
| bool | dynamic_decode | Not currently implemented. |
| 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 output. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_FileNotRecognized | Failed because file was not recognized. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidBitsPerSample | Failed due to invalid bits per sample. |
| MLResult | MLAudioResult_InvalidChannelCount | Failed due to an invalid channel count. |
| MLResult | MLAudioResult_InvalidSampleRate | Failed due to an invalid sample rate. |
| MLResult | MLAudioResult_InvalidValidBits | Failed due to invalid valid bits. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
Once created, the sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound. Files can be of type WAV, FLAC, MP3 and OGG, can be stereo or mono, can have 16kHz to 48kHz sample rate, and can be represented as 16-bit, 24-bit, and 32-bit integers or 32-bit floats.
MLAudioCreateSoundWithStreamedFile
MLResult MLAudioCreateSoundWithStreamedFile(
int file,
bool auto_destroy,
MLHandle * out_handle
)
Creates a sound output that streams audio data from flash memory via a file descriptor.
Parameters
| int | file | File descriptor specifying the audio file. |
| bool | auto_destroy | If true, the sound output is destroyed when playback reaches end of file. |
| 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 output. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_FileNotFound | Failed because file was missing. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_ResourceDiscarded | Failed because file was closed. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
Once created, the sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound. Files can be of type WAV, FLAC, MP3 and OGG, can be stereo or mono, can have 16kHz to 48kHz sample rate, and can be represented as 16-bit, 24-bit, and 32-bit integers or 32-bit floats.
MLAudioCreateSoundWithBufferedOutput
MLResult MLAudioCreateSoundWithBufferedOutput(
const MLAudioBufferFormat * format,
uint32_t buffer_size_in_bytes,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)
Creates a sound output that plays a client-provided stream of buffered audio data.
Parameters
| const MLAudioBufferFormat * | format | MLAudioBufferFormat struct specifying the format properties. |
| uint32_t | buffer_size_in_bytes | Requested size in bytes for each of the output 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 output. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidSampleRate | Failed due to an invalid sample rate. |
| 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 invalid valid bits. |
Required Permissions:
- None
The sound output allocates a double buffer that the caller is responsible for continuously filling with audio data. This can be done within a callback of type MLAudioBufferCallback that is set via the 'callback' argument or by polling MLAudioGetOutputBuffer if no callback is set. When polling, a return value of MLAudioResult_BufferNotReady indicates the sound output is not ready and the caller must wait. Setting the 'buffer_size_in_bytes' argument to 0 will utilize the system-preferred buffer size. Double-buffers can optionally be pre-filled prior to starting the sound. Once created, a sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound. Audio data can be mono, stereo, 4-channel (ambisonics), 6-channel (5.1), 8-channel (7.1), or 12-channel (7.1.4). It can have 16kHz to 48kHz sample rate, and must be 16-bit integer.
API Level:
- 7
MLAudioDestroySound
MLResult MLAudioDestroySound(
MLHandle handle
)
Destroys a previously created sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
Returns
| MLResult | MLResult_Ok | Successfully destroyed sound output. |
| MLResult | MLResult_UnspecifiedFailure | Failed to destroy sound output due to an unknown error. |
| MLResult | MLAudioResult_HandleNotFound | Failed to destroy sound output due to a missing handle. |
| MLResult | MLAudioResult_NotImplemented | Failed to destroy sound output because feature has not been implemented yet. |
Required Permissions:
- None