Resources
Module: Audio / Audio Definitions / Audio Output
Functions
| Name | |
|---|---|
| MLResult | MLAudioCreateLoadedResource(int file, bool dynamic_decode, MLAudioResourceDiscardedCallback callback, void context, MLHandle out_resource) Creates a new Loaded Resource that references a loaded audio file. |
| MLResult | MLAudioCreateStreamedResource(int file, MLAudioResourceDiscardedCallback callback, void context, MLHandle out_resource) Creates a new audio resource that references a streamed audio file. |
| MLResult | MLAudioCheckResource(MLHandle resource, bool * out_is_ready) Queries whether a Loaded or Streamed Resource has been discarded due to system limits. |
| MLResult | MLAudioGetResourceSize(MLHandle resource, uint32_t * out_size_in_bytes) Queries the size of the memory footprint for a Loaded Resource. |
| MLResult | MLAudioRefreshResource(MLHandle resource, int file) Refreshes a resource whose data was discarded due to system limits. |
| MLResult | MLAudioDestroyResource(MLHandle resource) Destroys a previously created audio resource. |
| MLResult | MLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle) Creates a sound output referencing a Loaded Audio Resource. |
| MLResult | MLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle) Creates a sound output referencing a Streamed Audio Resource. |
Detailed Description
RESOURCES.
Functions Documentation
MLAudioCreateLoadedResource
MLResult MLAudioCreateLoadedResource(
int file,
bool dynamic_decode,
MLAudioResourceDiscardedCallback callback,
void * context,
MLHandle * out_resource
)
Creates a new Loaded Resource that references a loaded audio file.
Parameters
| int | file | File descriptor specifying the audio file. |
| bool | dynamic_decode | Not currently implemented. |
| MLAudioResourceDiscardedCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
| MLHandle * | out_resource | 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 resource. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_FileNotRecognized | Failed because file was not recognized. |
| 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_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Loaded Audio Resources provide the ability to preload audio files that stay in memory, so a single audio file can be played by multiple sound outputs. The resource can be used to create a sound output by passing the resource ID (MLHandle) provided by this function via out_resource to MLAudioCreateSoundWithLoadedResource. 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.
The audio data for a Loaded Resource can be discarded by the system due to memory limits. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling MLAudioRefreshResource. MLAudioResourceDiscardedCallback is an optional argument to this function that will result in a callback to inform the client if the audio data for this Loaded Resource has been discarded due to system limits.
MLAudioCreateStreamedResource
MLResult MLAudioCreateStreamedResource(
int file,
MLAudioResourceDiscardedCallback callback,
void * context,
MLHandle * out_resource
)
Creates a new audio resource that references a streamed audio file.
Parameters
| int | file | File descriptor specifying the audio file. |
| MLAudioResourceDiscardedCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
| MLHandle * | out_resource | 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 resource. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Streamed Audio Resources provide the ability to pre-establish a persistent reference to an audio file (in the form of a file descriptor), so a single audio file can be streamed by multiple sound outputs, with audio data streamed from flash memory into main memory in chunks during playback. The resource can be used to create a sound output by passing the resource ID (MLHandle) provided by this function via out_resource to MLAudioCreateSoundWithStreamedResource. 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.
The File Descriptor for a Streamed Resource can be discarded by the system due to a limited number of available File Descriptors. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling MLAudioRefreshResource. MLAudioResourceDiscardedCallback is an optional argument to this function that will result in a callback to inform the client if the File Descriptor for this Streamed Resource has been discarded due to system limits.
MLAudioCheckResource
MLResult MLAudioCheckResource(
MLHandle resource,
bool * out_is_ready
)
Queries whether a Loaded or Streamed Resource has been discarded due to system limits.
Parameters
| MLHandle | resource | MLHandle of the resource. |
| bool * | out_is_ready | If true, the resource is ready to use. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully reported the value. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
The audio data for a Loaded Resource can be discarded by the system due to memory limits. The File Descriptor for a Streamed Resource can be discarded by the system due to a limited number of available File Descriptors. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling MLAudioRefreshResource.
MLAudioGetResourceSize
MLResult MLAudioGetResourceSize(
MLHandle resource,
uint32_t * out_size_in_bytes
)
Queries the size of the memory footprint for a Loaded Resource.
Parameters
| MLHandle | resource | MLHandle of the resource. |
| uint32_t * | out_size_in_bytes | The retrieved size of the memory footprint. |
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_NotImplemented | Failed because Streamed Resource was queried. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
For Loaded Resources using compressed file formats, the data is decompressed when loaded, and the size of the decompressed data is reported. For Streamed Resources, this call will fail with MLAudioResult_NotImplemented.
API Level:
- 7
MLAudioRefreshResource
MLResult MLAudioRefreshResource(
MLHandle resource,
int file
)
Refreshes a resource whose data was discarded due to system limits.
Parameters
| MLHandle | resource | MLHandle of the resource. |
| int | file | File descriptor specifying the audio file. |
Returns
| MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully refreshed resource. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_FileNotRecognized | Failed because file was not recognized. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidBitsPerSample | Failed due to 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 invalid valid bits. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
| MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
The audio data for a Loaded Resource can be discarded by the system due to memory limits. The File Descriptor for a Streamed Resource can be discarded by the system due to a limited number of available File Descriptors. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling this function.
MLAudioDestroyResource
MLResult MLAudioDestroyResource(
MLHandle resource
)
Destroys a previously created audio resource.
Parameters
| MLHandle | resource | MLHandle of the resource. |
Returns
| MLResult | MLResult_Ok | Successfully destroyed resource. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
Even if a resource is currently in use it will be destroyed immediately. If a sound output is playing the resource, the sound will be stopped and a corresponding Sound Event callback of type MLAudioSoundEvent_ResourceDestroyed will be issued.
MLAudioCreateSoundWithLoadedResource
MLResult MLAudioCreateSoundWithLoadedResource(
MLHandle resource,
bool auto_destroy,
MLHandle * out_handle
)
Creates a sound output referencing a Loaded Audio Resource.
Parameters
| MLHandle | resource | MLHandle of the Loaded Resource. |
| 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 input. |
| 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_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
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.
MLAudioCreateSoundWithStreamedResource
MLResult MLAudioCreateSoundWithStreamedResource(
MLHandle resource,
bool auto_destroy,
MLHandle * out_handle
)
Creates a sound output referencing a Streamed Audio Resource.
Parameters
| MLHandle | resource | MLHandle of the streamed audio resource. |
| 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_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_InvalidBufferSize | Failed due to an invalid buffer size. |
| MLResult | MLAudioResult_ResourceDiscarded | Failed because file was closed. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
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.