Control
Module: Audio / Audio Definitions / Audio Output
Functions
| Name | |
|---|---|
| MLResult | MLAudioStartSound(MLHandle handle) Starts playback for a sound output. |
| MLResult | MLAudioStopSound(MLHandle handle) Stops playback for a sound output. |
| MLResult | MLAudioPauseSound(MLHandle handle) Pauses playback for a currently playing sound output. |
| MLResult | MLAudioResumeSound(MLHandle handle) Resumes playback for a currently paused sound output. |
| MLResult | MLAudioGetSoundState(MLHandle handle, MLAudioState * out_state) Queries the playback state of a sound output. |
| MLResult | MLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat * out_format) Queries the audio format of a sound output. |
| MLResult | MLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void * context) Registers a callback for Sound Events relating to a sound output. |
| MLResult | MLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void * context) Registers a callback for media transport events. |
Detailed Description
CONTROL.
Functions Documentation
MLAudioStartSound
MLResult MLAudioStartSound(
MLHandle handle
)
Starts playback for a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
Returns
| MLResult | MLResult_Ok | Sound output is started, or continues if already playing. |
| 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_ResourceDiscarded | Failed because file was closed. |
| MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
Calling this function on a playing sound has no effect and returns success. Calling this function on a paused sound will start the sound output from the beginning. When starting playback for a buffered output stream, the "out_frames_played" counter retrieved by calling MLAudioGetBufferedOutputFramesPlayed is reset to 0.
MLAudioStopSound
MLResult MLAudioStopSound(
MLHandle handle
)
Stops playback for a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
Returns
| MLResult | MLResult_Ok | Sound output is stopped, or remains stopped if already stopped. |
| MLResult | MLResult_UnspecifiedFailure | Failed to stop playback due to an unknown error. |
| MLResult | MLAudioResult_HandleNotFound | Failed to stop playback due to a missing handle. |
| MLResult | MLAudioResult_NotImplemented | Failed to stop playback because feature has not been implemented yet. |
| MLResult | MLAudioResult_ResourceNotFound | Failed to stop playback because resource was not found. |
Required Permissions:
- None
Calling this function on a stopped sound has no effect and returns success.
MLAudioPauseSound
MLResult MLAudioPauseSound(
MLHandle handle
)
Pauses playback for a currently playing sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
Returns
| MLResult | MLResult_Ok | Sound output is paused, or remains paused if already paused. |
| 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
If the sound output is not playing, the pause will fail with MLAudioResult_OperationUnavailable. Calling this function on a paused sound has no effect and returns success.
MLAudioResumeSound
MLResult MLAudioResumeSound(
MLHandle handle
)
Resumes playback for a currently paused sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
Returns
| MLResult | MLResult_Ok | Sound output resumes playing. |
| 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
Calling this function on a paused sound will resume playback from the current position. Calling this function on a playing or stopped sound will fail with MLAudioResult_OperationUnavailable.
MLAudioGetSoundState
MLResult MLAudioGetSoundState(
MLHandle handle,
MLAudioState * out_state
)
Queries the playback state of a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| MLAudioState * | out_state | MLAudioState enum to be filled with the current playback state. |
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_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The MLAudioState enum defines the possible playback states which are Stopped, Playing and Paused.
MLAudioGetSoundFormat
MLResult MLAudioGetSoundFormat(
MLHandle handle,
MLAudioBufferFormat * out_format
)
Queries the audio format of a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| MLAudioBufferFormat * | out_format | MLAudioBufferFormat struct to be filled with the format properties. |
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_NotImplemented | Failed because feature has not been implemented yet. |
| MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
For sound outputs referencing streamed resources, the format is not available until ~100 milliseconds after playback has started.
MLAudioSetSoundEventCallback
MLResult MLAudioSetSoundEventCallback(
MLHandle handle,
MLAudioSoundEventCallback callback,
void * context
)
Registers a callback for Sound Events relating to a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| MLAudioSoundEventCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
Returns
| MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully registered the callback. |
| 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_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Sound outputs generate events as specified in the MLAudioSoundEvent enum, such as when a sound has looped, stopped, etc. Each of these events will trigger the MLAudioSoundEventCallback.
API Level:
- 20
MLAudioSetMediaEventCallback
MLResult MLAudioSetMediaEventCallback(
MLAudioMediaEventCallback callback,
void * context
)
Registers a callback for media transport events.
Parameters
| MLAudioMediaEventCallback | callback | Callback function pointer. |
| void * | context | Generic data pointer passed back through the callback. |
Returns
| MLResult | MLResult_AllocFailed | If memory allocation fails. |
| MLResult | MLResult_InvalidParam | If input parameter is invalid. |
| MLResult | MLResult_Ok | Successfully registered the callback. |
| MLResult | MLResult_UnspecifiedFailure | Internal error. |
| MLResult | MLAudioResult_HandleNotFound | Handle not found. |
| MLResult | MLAudioResult_InternalConfigError | Internal config error. |
| MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Media transport events can be triggered by devices such as bluetooth media controls. The possible events include Stop, Start, Pause, NextTrack and PrevTrack as specified in the MLAudioMediaEvent enum.
API Level:
- 20