Parameters
Module: Audio / Audio Definitions / Audio Output
Functions
| Name | |
|---|---|
| MLResult | MLAudioSetSoundVolumeLinear(MLHandle handle, float volume) Sets the volume of a sound output using a linear scale. |
| MLResult | MLAudioGetSoundVolumeLinear(MLHandle handle, float * out_volume) Queries the volume of a sound output in a linear scale. |
| MLResult | MLAudioSetSoundVolumeDb(MLHandle handle, float volume) Sets the volume of a sound output using a decibel scale. |
| MLResult | MLAudioGetSoundVolumeDb(MLHandle handle, float * out_volume) Queries the volume of a sound output using a decibel scale. |
| MLResult | MLAudioSetSoundPitch(MLHandle handle, float pitch) Sets the pitch of a sound output by modifying its playback speed. |
| MLResult | MLAudioGetSoundPitch(MLHandle handle, float * out_pitch) Queries the pitch of a sound output which corresponds to its playback speed. |
| MLResult | MLAudioSetSoundMute(MLHandle handle, bool is_muted) Sets the mute state of a sound output. |
| MLResult | MLAudioGetSoundMute(MLHandle handle, bool * out_is_muted) Queries the mute state of a sound output. |
| MLResult | MLAudioSetSoundBypassesMasterVolume(MLHandle handle, bool is_bypassing) Sets whether a sound output is exempt from attenuation due to master volume. |
| MLResult | MLAudioGetSoundBypassesMasterVolume(MLHandle handle, bool * out_is_bypassing) Queries whether a sound output is exempt from attenuation due to master volume. |
| MLResult | MLAudioSetSoundLooping(MLHandle handle, bool is_looping) Sets whether a sound output is looping or not. |
| MLResult | MLAudioGetSoundLooping(MLHandle handle, bool * out_is_looping) Queries whether a sound output is looping or not. |
| MLResult | MLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec) Sets the playback position of a sound output that's playing a Streamed File. |
| MLResult | MLAudioGetStreamedFileOffset(MLHandle handle, uint32_t * out_offset_in_msec) Queries the playback position of a sound output that's playing a Streamed File. |
| MLResult | MLAudioGetOutputDevice(MLAudioOutputDevice * out_current_device) Queries which type of sound output device is being used for sound output. |
| MLResult | MLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void * context) Registers a callback for when the active audio hardware output has changed. |
Detailed Description
PARAMETERS.
Functions Documentation
MLAudioSetSoundVolumeLinear
MLResult MLAudioSetSoundVolumeLinear(
MLHandle handle,
float volume
)
Sets the volume of a sound output using a linear scale.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| float | volume | The linear volume that the sound output will be set to. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully set the value. |
| 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
The range of valid values is from 0 to 8. A value of 0 indicates silence. A value of 1 indicates unity gain. A maximum value of 8 indicates 8x unity gain (+18 dB).
MLAudioGetSoundVolumeLinear
MLResult MLAudioGetSoundVolumeLinear(
MLHandle handle,
float * out_volume
)
Queries the volume of a sound output in a linear scale.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| float * | out_volume | Retrieved linear volume of the sound output. |
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_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of valid values is from 0 to 8. A value of 0 indicates silence. A value of 1 indicates unity gain. A maximum value of 8 indicates 8x unity gain (+18 dB).
MLAudioSetSoundVolumeDb
MLResult MLAudioSetSoundVolumeDb(
MLHandle handle,
float volume
)
Sets the volume of a sound output using a decibel scale.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| float | volume | The dB volume that the sound output will be set to. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully set the value. |
| 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
The range of valid values is from -100 dB to +18 dB. A value of -100 dB indicates silence. A value of 0 dB indicates unity gain. A maximum value of 18 dB indicates 8x unity gain.
MLAudioGetSoundVolumeDb
MLResult MLAudioGetSoundVolumeDb(
MLHandle handle,
float * out_volume
)
Queries the volume of a sound output using a decibel scale.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| float * | out_volume | Retrieved dB volume of the sound output. |
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_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of valid values is from -100 dB to +18 dB. A value of -100 dB indicates silence. A value of 0 dB indicates unity gain. A maximum value of 18 dB indicates 8x unity gain.
MLAudioSetSoundPitch
MLResult MLAudioSetSoundPitch(
MLHandle handle,
float pitch
)
Sets the pitch of a sound output by modifying its playback speed.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| float | pitch | The pitch of the sound output to be set. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully set the value. |
| 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_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of valid values is from 0.5 which plays at half speed and produces an octave shift down, to 2.0 which plays at double speed and produces an octave shift up. The default value of 1.0 plays the sound at its original speed and pitch.
MLAudioGetSoundPitch
MLResult MLAudioGetSoundPitch(
MLHandle handle,
float * out_pitch
)
Queries the pitch of a sound output which corresponds to its playback speed.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| float * | out_pitch | Retrieved pitch of the sound output. |
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_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of valid values is from 0.5 which plays at half speed and produces an octave shift down, to 2.0 which plays at double speed and produces an octave shift up. At the default value of 1.0 the sound plays at its original speed and pitch.
MLAudioSetSoundMute
MLResult MLAudioSetSoundMute(
MLHandle handle,
bool is_muted
)
Sets the mute state of a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| bool | is_muted | If true, the sound output will be muted. |
Returns
| MLResult | MLResult_Ok | Successfully set the value. |
| 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
The 'sound mute' of a sound output only affects that one sound output.
MLAudioGetSoundMute
MLResult MLAudioGetSoundMute(
MLHandle handle,
bool * out_is_muted
)
Queries the mute state of a sound output.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| bool * | out_is_muted | If true, the sound output is muted. |
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_InternalConfigError | Failed due to an internal configuration error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The 'sound mute' of a sound output only affects that one sound output.
API Level:
- 20
MLAudioSetSoundBypassesMasterVolume
MLResult MLAudioSetSoundBypassesMasterVolume(
MLHandle handle,
bool is_bypassing
)
Sets whether a sound output is exempt from attenuation due to master volume.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| bool | is_bypassing | Indicates whether the sound output should bypass master volume or not. |
Returns
| MLResult | MLResult_Ok | Successfully set the value. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLResult_IncompatibleSKU | Failed due to feature not being supported on current device version. |
Required Permissions:
- None
This call sets whether a sound output is bypassing master volume, making it effectively "always audible" (assuming it is neither muted nor set to zero volume on a per-sound basis). This option is available only on certain SKUs; trying to set it when the device is not compatible will produce an error as listed below. In addition, this option only works when a sound is non-spatial; the non-spatial sound parameters volume, pitch, etc remain active for sounds that are bypassing master volume.
API Level:
- 20
MLAudioGetSoundBypassesMasterVolume
MLResult MLAudioGetSoundBypassesMasterVolume(
MLHandle handle,
bool * out_is_bypassing
)
Queries whether a sound output is exempt from attenuation due to master volume.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| bool * | out_is_bypassing | Indicates whether the sound output is bypassing master volume or not. |
Returns
| MLResult | MLResult_Ok | Successfully queried the bypassing state of the sound output. |
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLResult_IncompatibleSKU | Failed due to feature not being supported on current device version. |
| MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
| MLResult | MLAudioResult_InternalConfigError | Failed due to an internal configuration error. |
Required Permissions:
- None
This call queries whether a sound output is bypassing master volume, making it effectively "always audible" (assuming it is neither muted nor set to zero volume on a per-sound basis). This option is available only on certain SKUs; trying to query it when the device is not compatible will produce an error as listed below. In addition, this option only works when a sound is non-spatial; the non-spatial sound parameters volume, pitch, etc remain active for sounds that are bypassing master volume.
API Level:
- 20
MLAudioSetSoundLooping
MLResult MLAudioSetSoundLooping(
MLHandle handle,
bool is_looping
)
Sets whether a sound output is looping or not.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| bool | is_looping | Determines whether the sound output is looping or not. |
Returns
| MLResult | MLResult_Ok | Successfully set looping of audio. |
| 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
Looping is available for sound outputs that use Loaded Files and Streamed Files (and their audio resource equivalents). If a sound output is set to looping, then when it reaches the end of the file, it continues playing from the beginning of the file. Looping is not available for sound outputs that use Buffered Outputs.
MLAudioGetSoundLooping
MLResult MLAudioGetSoundLooping(
MLHandle handle,
bool * out_is_looping
)
Queries whether a sound output is looping or not.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| bool * | out_is_looping | If true, the sound output state is looping. |
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
Looping is available for sound outputs that use Loaded Files and Streamed Files (and their audio resource equivalents). If a sound output is set to looping, then when it reaches the end of the file, it continues playing from the beginning of the file. Looping is not available for sound outputs that use Buffered Outputs.
MLAudioSetStreamedFileOffset
MLResult MLAudioSetStreamedFileOffset(
MLHandle handle,
uint32_t offset_in_msec
)
Sets the playback position of a sound output that's playing a Streamed File.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| uint32_t | offset_in_msec | The playback position in milliseconds the sound output will be set to. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully set 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 playback position is in milliseconds and can be set regardless of the playback state.
MLAudioGetStreamedFileOffset
MLResult MLAudioGetStreamedFileOffset(
MLHandle handle,
uint32_t * out_offset_in_msec
)
Queries the playback position of a sound output that's playing a Streamed File.
Parameters
| MLHandle | handle | MLHandle of the sound output. |
| uint32_t * | out_offset_in_msec | Retrieved playback position. |
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_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
The playback position is in milliseconds.
MLAudioGetOutputDevice
MLResult MLAudioGetOutputDevice(
MLAudioOutputDevice * out_current_device
)
Queries which type of sound output device is being used for sound output.
Parameters
| MLAudioOutputDevice * | out_current_device | Enum indicating what kind of audio output device is currently in use. |
Returns
| MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
| MLResult | MLResult_Ok | Successfully indicated the type of output device. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
This is a global configuration that is not specific to individual sound outputs.
MLAudioSetOutputDeviceCallback
MLResult MLAudioSetOutputDeviceCallback(
MLAudioOutputDeviceChangedCallback callback,
void * context
)
Registers a callback for when the active audio hardware output has changed.
Parameters
| MLAudioOutputDeviceChangedCallback | 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_Ok | Successfully registered the callback. |
| MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
| MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
API Level:
- 8