Skip to main content
Version: 31 Aug 2023

ml_audio.h

Classes

Name
structMLAudioMultibandLevel
Properties specifying a broadband level and three sub-band levels.
structMLAudioDispersionProperties
structMLAudioReverbProperties
Properties specifying acoustic reverberation.
structMLAudioSpatialSoundDistanceProperties
structMLAudioSpatialSoundRadiationProperties
structMLAudioRaycast
Two points in space describing a ray.
structMLAudioObstruction
Obstruction along a ray.
structMLAudioRaycastRequest
ID-tracked request for a single raycast operation.
structMLAudioRaycastResult
ID-tracked result for a single raycast operation.
structMLAudioBufferFormat
Buffer format settings for input and output streams.
structMLAudioBuffer
structMLAudioSpectralAnalysis

Types

Name
typedef struct MLAudioMultibandLevelMLAudioMultibandLevel
Properties specifying a broadband level and three sub-band levels.
typedef struct MLAudioDispersionPropertiesMLAudioDispersionProperties
typedef struct MLAudioReverbPropertiesMLAudioReverbProperties
Properties specifying acoustic reverberation.
typedef struct MLAudioSpatialSoundDistancePropertiesMLAudioSpatialSoundDistanceProperties
typedef struct MLAudioSpatialSoundRadiationPropertiesMLAudioSpatialSoundRadiationProperties
typedef struct MLAudioRaycastMLAudioRaycast
Two points in space describing a ray.
typedef struct MLAudioObstructionMLAudioObstruction
Obstruction along a ray.
typedef struct MLAudioRaycastRequestMLAudioRaycastRequest
ID-tracked request for a single raycast operation.
typedef struct MLAudioRaycastResultMLAudioRaycastResult
ID-tracked result for a single raycast operation.
typedef struct MLAudioBufferFormatMLAudioBufferFormat
Buffer format settings for input and output streams.
typedef struct MLAudioBufferMLAudioBuffer
typedef struct MLAudioSpectralAnalysisMLAudioSpectralAnalysis
typedef void()(MLHandle handle, MLAudioSoundEvent event, void context)MLAudioSoundEventCallback
Callback to notify when a sound event has occurred.
typedef void()(MLAudioMediaEvent event, void context)MLAudioMediaEventCallback
Callback to notify when a media event has occurred.
typedef void()(MLHandle handle, void context)MLAudioBufferCallback
Callback to notify when an audio buffer is available for reading or writing.
typedef void()(MLHandle resource, void context)MLAudioResourceDiscardedCallback
Callback to notify when audio resource data is being discarded to make room for other resource data. Resources that are not being referenced by a sound will be discarded before resources that are being referenced by a sound. Resources that are being played by a sound will not be discarded.
typedef void()(float new_volume, void context)MLAudioMasterVolumeChangedCallback
Callback to notify when master volume has been changed.
typedef void()(bool is_muted, void context)MLAudioOutputMuteChangedCallback
Callback to notify when the global Output Mute has changed.
typedef void()(MLAudioOutputDevice current_device, void context)MLAudioOutputDeviceChangedCallback
Callback to notify when the output device has changed.
typedef void()(bool is_muted, void context)MLAudioMicMuteCallback
Callback to notify when global mic mute has been changed.
typedef void()(MLHandle handle, MLAudioTraitAnalysisTarget target, float value, void context)MLAudioTraitAnalysisCallback
Callback to provide a changed value for a running trait analysis.
typedef void()(MLHandle handle, MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysis values, void context)MLAudioSpectralAnalysisCallback
Callback to provide a changed value for a running spectral analysis.

Enums

Name
enumMLAudioState
{
MLAudioState_Stopped,
MLAudioState_Playing,
MLAudioState_Paused,
MLAudioState_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioSoundEvent
{
MLAudioSoundEvent_End,
MLAudioSoundEvent_Loop,
MLAudioSoundEvent_MutedBySystem,
MLAudioSoundEvent_UnmutedBySystem,
MLAudioSoundEvent_DuckedBySystem,
MLAudioSoundEvent_UnduckedBySystem,
MLAudioSoundEvent_ResourceDestroyed,
MLAudioSoundEvent_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioMediaEvent
{
MLAudioMediaEvent_Play,
MLAudioMediaEvent_Stop,
MLAudioMediaEvent_Pause,
MLAudioMediaEvent_NextTrack,
MLAudioMediaEvent_PrevTrack,
MLAudioMediaEvent_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioOutputDevice
{
MLAudioOutputDevice_Wearable,
MLAudioOutputDevice_USB,
MLAudioOutputDevice_Bluetooth,
MLAudioOutputDevice_HearingAid,
MLAudioOutputDevice_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioMicCaptureType
{
MLAudioMicCaptureType_VoiceComm,
MLAudioMicCaptureType_VoiceCapture,
MLAudioMicCaptureType_WorldCapture =4,
MLAudioMicCaptureType_RawMicsAndAECRef,
MLAudioMicCaptureType_Ensure32Bits =0x7FFFFFFF
}
The type of mic input to capture.
enumMLAudioSampleFormat
{
MLAudioSampleFormat_Int,
MLAudioSampleFormat_Float,
MLAudioSampleFormat_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioChannelFormat
{
MLAudioChannelFormat_Default,
MLAudioChannelFormat_AmbisonicAmbix,
MLAudioChannelFormat_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioTraitAnalysisTarget
{
MLAudioTraitAnalysisTarget_AmbientSoundLevelDbfs,
MLAudioTraitAnalysisTarget_UserVoicePresence,
MLAudioTraitAnalysisTarget_UserVoiceLevelDbfs,
MLAudioTraitAnalysisTarget_UserVoicePitch,
MLAudioTraitAnalysisTarget_Ensure32Bits = 0x7FFFFFFF
}
enumMLAudioSpectralAnalysisTarget
{
MLAudioSpectralAnalysisTarget_UserVoiceSpectrumMfcc,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumBark,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumMel,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumThirdOctave,
MLAudioSpectralAnalysisTarget_Ensure32Bits = 0x7FFFFFFF
}
enumAnonymous Enum 3
{
MLResultAPIPrefix_Audio = ( 0x9e11 << 16)
}
enumMLAudioResult
{
MLAudioResult_NotImplemented = MLResultAPIPrefix_Audio,
MLAudioResult_HandleNotFound,
MLAudioResult_InvalidSampleRate,
MLAudioResult_InvalidBitsPerSample,
MLAudioResult_InvalidValidBits,
MLAudioResult_InvalidSampleFormat,
MLAudioResult_InvalidChannelCount,
MLAudioResult_InvalidBufferSize,
MLAudioResult_BufferNotReady,
MLAudioResult_FileNotFound,
MLAudioResult_FileNotRecognized,
MLAudioResult_ResourceNotFound,
MLAudioResult_ResourceDiscarded,
MLAudioResult_OperationUnavailable,
MLAudioResult_OperationNotReady,
MLAudioResult_InternalConfigError,
MLAudioResult_Ensure32Bits = 0x7FFFFFFF
}
Return values for Audio Service API calls.

Functions

Name
const char *MLAudioGetResultString(MLResult result_code)
Returns an ASCII string for each result code.
MLResultMLAudioCreateLoadedResource(int file, bool dynamic_decode, MLAudioResourceDiscardedCallback callback, void context, MLHandle out_resource)
Creates a new audio resource that references a loaded audio file.
MLResultMLAudioCreateStreamedResource(int file, MLAudioResourceDiscardedCallback callback, void context, MLHandle out_resource)
Creates a new audio resource that references a streamed audio file.
MLResultMLAudioCheckResource(MLHandle resource, bool * out_is_ready)
Checks whether an audio resource has been discarded due to memory limits.
MLResultMLAudioGetResourceSize(MLHandle resource, uint32_t * out_size_in_bytes)
Returns the size of the memory footprint for a loaded audio resource.
MLResultMLAudioRefreshResource(MLHandle resource, int file)
Refreshes an audio resource whose data was discarded due to memory limits.
MLResultMLAudioDestroyResource(MLHandle resource)
Destroys a previously created audio resource. If there are sounds that are currently playing the resource, they will be stopped, and an event callback will be issued for MLAudioSoundEvent_ResourceDestroyed.
MLResultMLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle)
Creates a new sound output that plays a loaded audio resource.
MLResultMLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle)
Creates a new sound output that plays a streamed audio resource.
MLResultMLAudioCreateSoundWithLoadedFile(int file, bool auto_destroy, bool dynamic_decode, MLHandle * out_handle)
Creates a new sound output that plays a loaded file.
MLResultMLAudioCreateSoundWithStreamedFile(int file, bool auto_destroy, MLHandle * out_handle)
Creates a new sound output that plays a streamed file.
MLResultMLAudioCreateSoundWithBufferedOutput(const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle)
Creates a new sound output that plays a buffered audio output.
MLResultMLAudioDestroySound(MLHandle handle)
Destroys a previously created sound output.
MLResultMLAudioStartSound(MLHandle handle)
Starts playback for a sound output.
MLResultMLAudioStopSound(MLHandle handle)
Stops playback for a sound output.
MLResultMLAudioPauseSound(MLHandle handle)
Pauses playback for a sound output.
MLResultMLAudioResumeSound(MLHandle handle)
Resumes playback for a sound output.
MLResultMLAudioGetSoundState(MLHandle handle, MLAudioState * out_state)
Indicates the play state of a sound output.
MLResultMLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat * out_format)
Returns the audio format of a sound output.
MLResultMLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void * context)
Registers a callback for events on a sound output.
MLResultMLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void * context)
Registers a callback for user-issued media control events.
MLResultMLAudioSetSoundVolumeLinear(MLHandle handle, float volume)
Sets the volume of a sound output using a linear scale.
MLResultMLAudioGetSoundVolumeLinear(MLHandle handle, float * out_volume)
Returns the volume of a sound output using a linear scale.
MLResultMLAudioSetSoundVolumeDb(MLHandle handle, float volume)
Sets the volume of a sound output using a decibel scale.
MLResultMLAudioGetSoundVolumeDb(MLHandle handle, float * out_volume)
Returns the volume of a sound output using a decibel scale.
MLResultMLAudioSetSoundPitch(MLHandle handle, float pitch)
Sets the pitch of a sound output.
MLResultMLAudioGetSoundPitch(MLHandle handle, float * out_pitch)
Returns the pitch of a sound output.
MLResultMLAudioSetSoundMute(MLHandle handle, bool is_muted)
Mutes or un-mutes a sound output.
MLResultMLAudioGetSoundMute(MLHandle handle, bool * out_is_muted)
Returns whether a sound output is muted or not.
MLResultMLAudioSetSoundBypassesMasterVolume(MLHandle handle, bool is_bypassing)
Sets whether a sound output is exempt from attenuation due to master volume.
MLResultMLAudioGetSoundBypassesMasterVolume(MLHandle handle, bool * out_is_bypassing)
Queries whether a sound output is exempt from attenuation due to master volume.
MLResultMLAudioSetSoundLooping(MLHandle handle, bool is_looping)
Sets whether a sound output is looping or not.
MLResultMLAudioGetSoundLooping(MLHandle handle, bool * out_is_looping)
Returns whether a sound output is looping or not.
MLResultMLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec)
Sets the playback position for a streamed file.
MLResultMLAudioGetStreamedFileOffset(MLHandle handle, uint32_t * out_offset_in_msec)
Returns the playback position for a streamed file.
MLResultMLAudioGetOutputDevice(MLAudioOutputDevice * out_current_device)
Returns which type of sound output device is being used for sound output.
MLResultMLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void * context)
Registers a callback for audio output device change.
MLResultMLAudioResetAcousticScene()
Resets the Acoustic Scene associated with the caller.
MLResultMLAudioBeginAcousticSceneUpdate()
Signals beginning of grouped Acoustic parameter multi-update.
MLResultMLAudioEndAcousticSceneUpdate()
Signals end of grouped Acoustic parameter multi-update.
MLResultMLAudioSetAcousticSceneMapEnable(bool is_enabled)
Enables/disables Acoustic Map data for the Acoustic Scene.
MLResultMLAudioGetAcousticSceneMapEnable(bool * out_is_enabled)
Indicates whether Acoustic Map data is enabled for the Acoustic Scene.
MLResultMLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel * transmission)
Sets amount of sound transmitted through non-Acoustic Element objects.
MLResultMLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel * out_transmission)
Returns amount of sound transmitted through non-Acoustic Element objects.
MLResultMLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties * properties)
Sets the fallback room properties to be used when none are otherwise specified.
MLResultMLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties * out_properties)
Returns the default room properties used when none are otherwise specified.
MLResultMLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties * properties)
Sets the fallback room properties to be used when none are otherwise specified.
MLResultMLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties * out_properties)
Returns the default room properties used when none are otherwise specified.
MLResultMLAudioGetChangedAcousticMap(uint32_t prev_map_tag, uint8_t * out_map_data, uint32_t out_map_size_in_bytes, uint32_t * out_map_tag)
Returns the Acoustic Map if updated since previous call.
MLResultMLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled)
Enables/disables 3D audio processing for a sound output.
MLResultMLAudioGetSpatialSoundEnable(MLHandle handle, bool * out_is_enabled)
Indicates whether 3D audio processing is enabled for a sound output.
MLResultMLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f * position)
Sets the 3D position for one channel of a sound output.
MLResultMLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f * out_position)
Returns the 3D position for one channel of a sound output.
MLResultMLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf * direction)
Sets the radiation direction for one channel of a sound output.
MLResultMLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf * out_direction)
Returns the radiation direction for one channel of a sound output.
MLResultMLAudioSetSpatialSoundBillboarding(MLHandle id, bool is_billboarding)
Sets a mode where the sound always faces the listener.
MLResultMLAudioGetSpatialSoundBillboarding(MLHandle id, bool * out_is_billboarding)
Indicates whether the sound automatically faces the listener.
MLResultMLAudioSetSpatialSoundObstruction(MLHandle id, uint32_t channel, const MLAudioObstruction left_ear, const MLAudioObstruction right_ear)
Sets the direct path obstruction for one channel of a sound output.
MLResultMLAudioGetSpatialSoundObstruction(MLHandle id, uint32_t channel, MLAudioObstruction out_left_ear, MLAudioObstruction out_right_ear)
Returns the direct path obstruction for one channel of a sound output.
MLResultMLAudioSetSpatialSoundObstructionOverride(MLHandle id, const MLAudioMultibandLevel * override)
Sets an override that enables the sound to pass through obstructions.
MLResultMLAudioGetSpatialSoundObstructionOverride(MLHandle id, MLAudioMultibandLevel * out_override)
Returns the amount of the sound obstruction override.
MLResultMLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties * properties)
Sets the distance properties for one channel of a sound output.
MLResultMLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties * out_properties)
Returns the distance properties for one channel of a sound output.
MLResultMLAudioSetSpatialSoundRadiation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundRadiationProperties * properties)
Sets the radiation properties for one channel of a sound output.
MLResultMLAudioGetSpatialSoundRadiation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundRadiationProperties * out_properties)
Returns the radiation properties for one channel of a sound output.
MLResultMLAudioSetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the direct sound level for one channel of a sound output.
MLResultMLAudioGetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Returns the direct sound level for one channel of a sound output.
MLResultMLAudioSetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the indirect sound level for one channel of a sound output.
MLResultMLAudioGetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Returns the indirect sound level for one channel of a sound output.
MLResultMLAudioSetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the dispersion level for one channel of a sound output.
MLResultMLAudioGetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Returns the dispersion level for one channel of a sound output.
MLResultMLAudioSetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the reverb level for one channel of a sound output.
MLResultMLAudioGetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Returns the reverb level for one channel of a sound output.
MLResultMLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative)
Sets whether the coordinates for a sound output are head relative.
MLResultMLAudioGetSpatialSoundHeadRelative(MLHandle handle, bool * out_is_head_relative)
Returns whether the coordinates for a sound output are head relative.
MLResultMLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest * out_raycast_requests, uint32_t out_request_count)
Returns a list of ID-tracked requests for raycast operations.
MLResultMLAudioSetSpatialRaycastResults(MLAudioRaycastResult * raycast_results, uint32_t result_count)
Sets the ID-tracked results for previously requested raycast operations.
MLResultMLAudioGetBufferedOutputDefaults(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)
Returns the preferred (i.e. best performing) settings for buffered output.
MLResultMLAudioGetBufferedOutputLatency(MLHandle handle, float * out_latency_in_msec)
Returns the latency for a buffered output.
MLResultMLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t * out_frames_played)
Returns the number of audio frames played by a buffered output.
MLResultMLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer * out_buf)
Returns an empty buffer for writing more buffered data.
MLResultMLAudioReleaseOutputBuffer(MLHandle handle)
Releases a buffer once it has been filled.
MLResultMLAudioGetMasterVolume(float * out_volume)
Returns the master volume for the audio system.
MLResultMLAudioSetMasterVolumeCallback(MLAudioMasterVolumeChangedCallback callback, void * context)
Registers a callback for changes to the master volume.
MLResultMLAudioGetOutputMute(bool * out_is_muted)
Indicates whether the output mute of the audio system is on or off.
MLResultMLAudioSetOutputMuteCallback(MLAudioOutputMuteChangedCallback callback, void * context)
Registers a callback for audio output mute change.
MLResultMLAudioCreateInputFromMicCapture(MLAudioMicCaptureType mic_capture_type, const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle)
Creates a new sound input that provides audio from the mics on the wearable.
MLResultMLAudioCreateInputFromVirtualCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void callback_context, MLHandle * out_handle)
Creates a new sound input that provides a "virtual capture" stream.
MLResultMLAudioCreateInputFromMixedCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void callback_context, MLHandle * out_handle)
Creates a new sound input that provides a "mixed capture" stream.
MLResultMLAudioDestroyInput(MLHandle handle)
Destroys a previously created sound input.
MLResultMLAudioStartInput(MLHandle handle)
Starts capture for a sound input.
MLResultMLAudioStopInput(MLHandle handle)
Stops capture for a sound input.
MLResultMLAudioGetInputState(MLHandle handle, MLAudioState * out_state)
Indicates the play state of a sound input.
MLResultMLAudioGetBufferedInputDefaults(uint32_t channel_count, uint32_t samples_per_second, MLAudioBufferFormat out_format, uint32_t out_recommended_size_in_bytes, uint32_t * out_min_size_in_bytes)
Returns the preferred (i.e. best performing) settings for buffered input.
MLResultMLAudioGetBufferedInputLatency(MLHandle handle, float * out_latency_in_msec)
Returns the latency for a sound input.
MLResultMLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer * out_buf)
Returns a full buffer containing captured audio data.
MLResultMLAudioReleaseInputBuffer(MLHandle handle)
Releases a buffer once it has been read.
MLResultMLAudioSetMicMute(bool is_muted)
Mutes or un-mutes all microphone capture.
MLResultMLAudioGetMicMute(bool * out_is_muted)
Returns whether all microphone capture is muted or not.
MLResultMLAudioSetMicMuteCallback(MLAudioMicMuteCallback callback, void * context)
Registers a callback for changes to the global mic mute.
MLResultMLAudioBeginTraitAnalysisFromMicCapture(MLAudioTraitAnalysisTarget target, MLAudioTraitAnalysisCallback callback, void callback_context, MLHandle out_handle)
Creates a new analysis input for the specified target.
MLResultMLAudioGetTraitAnalysis(MLHandle handle, float * out_value)
Returns the current value of the trait analysis associated with the specified handle.
MLResultMLAudioEndTraitAnalysis(MLHandle handle)
Stops a previously started trait analysis.
MLResultMLAudioBeginSpectralAnalysisFromMicCapture(MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysisCallback callback, void callback_context, MLHandle out_handle)
Starts a new spectral analysis that provides frequency spectrum energy derived from mic signals.
MLResultMLAudioGetSpectralAnalysis(MLHandle handle, MLAudioSpectralAnalysis * out_values)
Returns the current value of the spectral analysis associated with the specified handle.
MLResultMLAudioEndSpectralAnalysis(MLHandle handle)
Stops a previously started spectral analysis.

Enums Documentation

MLAudioState

EnumeratorValueDescription
MLAudioState_StoppedStopped, can be started.
MLAudioState_PlayingPlaying, can be stopped or paused.
MLAudioState_PausedPaused, can be resumed or re-started.
MLAudioState_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Possible playback states for sounds and inputs.


MLAudioSoundEvent

EnumeratorValueDescription
MLAudioSoundEvent_EndA sound output has reached the end and is stopping.
MLAudioSoundEvent_LoopA sound output has reached the end and is is looping.
MLAudioSoundEvent_MutedBySystemA sound output has been selectively muted due to system conditions.
MLAudioSoundEvent_UnmutedBySystemA previously muted sound output has been unmuted due to system conditions.
MLAudioSoundEvent_DuckedBySystemA sound output has been selectively ducked due to system conditions.
MLAudioSoundEvent_UnduckedBySystemA previously ducked sound output has been unducked due to system conditions.
MLAudioSoundEvent_ResourceDestroyedThe resource used by a sound output has been destroyed.
MLAudioSoundEvent_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Possible events for individual sound outputs.


MLAudioMediaEvent

EnumeratorValueDescription
MLAudioMediaEvent_PlayIndicates a user command to play.
MLAudioMediaEvent_StopIndicates a user command to stop.
MLAudioMediaEvent_PauseIndicates a user command to pause.
MLAudioMediaEvent_NextTrackIndicates a user command to go to next track.
MLAudioMediaEvent_PrevTrackIndicates a user command to go to previous track.
MLAudioMediaEvent_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Possible media control events initiated by the user.


MLAudioOutputDevice

EnumeratorValueDescription
MLAudioOutputDevice_WearableBuilt-in speakers in the wearable.
MLAudioOutputDevice_USBUSB audio from the beltpack.
MLAudioOutputDevice_BluetoothA2DP audio via Bluetooth.
MLAudioOutputDevice_HearingAidHearing Aid audio via Bluetooth.
MLAudioOutputDevice_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

The currently active output device.


MLAudioMicCaptureType

EnumeratorValueDescription
MLAudioMicCaptureType_VoiceCommUser voice, suitable for communications. Mono, 16 bit integer, 16k sampling rate.
MLAudioMicCaptureType_VoiceCaptureHigh fidelity user voice, suitable for recording. Mono, 16 bit integer, 48k sampling rate.
MLAudioMicCaptureType_WorldCapture=4Mic mix representing the user's surroundings. Stereo, 16 bit integer, 48k sampling rate.
MLAudioMicCaptureType_RawMicsAndAECRefAll 4 mics unprocessed (front L/R, side L/R) + AEC return from amp (L/R). Channel layout: 1 - Front L, 2 - Front R, 3 - Side L, 4 - Side R, 5 - AEC return L, 6 - AEC return R. DC Offset and/or background hum may be present on channels 1-4 due to lack of processing. 6-channel, 16 bit integer, 48k sampling rate.
MLAudioMicCaptureType_Ensure32Bits=0x7FFFFFFFEnsure enum is represented as 32 bits.

The type of mic input to capture.

API Level:

  • 29

MLAudioSampleFormat

EnumeratorValueDescription
MLAudioSampleFormat_IntSamples are integer.
MLAudioSampleFormat_FloatSamples are float. Not currently implemented.
MLAudioSampleFormat_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Possible sample formats for input and output streams.


MLAudioChannelFormat

EnumeratorValueDescription
MLAudioChannelFormat_DefaultInfer channel format from buffer format settings.
MLAudioChannelFormat_AmbisonicAmbixAmbisonic AmbiX format.
MLAudioChannelFormat_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Channel formats for buffered outputs, specified in MLAudioBufferFormat reserved field.


MLAudioTraitAnalysisTarget

EnumeratorValueDescription
MLAudioTraitAnalysisTarget_AmbientSoundLevelDbfsAmbient Sound Level dBFS, a full scale sound level measurement of an ambient mic stream.
MLAudioTraitAnalysisTarget_UserVoicePresenceVoice Presence, indicates absence (0) or presence (1) of voice in a voice mic stream.
MLAudioTraitAnalysisTarget_UserVoiceLevelDbfsVoice Level dBFS, a full scale sound level measurement of a voice mic stream.
MLAudioTraitAnalysisTarget_UserVoicePitchVoice Pitch, frequency in hertz of the voice in a voice mic stream.
MLAudioTraitAnalysisTarget_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Available trait analyses of an audio stream.


MLAudioSpectralAnalysisTarget

EnumeratorValueDescription
MLAudioSpectralAnalysisTarget_UserVoiceSpectrumMfccVoice Mel Frequency Cepstral Coefficients, spectral analysis of a voice mic stream. (typically used for lip-sync).
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumBarkAmbient Sound Spectrum Bark Scale, spectral analysis of ambient mic stream(s) using Bark scale.
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumMelAmbient Sound Spectrum Mel Scale, spectral analysis of ambient mic stream(s) using Mel scale.
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumThirdOctaveAmbient Sound Spectrum Third Octave Scale, spectral analysis of ambient mic stream(s) using Third Octave scale.
MLAudioSpectralAnalysisTarget_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Available frequency spectrum analyses of an audio stream.


Anonymous Enum 3

EnumeratorValueDescription
MLResultAPIPrefix_Audio( 0x9e11 << 16)Defines the prefix for MLAudioResult codes.

MLAudioResult

EnumeratorValueDescription
MLAudioResult_NotImplementedMLResultAPIPrefix_AudioFunction not implemented.
MLAudioResult_HandleNotFoundNot a valid MLHandle for a sound or input.
MLAudioResult_InvalidSampleRateSample rate not supported.
MLAudioResult_InvalidBitsPerSampleBits per sample not supported.
MLAudioResult_InvalidValidBitsValid bits per sample not supported.
MLAudioResult_InvalidSampleFormatSample format not supported.
MLAudioResult_InvalidChannelCountChannel count not supported.
MLAudioResult_InvalidBufferSizeBuffer size too small.
MLAudioResult_BufferNotReadyBuffer not ready for read or write.
MLAudioResult_FileNotFoundSpecified file not found.
MLAudioResult_FileNotRecognizedSpecified file has unsupported format.
MLAudioResult_ResourceNotFoundSpecified resource is not on the list.
MLAudioResult_ResourceDiscardedData was unloaded or file was closed.
MLAudioResult_OperationUnavailableRequested operation not possible for given item.
MLAudioResult_OperationNotReadyRequested operation has not yet been processed.
MLAudioResult_InternalConfigErrorInternal configuration problem was detected.
MLAudioResult_Ensure32Bits0x7FFFFFFFEnsure enum is represented as 32 bits.

Return values for Audio Service API calls.

API Level:

  • 4

Types Documentation

MLAudioMultibandLevel

typedef struct MLAudioMultibandLevel MLAudioMultibandLevel;

Properties specifying a broadband level and three sub-band levels.

More Info

API Level:

  • 20

MLAudioDispersionProperties

typedef struct MLAudioDispersionProperties MLAudioDispersionProperties;

\briefProperties specifying acoustic dispersion (clustered reflections).

More Info

API Level:

  • 20

MLAudioReverbProperties

typedef struct MLAudioReverbProperties MLAudioReverbProperties;

Properties specifying acoustic reverberation.

More Info

API Level:

  • 20

MLAudioSpatialSoundDistanceProperties

typedef struct MLAudioSpatialSoundDistanceProperties MLAudioSpatialSoundDistanceProperties;

Properties specifying the distance response of a spatial sound.

More Info


MLAudioSpatialSoundRadiationProperties

typedef struct MLAudioSpatialSoundRadiationProperties MLAudioSpatialSoundRadiationProperties;

Properties specifying the directivity of a spatial sound.

More Info


MLAudioRaycast

typedef struct MLAudioRaycast MLAudioRaycast;

Two points in space describing a ray.

More Info

API Level:

  • 20

MLAudioObstruction

typedef struct MLAudioObstruction MLAudioObstruction;

Obstruction along a ray.

More Info

API Level:

  • 20

MLAudioRaycastRequest

typedef struct MLAudioRaycastRequest MLAudioRaycastRequest;

ID-tracked request for a single raycast operation.

More Info

API Level:

  • 20

MLAudioRaycastResult

typedef struct MLAudioRaycastResult MLAudioRaycastResult;

ID-tracked result for a single raycast operation.

More Info

API Level:

  • 20

MLAudioBufferFormat

typedef struct MLAudioBufferFormat MLAudioBufferFormat;

Buffer format settings for input and output streams.

More Info

API Level:

  • 20

MLAudioBuffer

typedef struct MLAudioBuffer MLAudioBuffer;

An audio buffer for passing data from input streams or to output streams.

More Info


MLAudioSpectralAnalysis

typedef struct MLAudioSpectralAnalysis MLAudioSpectralAnalysis;

A representation of frequency spectrum energy over a window of time.

More Info


MLAudioSoundEventCallback

typedef void(* MLAudioSoundEventCallback) (MLHandle handle, MLAudioSoundEvent event, void *context);

Callback to notify when a sound event has occurred.

note

The callback will be called on a separate thread.


MLAudioMediaEventCallback

typedef void(* MLAudioMediaEventCallback) (MLAudioMediaEvent event, void *context);

Callback to notify when a media event has occurred.

note

The callback will be called on a separate thread.


MLAudioBufferCallback

typedef void(* MLAudioBufferCallback) (MLHandle handle, void *context);

Callback to notify when an audio buffer is available for reading or writing.

note

The callback will be called on a separate thread.


MLAudioResourceDiscardedCallback

typedef void(* MLAudioResourceDiscardedCallback) (MLHandle resource, void *context);

Callback to notify when audio resource data is being discarded to make room for other resource data. Resources that are not being referenced by a sound will be discarded before resources that are being referenced by a sound. Resources that are being played by a sound will not be discarded.

note
  • The callback will be called on a separate thread.
  • The audio data should not be refreshed until needed again.

MLAudioMasterVolumeChangedCallback

typedef void(* MLAudioMasterVolumeChangedCallback) (float new_volume, void *context);

Callback to notify when master volume has been changed.

note

The callback will be called on a separate thread.


MLAudioOutputMuteChangedCallback

typedef void(* MLAudioOutputMuteChangedCallback) (bool is_muted, void *context);

Callback to notify when the global Output Mute has changed.

note
  • The global Output Mute is changed by using voice commands or a bluetooth keyboard with a mute/unmute button.
  • The callback will be called on a separate thread.

MLAudioOutputDeviceChangedCallback

typedef void(* MLAudioOutputDeviceChangedCallback) (MLAudioOutputDevice current_device, void *context);

Callback to notify when the output device has changed.

note

The callback will be called on a separate thread.


MLAudioMicMuteCallback

typedef void(* MLAudioMicMuteCallback) (bool is_muted, void *context);

Callback to notify when global mic mute has been changed.

note

The callback will be called on a separate thread.


MLAudioTraitAnalysisCallback

typedef void(* MLAudioTraitAnalysisCallback) (MLHandle handle, MLAudioTraitAnalysisTarget target, float value, void *context);

Callback to provide a changed value for a running trait analysis.

note

The callback will be called on a separate thread.


MLAudioSpectralAnalysisCallback

typedef void(* MLAudioSpectralAnalysisCallback) (MLHandle handle, MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysis values, void *context);

Callback to provide a changed value for a running spectral analysis.

note

The callback will be called on a separate thread.


Functions Documentation

MLAudioGetResultString

const char * MLAudioGetResultString(
MLResult result_code
)

Returns an ASCII string for each result code.

Parameters

MLResultresult_codeMLResult to select the result code.

This call returns strings for all of the MLResult and MLAudioResult codes.

Return: ASCII string containing readable version of result code.


MLAudioCreateLoadedResource

MLResult MLAudioCreateLoadedResource(
int file,
bool dynamic_decode,
MLAudioResourceDiscardedCallback callback,
void * context,
MLHandle * out_resource
)

Creates a new audio resource that references a loaded audio file.

Parameters

intfileFile descriptor specifying the file to load.
booldynamic_decodeNot currently implemented.
MLAudioResourceDiscardedCallbackcallbackMLAudioResourceDiscardedCallback function pointer.
void *contextGeneric data pointer passed back to callback.
MLHandle *out_resourceMLHandle used in subsequent calls for this resource.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created new audio resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotRecognizedFailed because file was not recognized.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to invalid bits per sample.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Creates a new audio resource that references the audio file specified by the 'file' argument, which it tries to load during resource creation. An optional MLAudioResourceDiscardedCallback will inform the client if the data later gets discarded due to memory limits (or if it fails to load during creation). After creation the resource can be played by passing its id to MLAudioCreateSoundWithLoadedResource.


MLAudioCreateStreamedResource

MLResult MLAudioCreateStreamedResource(
int file,
MLAudioResourceDiscardedCallback callback,
void * context,
MLHandle * out_resource
)

Creates a new audio resource that references a streamed audio file.

Parameters

intfileFile descriptor specifying the file to load.
MLAudioResourceDiscardedCallbackcallbackMLAudioResourceDiscardedCallback Function pointer.
void *contextGeneric data pointer passed back to callback.
MLHandle *out_resourceMLHandle used in subsequent calls for this resource.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created new audio resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because of feature has not been implemented yet.

Required Permissions:

  • None

Creates a new audio resource that references the audio file specified by the 'file' argument. An optional MLAudioResourceDiscardedCallback will inform the client if the file's file descriptor later gets discarded due to file descriptor limits (or if a file descriptor cannot be generated during resource creation). After creation the resource can be played by passing its id to MLAudioCreateSoundWithStreamedResource.


MLAudioCheckResource

MLResult MLAudioCheckResource(
MLHandle resource,
bool * out_is_ready
)

Checks whether an audio resource has been discarded due to memory limits.

Parameters

MLHandleresourceMLHandle used to identify the resource.
bool *out_is_readyIndicates whether the resource is ready or not.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully checked audio resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because of feature has not been implemented yet.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

This call can be used instead of the MLAudioResourceDiscardedCallback to determine whether an audio resource has been discarded. Resources that are not being referenced by a sound will be discarded before resources that are being referenced by a sound. Resources that are being played by a sound will not be discarded. MLAudioCheckResource can be called just before the resource is needed, or at some other appropriate time for accessing data. However it should not be called constantly on a polling basis to instantly refresh resources that get discarded, since that would defeat the purpose of the memory limit.


MLAudioGetResourceSize

MLResult MLAudioGetResourceSize(
MLHandle resource,
uint32_t * out_size_in_bytes
)

Returns the size of the memory footprint for a loaded audio resource.

Parameters

MLHandleresourceMLHandle used to identify the resource.
uint32_t *out_size_in_bytesThe returned size of the footprint.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully obtained resource size.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

This call tells the owner of a loaded resource what size memory footprint is used by the resource. For a loaded resource that is de-compressed when it gets loaded into memory, the value returned will be the de-compressed size. For a loaded resource that stays compressed when loaded, and gets decoded on the fly (not yet implemented), the value returned will be the compressed size. This call always returns the size of the resource's footprint, even when the resource is temporarily discarded and is using no memory. To determine if the size returned is actually being used in memory, call MLAudioCheckResource to find out if the resource is currently discarded. This call will return with an error if it is called for a streamed resource.

API Level:

  • 7

MLAudioRefreshResource

MLResult MLAudioRefreshResource(
MLHandle resource,
int file
)

Refreshes an audio resource whose data was discarded due to memory limits.

Parameters

MLHandleresourceMLHandle used to identify the resource.
intfileFile descriptor specifying the audio data to refresh.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully refreshed audio resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotRecognizedFailed because file was not recognized.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to invalid bits per sample.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleFormatFailed due to an invalid sample format.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidValidBitsFailed due to invalid valid bits.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

This call allows the client to 'refresh' a resource whose data has been discarded. This should be done just prior to the next time the data is needed, or some other convenient time when data access is appropriate, but not right after the data is discarded, as that would defeat the purpose of the memory limit.


MLAudioDestroyResource

MLResult MLAudioDestroyResource(
MLHandle resource
)

Destroys a previously created audio resource. If there are sounds that are currently playing the resource, they will be stopped, and an event callback will be issued for MLAudioSoundEvent_ResourceDestroyed.

Parameters

MLHandleresourceMLHandle used to identify the resource.

Returns

MLResultMLResult_OkSuccessfully destroyed audio resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

MLAudioCreateSoundWithLoadedResource

MLResult MLAudioCreateSoundWithLoadedResource(
MLHandle resource,
bool auto_destroy,
MLHandle * out_handle
)

Creates a new sound output that plays a loaded audio resource.

Parameters

MLHandleresourceMLHandle specifying the resource to play.
boolauto_destroyIf true, the sound output is destroyed when done playing.
MLHandle *out_handleMLHandle used in subsequent calls for this sound output.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound input.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotRecognizedFailed because file was not recognized.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to invalid bits per sample.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

Creates a sound output to play a loaded audio file referenced as a resource. Loaded resources are created and loaded by calling MLAudioCreateLoadedResource. After sound creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.


MLAudioCreateSoundWithStreamedResource

MLResult MLAudioCreateSoundWithStreamedResource(
MLHandle resource,
bool auto_destroy,
MLHandle * out_handle
)

Creates a new sound output that plays a streamed audio resource.

Parameters

MLHandleresourceMLHandle specifying the resource to play.
boolauto_destroyIf true, the sound output is destroyed when done playing.
MLHandle *out_handleMLHandle used in subsequent calls for this sound output.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_ResourceDiscardedFailed because file was closed.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

Creates a sound output to play a streamed audio file referenced as a resource. Streamed resources are created by calling MLAudioCreateStreamedResource. After sound creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.


MLAudioCreateSoundWithLoadedFile

MLResult MLAudioCreateSoundWithLoadedFile(
int file,
bool auto_destroy,
bool dynamic_decode,
MLHandle * out_handle
)

Creates a new sound output that plays a loaded file.

Parameters

intfileFile descriptor specifying the file to play.
boolauto_destroyIf true, the sound output is destroyed when done playing.
booldynamic_decodeNot currently implemented.
MLHandle *out_handleMLHandle used in subsequent calls for this sound output.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotRecognizedFailed because file was not recognized.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to invalid bits per sample.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidValidBitsFailed due to invalid valid bits.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

Creates a sound output and loads the audio file specified by the 'file' argument into memory. After creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.


MLAudioCreateSoundWithStreamedFile

MLResult MLAudioCreateSoundWithStreamedFile(
int file,
bool auto_destroy,
MLHandle * out_handle
)

Creates a new sound output that plays a streamed file.

Parameters

intfileFile descriptor specifying the file to play.
boolauto_destroyIf true, the sound output is destroyed when done playing.
MLHandle *out_handleMLHandle used in subsequent calls for this sound output.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotFoundFailed because file was missing.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_ResourceDiscardedFailed because file was closed.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

Creates a sound output and prepares to stream the audio file specified by the 'file' argument. After creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 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 new sound output that plays a buffered audio output.

Parameters

const MLAudioBufferFormat *formatMLAudioBufferFormat Specifying the audio format of the buffers.
uint32_tbuffer_size_in_bytesRequested size in bytes for each of the output buffers.
MLAudioBufferCallbackcallbackMLAudioBufferCallback function pointer.
void *contextGeneric data pointer passed back to callback.
MLHandle *out_handleMLHandle used in subsequent calls for this sound output.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleFormatFailed due to an invalid sample format.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidValidBitsFailed due to invalid valid bits.

Required Permissions:

  • None

Creates a sound output and allocates a double-buffer for buffering audio data into it. To write data into the next available buffer call MLAudioGetOutputBuffer to get an empty buffer, then write the data into the buffer, then call MLAudioReleaseOutputBuffer to indicate that the buffer is ready to play. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument specifies the format of which the following are supported: Mono, stereo, 6-channel, 8-channel, or 12-channel; 16 bit integer; a sampling rate between 16k - 48k. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, one or both buffers can optionally be pre-filled, and the sound can be started by calling MLAudioStartSound.

API Level:

  • 7

MLAudioDestroySound

MLResult MLAudioDestroySound(
MLHandle handle
)

Destroys a previously created sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.

Returns

MLResultMLResult_OkSuccessfully destroyed sound output.
MLResultMLResult_UnspecifiedFailureFailed to destroy sound output due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed to destroy sound output due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed to destroy sound output because feature has not been implemented yet.

Required Permissions:

  • None

MLAudioStartSound

MLResult MLAudioStartSound(
MLHandle handle
)

Starts playback for a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.

Returns

MLResultMLResult_OkSuccessfully started playback.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_ResourceDiscardedFailed because file was closed.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

When starting playback for a file (loaded, streamed, system sound), playback starts at the beginning of the file (even after a pause). When starting playback for an output stream, the "frames played" counter gets reset to zero (and if the output stream was previously paused the streaming buffers get reset as well).


MLAudioStopSound

MLResult MLAudioStopSound(
MLHandle handle
)

Stops playback for a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.

Returns

MLResultMLResult_OkSuccessfully stopped playback.
MLResultMLResult_UnspecifiedFailureFailed to stop playback due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed to stop playback due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed to stop playback because feature has not been implemented yet.
MLResultMLAudioResult_ResourceNotFoundFailed to stop playback because resource was not found.

Required Permissions:

  • None

Stops playback for a sound output that's playing or paused.


MLAudioPauseSound

MLResult MLAudioPauseSound(
MLHandle handle
)

Pauses playback for a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.

Returns

MLResultMLResult_OkSuccessfully paused playback.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

Pauses playback for a sound output that's playing. If the sound output is not playing, the pause will fail.


MLAudioResumeSound

MLResult MLAudioResumeSound(
MLHandle handle
)

Resumes playback for a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.

Returns

MLResultMLResult_OkSuccessfully resumed playback.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

Resumes playback for a sound output that's paused. If the sound output is not paused, the resume will fail.


MLAudioGetSoundState

MLResult MLAudioGetSoundState(
MLHandle handle,
MLAudioState * out_state
)

Indicates the play state of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
MLAudioState *out_stateIndicates the current play state.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully indicated the state of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The MLAudioState indicates whether the sound output is stopped, playing or paused.


MLAudioGetSoundFormat

MLResult MLAudioGetSoundFormat(
MLHandle handle,
MLAudioBufferFormat * out_format
)

Returns the audio format of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
MLAudioBufferFormat *out_formatMLAudioBufferFormat struct containing the format info.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned audio format.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

The returned information includes the channel count, sample rate and bit depth of the sound's audio data. For Streamed Files, the format is not available until about 100+ milliseconds after playback of the Streamed File is started.


MLAudioSetSoundEventCallback

MLResult MLAudioSetSoundEventCallback(
MLHandle handle,
MLAudioSoundEventCallback callback,
void * context
)

Registers a callback for events on a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
MLAudioSoundEventCallbackcallbackMLAudioSoundEventCallback function pointer.
void *contextGeneric data pointer passed back to callback.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully registered callback.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Events that can result in a callback being called include: Stopping at the end of a file; looping at the end of a file; a sound output having its volume lowered or restored by the audio policy manager; a sound output being muted or unmuted by the audio policy manager. The 'context' argument is passed back to the callback, along with the particular event type (MLAudioSoundEvent) that caused the callback.

API Level:

  • 20

MLAudioSetMediaEventCallback

MLResult MLAudioSetMediaEventCallback(
MLAudioMediaEventCallback callback,
void * context
)

Registers a callback for user-issued media control events.

Parameters

MLAudioMediaEventCallbackcallbackMLAudioMediaEventCallback function pointer.
void *contextGeneric data pointer passed back to callback.

Returns

MLResultMLResult_AllocFailedIf memory allocation fails.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Events that can result in a callback being called include: Pressing a play button; pressing a stop button; pressing a pause button; pressing a next track button, pressing a previous track button; The particular event type (MLAudioMediaEvent) that caused the callback is passed to the callback as its first argument.The 'context' argument is passed back to the callback as its second argument.

API Level:

  • 20

MLAudioSetSoundVolumeLinear

MLResult MLAudioSetSoundVolumeLinear(
MLHandle handle,
float volume
)

Sets the volume of a sound output using a linear scale.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
floatvolumeThe volume that the sound output will be set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set volume of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the volume is 0 to 8, with 0 for silence, 1 for unity gain, and 8 for 8x gain.


MLAudioGetSoundVolumeLinear

MLResult MLAudioGetSoundVolumeLinear(
MLHandle handle,
float * out_volume
)

Returns the volume of a sound output using a linear scale.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
float *out_volumeThe volume that the sound output is set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned volume of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the volume is 0 to 8, with 0 for silence, 1 for unity gain, and 8 for 8x gain.


MLAudioSetSoundVolumeDb

MLResult MLAudioSetSoundVolumeDb(
MLHandle handle,
float volume
)

Sets the volume of a sound output using a decibel scale.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
floatvolumeThe volume that the sound output will be set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set volume.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the volume is -100 db to +18 dB, with -100 dB for silence, 0 dB for unity gain, and +18 dB for 8x gain.


MLAudioGetSoundVolumeDb

MLResult MLAudioGetSoundVolumeDb(
MLHandle handle,
float * out_volume
)

Returns the volume of a sound output using a decibel scale.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
float *out_volumeThe volume that the sound output is set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned volume.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the volume is -100 db to +18 dB, with -100 dB for silence, 0 dB for unity gain, and +18 dB for 8x gain.


MLAudioSetSoundPitch

MLResult MLAudioSetSoundPitch(
MLHandle handle,
float pitch
)

Sets the pitch of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
floatpitchThe pitch that the sound output will be set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set pitch of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the pitch is 0.5 to 2.0, with 0.5 being one octave down and 2.0 being one octave up (i.e., the pitch is a frequency multiple). A pitch of 1.0 is the default and means no change.


MLAudioGetSoundPitch

MLResult MLAudioGetSoundPitch(
MLHandle handle,
float * out_pitch
)

Returns the pitch of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
float *out_pitchThe pitch that the sound output is set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned pitch of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the pitch is 0.5 to 2.0, with 0.5 being one octave down and 2.0 being one octave up (i.e., the pitch is a frequency multiple). A pitch of 1.0 is the default and means no change.


MLAudioSetSoundMute

MLResult MLAudioSetSoundMute(
MLHandle handle,
bool is_muted
)

Mutes or un-mutes a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
boolis_mutedDetermines whether the sound output is muted or not.

Returns

MLResultMLResult_OkSuccessfully muted or unmuted sound output.
MLResultMLResult_UnspecifiedFailureFailed sound due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed sound due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed sound due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed sound because feature has not been implemented yet.

Required Permissions:

  • None

This mute control is entirely under the control of the owner of the sound output, and is separate from any muting done by the audio policy manager.


MLAudioGetSoundMute

MLResult MLAudioGetSoundMute(
MLHandle handle,
bool * out_is_muted
)

Returns whether a sound output is muted or not.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
bool *out_is_mutedIndicates whether the sound output is muted or not.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully obtained mute state of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

This mute control is entirely under the control of the owner of the sound output, and will not indicate whether the sound output has been muted by the audio policy manager. To find out about the latter, use MLAudioSetSoundEventCallback to register a callback that will provide "policy mute" events.

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

MLHandlehandleMLHandle used to identify the sound output.
boolis_bypassingSets whether the sound output should bypass master volume or not.

Returns

MLResultMLResult_OkSuccessfully set the bypassing state of the sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLResult_IncompatibleSKUFailed due to feature not supported on current device version.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.

Required Permissions:

  • None

Setting this option on a sound output causes its output to bypass 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

MLHandlehandleMLHandle used to identify the sound output.
bool *out_is_bypassingIndicates whether the sound output is bypassing master volume or not.

Returns

MLResultMLResult_OkSuccessfully queried the bypassing state of the sound output.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLResult_IncompatibleSKUFailed due to feature not supported on current device version.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.

Required Permissions:

  • None

This call reports 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

MLHandlehandleMLHandle used to identify the sound output.
boolis_loopingDetermines whether the sound output is looping or not.

Returns

MLResultMLResult_OkSuccessfully set looping of audio.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Looping is available for sound outputs that play files (loaded, streamed, system sounds). The loop goes from the very beginning to the very end of the file. Looping does not apply to sound outputs that are output streams.


MLAudioGetSoundLooping

MLResult MLAudioGetSoundLooping(
MLHandle handle,
bool * out_is_looping
)

Returns whether a sound output is looping or not.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
bool *out_is_loopingIndicates whether the sound output is looping or not.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully obtained looping state of sound output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

API Level:

  • 20

MLAudioSetStreamedFileOffset

MLResult MLAudioSetStreamedFileOffset(
MLHandle handle,
uint32_t offset_in_msec
)

Sets the playback position for a streamed file.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_toffset_in_msecSets the new playback position.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set playback position.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

This function will cause a streaming file to jump to a new location. The playback position is specified in milliseconds. This function can be used while a streaming file is playing, paused or stopped.


MLAudioGetStreamedFileOffset

MLResult MLAudioGetStreamedFileOffset(
MLHandle handle,
uint32_t * out_offset_in_msec
)

Returns the playback position for a streamed file.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_t *out_offset_in_msecIndicates the current playback position.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned playback position for streamed file.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

This function can be used while a streaming file is playing, paused or stopped.


MLAudioGetOutputDevice

MLResult MLAudioGetOutputDevice(
MLAudioOutputDevice * out_current_device
)

Returns which type of sound output device is being used for sound output.

Parameters

MLAudioOutputDevice *out_current_deviceEnum indicating what kind of audio output device is currently in use.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully indicated the type of output device.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed 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 audio output device change.

Parameters

MLAudioOutputDeviceChangedCallbackcallbackMLAudioOutputDeviceChangedCallback function pointer.
void *contextGeneric data pointer passed back to callback.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_OkSuccessfully registered callback.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The callback will be called whenever the output device changes. The current output device is passed back to the callback as its first argument, and the 'context' argument is passed to the callback as its second argument.

API Level:

  • 8

MLAudioResetAcousticScene

MLResult MLAudioResetAcousticScene()

Resets the Acoustic Scene associated with the caller.

Returns

MLResultMLResult_OkIf reset was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundNo custom scene exists for client.

Required Permissions:

  • None

Removes all Acoustic Elements and restores default scene. Resets any modifications to the acoustic scene previously made by the caller.

API Level:

  • 20

MLAudioBeginAcousticSceneUpdate

MLResult MLAudioBeginAcousticSceneUpdate()

Signals beginning of grouped Acoustic parameter multi-update.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The multi-update parameters include global Acoustic Scene params and Acoustic Element params. Intended to be followed by a call to MLAcousticEndAcousticSceneUpdate signifying the end of the multi-update.

API Level:

  • 20

MLAudioEndAcousticSceneUpdate

MLResult MLAudioEndAcousticSceneUpdate()

Signals end of grouped Acoustic parameter multi-update.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundNo custom scene exists for client.

Required Permissions:

  • None

The multi-update parameters include global Acoustic Scene params and Acoustic Element params. Intended to be preceded by a call to MLAcousticBeginAcousticSceneUpdate signifying the beginning of the multi-update.

API Level:

  • 20

MLAudioSetAcousticSceneMapEnable

MLResult MLAudioSetAcousticSceneMapEnable(
bool is_enabled
)

Enables/disables Acoustic Map data for the Acoustic Scene.

Parameters

boolis_enabledDetermines whether Acoustic Map is enabled.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Acoustic Map data is a device-curated representation of the acoustics of the local physical environment. Enabling the Acoustic Map makes virtual objects sound as though they exist in the local environment.

API Level:

  • 20

MLAudioGetAcousticSceneMapEnable

MLResult MLAudioGetAcousticSceneMapEnable(
bool * out_is_enabled
)

Indicates whether Acoustic Map data is enabled for the Acoustic Scene.

Parameters

bool *out_is_enabledIndicates whether Acoustic Map is enabled.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

API Level:

  • 20

MLAudioSetAcousticSceneTransmissionDefault

MLResult MLAudioSetAcousticSceneTransmissionDefault(
const MLAudioMultibandLevel * transmission
)

Sets amount of sound transmitted through non-Acoustic Element objects.

Parameters

const MLAudioMultibandLevel *transmissionMLAudioMultibandLevel to set the default transmission.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Transmission is specified using MLAudioMultibandLevel, which includes gain and 3-band EQ. The values [1, (1, 1, 1)] represents fully transmissive while [0, (1, 1, 1)] or [1, (0, 0, 0)] represents fully obstructed.

API Level:

  • 20

MLAudioGetAcousticSceneTransmissionDefault

MLResult MLAudioGetAcousticSceneTransmissionDefault(
MLAudioMultibandLevel * out_transmission
)

Returns amount of sound transmitted through non-Acoustic Element objects.

Parameters

MLAudioMultibandLevel *out_transmissionMLAudioMultibandLevel to return the default transmission.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Transmission is specified using MLAudioMultibandLevel, which includes gain and 3-band EQ. The values [1, (1, 1, 1)] represents fully transmissive while [0, (1, 1, 1)] or [1, (0, 0, 0)] represents fully obstructed.

API Level:

  • 20

MLAudioSetAcousticSceneDispersionDefault

MLResult MLAudioSetAcousticSceneDispersionDefault(
const MLAudioDispersionProperties * properties
)

Sets the fallback room properties to be used when none are otherwise specified.

Parameters

const MLAudioDispersionProperties *propertiesMLAudioDispersionProperties to set the default dispersion properties.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Dispersion properties are specified using MLAudioDispersionProperties, which includes reflections gain (MLAudioMultibandLevel) and reflections delay time.

API Level:

  • 20

MLAudioGetAcousticSceneDispersionDefault

MLResult MLAudioGetAcousticSceneDispersionDefault(
MLAudioDispersionProperties * out_properties
)

Returns the default room properties used when none are otherwise specified.

Parameters

MLAudioDispersionProperties *out_propertiesMLAudioDispersionProperties to return the default dispersion properties.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Dispersion properties are specified using MLAudioDispersionProperties, which includes reflections gain (MLAudioMultibandLevel) and reflections delay time.

API Level:

  • 20

MLAudioSetAcousticSceneReverbDefault

MLResult MLAudioSetAcousticSceneReverbDefault(
const MLAudioReverbProperties * properties
)

Sets the fallback room properties to be used when none are otherwise specified.

Parameters

const MLAudioReverbProperties *propertiesMLAudioReverbProperties to set the default reverb properties.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Reverb properties are specified using MLAudioReverbProperties, which includes reflections gain (MLAudioMultibandLevel), reflections delay time, reverb gain (MLAudioMultibandLevel), reverb delay time, and frequency-dependent reverb decay times.

API Level:

  • 20

MLAudioGetAcousticSceneReverbDefault

MLResult MLAudioGetAcousticSceneReverbDefault(
MLAudioReverbProperties * out_properties
)

Returns the default room properties used when none are otherwise specified.

Parameters

MLAudioReverbProperties *out_propertiesMLAudioReverbProperties to return the default reverb properties.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Reverb properties are specified using MLAudioReverbProperties, which includes reverb gain (MLAudioMultibandLevel), reverb delay time, and frequency-dependent reverb decay times.

API Level:

  • 20

MLAudioGetChangedAcousticMap

MLResult MLAudioGetChangedAcousticMap(
uint32_t prev_map_tag,
uint8_t ** out_map_data,
uint32_t * out_map_size_in_bytes,
uint32_t * out_map_tag
)

Returns the Acoustic Map if updated since previous call.

Parameters

uint32_tprev_map_tagThe last map tag received in previous call.
uint8_t **out_map_dataReceives serialized Acoustic Map data if map tag is stale.
uint32_t *out_map_size_in_bytesReceives length of serialized Acoustic Map data in bytes.
uint32_t *out_map_tagReceives current map tag, to be passed in following call.

Returns

MLResultMLResult_OkIf call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The Acoustic Map is the system-managed representation of the acoustic environment.

note

Caller is responsible for deallocating the memory used by out_partner_crossfeed_handles and out_partner_crossfeed_outputs.

API Level:

  • 20

MLAudioSetSpatialSoundEnable

MLResult MLAudioSetSpatialSoundEnable(
MLHandle handle,
bool is_enabled
)

Enables/disables 3D audio processing for a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
boolis_enabledDetermines whether 3D processing is on or off.

Returns

MLResultMLResult_OkSuccessfully enabled or disabled 3D audio processing.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The 3D audio processing for a sound output can be turned on or off by this function (default is off). When 3D processing is enabled, the 3D position should be set by calling MLAudioSetSpatialSoundPosition. When 3D processing is disabled, stereo sounds will play their left and right channels directly to the left and right speakers or earphones, and mono sounds will be panned center.


MLAudioGetSpatialSoundEnable

MLResult MLAudioGetSpatialSoundEnable(
MLHandle handle,
bool * out_is_enabled
)

Indicates whether 3D audio processing is enabled for a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
bool *out_is_enabledIndicates whether 3D processing is on or off.

Returns

MLResultMLResult_InvalidParamFailed is enabled due to an invalid parameter.
MLResultMLResult_OkSuccessfully indicated whether 3D audio processing is enabled.
MLResultMLResult_UnspecifiedFailureFailed is enabled due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed is enabled due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed is enabled due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed is enabled because feature has not been implemented yet.

Required Permissions:

  • None

MLAudioSetSpatialSoundPosition

MLResult MLAudioSetSpatialSoundPosition(
MLHandle handle,
uint32_t channel,
const MLVec3f * position
)

Sets the 3D position for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose position is being set.
const MLVec3f *positionMLVec3f struct to set the position.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set 3D position of audio channel.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this funtions sets the perceived position within the user's environment. Multi-channel sounds require the 3D position to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right. Positive x is right. Positive y is up. Positive z is back.


MLAudioGetSpatialSoundPosition

MLResult MLAudioGetSpatialSoundPosition(
MLHandle handle,
uint32_t channel,
MLVec3f * out_position
)

Returns the 3D position for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose position is being read.
MLVec3f *out_positionMLVec3f struct to return the position.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned 3D position of audio channel.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Multi-channel sounds require the 3D position to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right. Positive x is right. Positive y is up. Positive z is back.


MLAudioSetSpatialSoundDirection

MLResult MLAudioSetSpatialSoundDirection(
MLHandle handle,
uint32_t channel,
const MLQuaternionf * direction
)

Sets the radiation direction for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose direction is being set.
const MLQuaternionf *directionMLQuaternionf struct to set the direction.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set radiation direction.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed to set radiation directionS due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

For sounds that have been set to radiate in a directional way by MLAudioSetSpatialSoundRadiation, this function sets the direction of the radiation. Multi-channel sounds require the radiation direction to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.


MLAudioGetSpatialSoundDirection

MLResult MLAudioGetSpatialSoundDirection(
MLHandle handle,
uint32_t channel,
MLQuaternionf * out_direction
)

Returns the radiation direction for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose direction is being read.
MLQuaternionf *out_directionMLQuaternionf struct to return the direction.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned radiation direction.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Multi-channel sounds require the radiation direction to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.


MLAudioSetSpatialSoundBillboarding

MLResult MLAudioSetSpatialSoundBillboarding(
MLHandle id,
bool is_billboarding
)

Sets a mode where the sound always faces the listener.

Parameters

MLHandleidMLHandle Used to identify the sound output.
boolis_billboardingDetermines whether the sound always faces the listener.

Returns

MLResultMLResult_OKIf the call was successful.
MLResultMLAudioResult_HandleNotFoundUnable to find resource handle.
MLResultMLAudioResult_OperationUnavailableUnavailable for this sound.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this call can be used to ensure a spatial sound always faces the listener. This allows the sound's radiation pattern to be used for proper acoustic propagation, while always ensuring the listener hears the sound head on. While this setting is enabled, values set by MLAudioSetSpatialSoundDirection are unused.

API Level:

  • 20

MLAudioGetSpatialSoundBillboarding

MLResult MLAudioGetSpatialSoundBillboarding(
MLHandle id,
bool * out_is_billboarding
)

Indicates whether the sound automatically faces the listener.

Parameters

MLHandleidMLHandle Used to identify the sound output.
bool *out_is_billboardingIndicates whether the sound automatically faces the listener.

Returns

MLResultMLResult_OKSuccessfully returned distance properties.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_OperationUnavailableUnavailable for this sound.

Required Permissions:

  • None

API Level:

  • 20

MLAudioSetSpatialSoundObstruction

MLResult MLAudioSetSpatialSoundObstruction(
MLHandle id,
uint32_t channel,
const MLAudioObstruction * left_ear,
const MLAudioObstruction * right_ear
)

Sets the direct path obstruction for one channel of a sound output.

Parameters

MLHandleidMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose obstruction is being set.
const MLAudioObstruction *left_earMLAudioObstruction for the direct path to left ear.
const MLAudioObstruction *right_earMLAudioObstruction for the direct path to right ear.

Returns

MLResultMLResult_OkIf the call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_OperationUnavailableUnavailable for this sound.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this call sets the obstruction of the direct path from that source to each ear of the listener. Multi-channel sounds require the ear obstructions to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

note

This API property is not intended to be user-specified, but rather set as part of a physics update.

API Level:

  • 20

MLAudioGetSpatialSoundObstruction

MLResult MLAudioGetSpatialSoundObstruction(
MLHandle id,
uint32_t channel,
MLAudioObstruction * out_left_ear,
MLAudioObstruction * out_right_ear
)

Returns the direct path obstruction for one channel of a sound output.

Parameters

MLHandleidMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose obstruction is being set.
MLAudioObstruction *out_left_earMLAudioObstruction to return the obstruction for left ear.
MLAudioObstruction *out_right_earMLAudioObstruction to return the obstruction for right ear.

Returns

MLResultMLResult_OkIf the call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_OperationUnavailableUnavailable for this sound.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Multi-channel sounds require the ear obstructions to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

note

This API property is not intended to be user-specified, but rather set as part of a physics update.

API Level:

  • 20

MLAudioSetSpatialSoundObstructionOverride

MLResult MLAudioSetSpatialSoundObstructionOverride(
MLHandle id,
const MLAudioMultibandLevel * override
)

Sets an override that enables the sound to pass through obstructions.

Parameters

MLHandleidMLHandle Used to identify the sound output.
const MLAudioMultibandLevel *overrideMLAudioMultibandLevel used to set the override.

Returns

MLResultMLResult_OKIf the call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundUnable to find resource handle.
MLResultMLAudioResult_OperationUnavailableUnavailable for this sound.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this call can be used to vary the degree to which the sound passes through obstructions. A MultibandLevel is used to set the override values, 0 representing no change, 1 representing fully transmissive, per band. For multi-channel sounds, all channels are affected equally by the single obstruction override for the sound.

API Level:

  • 20

MLAudioGetSpatialSoundObstructionOverride

MLResult MLAudioGetSpatialSoundObstructionOverride(
MLHandle id,
MLAudioMultibandLevel * out_override
)

Returns the amount of the sound obstruction override.

Parameters

MLHandleidMLHandle Used to identify the sound output.
MLAudioMultibandLevel *out_overrideMLAudioMultibandLevel used to return the override.

Returns

MLResultMLResult_OKIf the call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundUnable to find resource handle.
MLResultMLAudioResult_OperationUnavailableUnavailable for this sound.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Obstruction override is returned as a MultibandLevel, with 0 representing no change and 1 representing fully transmissive, per band. For multi-channel sounds, all channels are affected equally by the single obstruction override for the sound.

API Level:

  • 20

MLAudioSetSpatialSoundDistanceAttenuation

MLResult MLAudioSetSpatialSoundDistanceAttenuation(
MLHandle handle,
uint32_t channel,
const MLAudioSpatialSoundDistanceProperties * properties
)

Sets the distance properties for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose distance properties are being set.
const MLAudioSpatialSoundDistanceProperties *propertiesMLAudioSpatialSoundDistanceProperties struct to set the properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets the way in which distance affects sound volume. Multi-channel sounds require the distance properties to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioGetSpatialSoundDistanceAttenuation

MLResult MLAudioGetSpatialSoundDistanceAttenuation(
MLHandle handle,
uint32_t channel,
MLAudioSpatialSoundDistanceProperties * out_properties
)

Returns the distance properties for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose distance properties are being read.
MLAudioSpatialSoundDistanceProperties *out_propertiesMLAudioSpatialSoundDistanceProperties struct to return the properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Multi-channel sounds require the distance properties to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioSetSpatialSoundRadiation

MLResult MLAudioSetSpatialSoundRadiation(
MLHandle handle,
uint32_t channel,
const MLAudioSpatialSoundRadiationProperties * properties
)

Sets the radiation properties for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose radiation properties are being set.
const MLAudioSpatialSoundRadiationProperties *propertiesMLAudioSpatialSoundRadiationProperties struct to set the properties.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set radiation properties.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets the degree of directionality in the sound projection. The default setting is for sounds to be omnidirectional (equal projection in all directions). Multi-channel sounds require the radiation properties to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioGetSpatialSoundRadiation

MLResult MLAudioGetSpatialSoundRadiation(
MLHandle handle,
uint32_t channel,
MLAudioSpatialSoundRadiationProperties * out_properties
)

Returns the radiation properties for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose radiation properties are being set.
MLAudioSpatialSoundRadiationProperties *out_propertiesMLAudioSpatialSoundRadiationProperties struct to return the properties.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned radiation properties.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Multi-channel sounds require the radiation properties to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioSetSpatialSoundDirectLevel

MLResult MLAudioSetSpatialSoundDirectLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)

Sets the direct sound level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose direct level is being set.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set direct send levels.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the direct component of the sound, i.e., the audio mix for the part of the sound not affected by room acoustics. Multi-channel sounds require the direct send levels to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioGetSpatialSoundDirectLevel

MLResult MLAudioGetSpatialSoundDirectLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)

Returns the direct sound level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose direct level is being read.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to return the gain and eq.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned direct send levels.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Multi-channel sounds require the direct sound level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioSetSpatialSoundIndirectLevel

MLResult MLAudioSetSpatialSoundIndirectLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)

Sets the indirect sound level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose indirect sound level is being set.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the indirect component of the sound, i.e., the audio mix for the part of the sound that's affected by room acoustics (includes reflections and reverb). Multi-channel sounds require the indirect sound level to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioGetSpatialSoundIndirectLevel

MLResult MLAudioGetSpatialSoundIndirectLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)

Returns the indirect sound level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose indirect sound level is being read.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to return the gain and eq.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Multi-channel sounds require the indirect sound level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioSetSpatialSoundDispersionSendLevel

MLResult MLAudioSetSpatialSoundDispersionSendLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)

Sets the dispersion level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose dispersion level is being set.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set room send levels.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the dispersion component of the sound, i.e., the audio mix for late clustered reflections caused by room acoustics (also controlled by MLAudioSetSpatialSoundIndirectLevel). Multi-channel sounds require the dispersion level to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioGetSpatialSoundDispersionSendLevel

MLResult MLAudioGetSpatialSoundDispersionSendLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)

Returns the dispersion level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose dispersion level is being read.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to return the gain and eq.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned room send levels.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Multi-channel sounds require the dispersion level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioSetSpatialSoundReverbSendLevel

MLResult MLAudioSetSpatialSoundReverbSendLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)

Sets the reverb level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose reverb level is being set.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the reverb component of the sound, i.e., the audio mix for late reverberation caused by room acoustics (also controlled by MLAudioSetSpatialSoundIndirectLevel). Multi-channel sounds require the reverb level to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioGetSpatialSoundReverbSendLevel

MLResult MLAudioGetSpatialSoundReverbSendLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)

Returns the reverb level for one channel of a sound output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint32_tchannelSelects the channel whose reverb level is being read.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to return the gain and eq.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkIf the call was successful.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Multi-channel sounds require the reverb level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.

API Level:

  • 20

MLAudioSetSpatialSoundHeadRelative

MLResult MLAudioSetSpatialSoundHeadRelative(
MLHandle handle,
bool is_head_relative
)

Sets whether the coordinates for a sound output are head relative.

Parameters

MLHandlehandleMLHandle Used to identify the sound output.
boolis_head_relativeDetermines whether the coordinates are head relative.

Returns

MLResultMLResult_OkSuccessfully set the relative state of coordinates.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown failure.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

This call can be used to make the coordinate system of the specified sound be head relative, in which case the user's head position and orientation are ignored when simulating the sound's spatial position and direction. This is useful for sounds attached to graphics objects that don't use headpose, or when the desired effect is for sound position and direction to be fixed relative to the head. Head relative sounds always point at the user's head like "billboarding" graphics. If a sound is not explicitly told to use head relative coordinates, world coordinates are used by default.

API Level:

  • 7

MLAudioGetSpatialSoundHeadRelative

MLResult MLAudioGetSpatialSoundHeadRelative(
MLHandle handle,
bool * out_is_head_relative
)

Returns whether the coordinates for a sound output are head relative.

Parameters

MLHandlehandleMLHandle Used to identify the sound output.
bool *out_is_head_relativeIndicates whether the coordinates are head relative.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned whether coordinates are head relative.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown failure.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

This call can be used to determine if the coordinate system of the specified sound has been set to be head relative.

API Level:

  • 20

MLAudioGetSpatialRaycastRequests

MLResult MLAudioGetSpatialRaycastRequests(
MLAudioRaycastRequest ** out_raycast_requests,
uint32_t * out_request_count
)

Returns a list of ID-tracked requests for raycast operations.

Parameters

MLAudioRaycastRequest **out_raycast_requestsReturns list of requests for raycast operation.
uint32_t *out_request_countReturns number of raycast operations requested.

Returns

MLResultMLResult_OkIf the call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None
note
  • This function is not intended to be called directly by developers.
  • The caller is responsible for deallocating the memory containing the raycast requests.

API Level:

  • 20

MLAudioSetSpatialRaycastResults

MLResult MLAudioSetSpatialRaycastResults(
MLAudioRaycastResult * raycast_results,
uint32_t result_count
)

Sets the ID-tracked results for previously requested raycast operations.

Parameters

MLAudioRaycastResult *raycast_resultsSets the list of raycast operation results.
uint32_tresult_countSets the number of raycast results.

Returns

MLResultMLResult_OkIf the call was successful.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None
note

This function is not intended to be called directly by developers.

API Level:

  • 20

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
)

Returns the preferred (i.e. best performing) settings for buffered output.

Parameters

uint32_tchannel_countNumber of audio channels (e.g. 2 for stereo).
uint32_tsamples_per_secondSample rate for the buffered output.
floatmax_pitch_changeTop pitch (1.0 - 2.0) for this sound output.
MLAudioBufferFormat *out_formatRecommended settings for MLAudioBufferFormat.
uint32_t *out_recommended_size_in_bytesRecommended size for the buffers.
uint32_t *out_min_size_in_bytesMinimum allowable size for the buffers.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned preferred settings for buffered output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

API Level:

  • 7

MLAudioGetBufferedOutputLatency

MLResult MLAudioGetBufferedOutputLatency(
MLHandle handle,
float * out_latency_in_msec
)

Returns the latency for a buffered output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
float *out_latency_in_msecIndicates the latency in milliseconds.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned latency for buffered output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

This function returns the latency between the time a buffer is enqueued via MLAudioReleaseOutputBuffer and the time its audio is heard at the speakers or earphones.

API Level:

  • 7

MLAudioGetBufferedOutputFramesPlayed

MLResult MLAudioGetBufferedOutputFramesPlayed(
MLHandle handle,
uint64_t * out_frames_played
)

Returns the number of audio frames played by a buffered output.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
uint64_t *out_frames_playedThe number of audio frames played.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned number of audio frames by buffered output.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

This function returns the number of frames that have been sent down to the audio mixer (-not- the number that have been passed to the buffers) since the last time MLAudioStartSound was called for this output. Note that the perceived sound may be slightly behind this value due to the buffer latency (which can be queried by calling MLAudioGetBufferedOutputLatency). Pausing and resuming does not affect the frame count.

API Level:

  • 7

MLAudioGetOutputBuffer

MLResult MLAudioGetOutputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)

Returns an empty buffer for writing more buffered data.

Parameters

MLHandlehandleMLHandle used to identify the sound output.
MLAudioBuffer *out_bufMLAudioBuffer containing the buf to write into.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned empty buffer.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_BufferNotReadyFailed because buffer was not ready.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

This function returns an output buffer when one of the output buffers is empty and needs more data. It is possible to call this function in a polling fashion. However for greater efficiency it is recommended to provide a callback to the 'create' function (in which case this function may be called from within the callback).

API Level:

  • 7

MLAudioReleaseOutputBuffer

MLResult MLAudioReleaseOutputBuffer(
MLHandle handle
)

Releases a buffer once it has been filled.

Parameters

MLHandlehandleMLHandle used to identify the sound output.

Returns

MLResultMLResult_OkSuccessfully released buffer.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_BufferNotReadyFailed because buffer was not ready.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

After receiving an empty buffer from MLAudioGetOutputBuffer and writing audio data into that buffer, call this function to indicate that the buffer has been filled and can now be played.

API Level:

  • 7

MLAudioGetMasterVolume

MLResult MLAudioGetMasterVolume(
float * out_volume
)

Returns the master volume for the audio system.

Parameters

float *out_volumeThe current setting of master volume.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully return master volume.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of the volume is 0-100, with 0 being silent and 100 being full volume.


MLAudioSetMasterVolumeCallback

MLResult MLAudioSetMasterVolumeCallback(
MLAudioMasterVolumeChangedCallback callback,
void * context
)

Registers a callback for changes to the master volume.

Parameters

MLAudioMasterVolumeChangedCallbackcallbackMLAudioMasterVolumeChangedCallback function pointer.
void *contextGeneric data pointer passed back to callback.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_OkSuccessfully register callback to the master volume.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The callback will be called whenever the master volume gets changed (even if changed by the owner of the callback). The 'context' argument is passed back to the callback as its first argument, and the new master volume setting is passed to the callback as its second argument.


MLAudioGetOutputMute

MLResult MLAudioGetOutputMute(
bool * out_is_muted
)

Indicates whether the output mute of the audio system is on or off.

Parameters

bool *out_is_mutedIndicates whether the audio output is muted or not.

Returns

MLResultMLResult_OkSuccessfully indicated state of output mute.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown failure.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Queries the current status of the output mute.

API Level:

  • 20

MLAudioSetOutputMuteCallback

MLResult MLAudioSetOutputMuteCallback(
MLAudioOutputMuteChangedCallback callback,
void * context
)

Registers a callback for audio output mute change.

Parameters

MLAudioOutputMuteChangedCallbackcallbackMLAudioOutputMuteChangedCallback function pointer.
void *contextGeneric data pointer passed back to callback.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_OkSuccessfully registered callback for audio output mute change.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The callback will be called whenever the output mute changes (even if changed by the owner of the callback). The output mute setting is passed back to the callback as its first argument, and the 'context' argument is passed to the callback as its second argument.

API Level:

  • 8

MLAudioCreateInputFromMicCapture

MLResult MLAudioCreateInputFromMicCapture(
MLAudioMicCaptureType mic_capture_type,
const MLAudioBufferFormat * format,
uint32_t buffer_size_in_bytes,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)

Creates a new sound input that provides audio from the mics on the wearable.

Parameters

MLAudioMicCaptureTypemic_capture_typeMLAudioMicCaptureType specifying the type of mic capture created.
const MLAudioBufferFormat *formatMLAudioBufferFormat specifying the audio format of the stream.
uint32_tbuffer_size_in_bytesRequested size in bytes for each of the two stream buffers.
MLAudioBufferCallbackcallbackMLAudioBufferCallback function pointer.
void *contextGeneric data pointer passed back to callback.
MLHandle *out_handleMLHandle used in subsequent calls for this sound input.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created new sound input that provides a mic capture stream.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to an invalid bits per sample.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleFormatFailed due to an invalid sample format.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidValidBitsFailed due to an invalid valid bits per sample.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • android.permission.RECORD_AUDIO (protection level: dangerous)

Creates a sound input and allocates a double-buffer for streaming audio data from it. The 'mic_capture_type' argument specifies the "flavor" of the microphone capture, and the MLAudioMicCaptureType enum lists the available buffering formats for each flavor. To stream data from the buffers call MLAudioGetInputBuffer to get a full buffer, then read the data from the buffer, then call MLAudioReleaseInputBuffer to indicate that the buffer is ready to re-use. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument specifies the format of the buffering which must agree with the selected 'mic_capture_type'. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, the input can be started by calling MLAudioStartInput.

API Level:

  • 20

MLAudioCreateInputFromVirtualCapture

MLResult MLAudioCreateInputFromVirtualCapture(
const MLAudioBufferFormat * format,
uint32_t buffer_size,
MLAudioBufferCallback callback,
void * callback_context,
MLHandle * out_handle
)

Creates a new sound input that provides a "virtual capture" stream.

Parameters

const MLAudioBufferFormat *formatMLAudioBufferFormat specifying the audio format of the stream.
uint32_tbuffer_sizeRequested size in bytes for each of the two stream buffers.
MLAudioBufferCallbackcallbackMLAudioBufferCallback function pointer.
void *callback_contextGeneric data pointer passed back to callback.
MLHandle *out_handleMLHandle used in subsequent calls for this sound input.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created new sound input that provides a "virtual capture" stream.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to an invalid bits per sample.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleFormatFailed due to an invalid sample format.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidValidBitsFailed due to an invalid valid bits per sample.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Creates a sound input and allocates a double-buffer for streaming audio data from it. The "virtual capture" stream provides a stereo stream capturing the final audio output mix of all the sounds currently being played by the audio system. To stream data from the buffers call MLAudioGetInputBuffer to get a full buffer, then read the data from the buffer, then call MLAudioReleaseInputBuffer to indicate that the buffer is ready to re-use. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument specifies the format of which the following are supported: Two channels (stereo), 16 bit integer, a sampling rate of 48k. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, the input can be started by calling MLAudioStartInput.

API Level:

  • 8

MLAudioCreateInputFromMixedCapture

MLResult MLAudioCreateInputFromMixedCapture(
const MLAudioBufferFormat * format,
uint32_t buffer_size,
MLAudioBufferCallback callback,
void * callback_context,
MLHandle * out_handle
)

Creates a new sound input that provides a "mixed capture" stream.

Parameters

const MLAudioBufferFormat *formatMLAudioBufferFormat specifying the audio format of the stream.
uint32_tbuffer_sizeRequested size in bytes for each of the two stream buffers.
MLAudioBufferCallbackcallbackMLAudioBufferCallback function pointer.
void *callback_contextGeneric data pointer passed back to callback.
MLHandle *out_handleMLHandle used in subsequent calls for this sound input.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created new sound input that provides a "mixed capture" stream.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_InvalidBitsPerSampleFailed due to an invalid bits per sample.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleFormatFailed due to an invalid sample format.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_InvalidValidBitsFailed due to an invalid valid bits per sample.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Creates a sound input and allocates a double-buffer for streaming audio data from it. The "mixed capture" stream provides a stereo stream capturing the final audio output mix of all the sounds currently being played by the audio system (same as "virtual capture"), plus the user's voice processed for communications (same as MLAudioMicCaptureType_VoiceComm). To stream data from the buffers call MLAudioGetInputBuffer to get a full buffer, then read the data from the buffer, then call MLAudioReleaseInputBuffer to indicate that the buffer is ready to re-use. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument supports a variety of audio formats, and the preferred format can be determined in advance by calling MLAudioGetBufferedInputDefaults. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, the input can be started by calling MLAudioStartInput.

API Level:

  • 8

MLAudioDestroyInput

MLResult MLAudioDestroyInput(
MLHandle handle
)

Destroys a previously created sound input.

Parameters

MLHandlehandleMLHandle used to identify the sound input.

Returns

MLResultMLResult_OkSuccessfully destroyed previously created sound input.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

MLAudioStartInput

MLResult MLAudioStartInput(
MLHandle handle
)

Starts capture for a sound input.

Parameters

MLHandlehandleMLHandle used to identify the sound input.

Returns

MLResultMLResult_OkSuccessfully started capture for sound input.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

MLAudioStopInput

MLResult MLAudioStopInput(
MLHandle handle
)

Stops capture for a sound input.

Parameters

MLHandlehandleMLHandle used to identify the sound input.

Returns

MLResultMLResult_OkSuccessfully stopped capture for sound input.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

MLAudioGetInputState

MLResult MLAudioGetInputState(
MLHandle handle,
MLAudioState * out_state
)

Indicates the play state of a sound input.

Parameters

MLHandlehandleMLHandle used to identify the sound input.
MLAudioState *out_stateIndicates the current play state.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully indicated play state of sound input.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The MLAudioState indicates whether the sound input is stopped or playing.


MLAudioGetBufferedInputDefaults

MLResult MLAudioGetBufferedInputDefaults(
uint32_t channel_count,
uint32_t samples_per_second,
MLAudioBufferFormat * out_format,
uint32_t * out_recommended_size_in_bytes,
uint32_t * out_min_size_in_bytes
)

Returns the preferred (i.e. best performing) settings for buffered input.

Parameters

uint32_tchannel_countNumber of audio channels (e.g. 2 for stereo).
uint32_tsamples_per_secondSample rate for the buffered input.
MLAudioBufferFormat *out_formatRecommended Settings for MLAudioBufferFormat.
uint32_t *out_recommended_size_in_bytesRecommended size for the buffers.
uint32_t *out_min_size_in_bytesMinimum allowable size for the buffers.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned the preferred settings for buffered input.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InvalidChannelCountFailed due to an invalid channel count.
MLResultMLAudioResult_InvalidSampleRateFailed due to an invalid sample rate.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

API Level:

  • 7

MLAudioGetBufferedInputLatency

MLResult MLAudioGetBufferedInputLatency(
MLHandle handle,
float * out_latency_in_msec
)

Returns the latency for a sound input.

Parameters

MLHandlehandleMLHandle used to identify the sound input.
float *out_latency_in_msecIndicates the latency in milliseconds.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned the latency for sound input.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

This function returns the latency between the time a sound occurs in the real world and the time it becomes available via MLAudioGetInputBuffer.

API Level:

  • 7

MLAudioGetInputBuffer

MLResult MLAudioGetInputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)

Returns a full buffer containing captured audio data.

Parameters

MLHandlehandleMLHandle used to identify the sound input.
MLAudioBuffer *out_bufMLAudioBuffer containing the buf to read from.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned full buffer containing captured audio data.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_BufferNotReadyFailed because buffer was not ready.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

This function returns a buffer when one of the input buffers is full and needs to be read. It is possible to call this function in a polling fashion. However for greater efficiency it is recommended to provide a callback to the 'create' function (in which case this function may be called from within the callback).

API Level:

  • 7

MLAudioReleaseInputBuffer

MLResult MLAudioReleaseInputBuffer(
MLHandle handle
)

Releases a buffer once it has been read.

Parameters

MLHandlehandleMLHandle used to identify the sound input.

Returns

MLResultMLResult_OkSuccessfully released buffer.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_BufferNotReadyFailed because buffer was not ready.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configurations error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

After receiving a full buffer from MLAudioGetInputBuffer and reading the audio data from that buffer, call this function to indicate that the buffer has been read and can now be re-used.

API Level:

  • 7

MLAudioSetMicMute

MLResult MLAudioSetMicMute(
bool is_muted
)

Mutes or un-mutes all microphone capture.

Parameters

boolis_mutedDetermines whether mic capture is muted or not.

Returns

MLResultMLResult_OkSuccessfully Successfully muted or unmuted microphone capture.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • android.permission.RECORD_AUDIO (protection level: dangerous)

This mute control applies to all microphone capture in general (excluding "recognizer voice" which is always active). When mic capture is muted or unmuted by one app, it is muted or unmuted for all apps. Note: This setting is separate from any muting done by the audio policy manager (such as when the "reality button" is pressed).


MLAudioGetMicMute

MLResult MLAudioGetMicMute(
bool * out_is_muted
)

Returns whether all microphone capture is muted or not.

Parameters

bool *out_is_mutedIndicates whether the mic capture is muted or not.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully indicated whether microphone is muted.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • android.permission.RECORD_AUDIO (protection level: dangerous)

API Level:

  • 20

MLAudioSetMicMuteCallback

MLResult MLAudioSetMicMuteCallback(
MLAudioMicMuteCallback callback,
void * context
)

Registers a callback for changes to the global mic mute.

Parameters

MLAudioMicMuteCallbackcallbackMLAudioMicMuteCallback function pointer.
void *contextGeneric data pointer passed back to callback.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_OkSuccessfully registered callback.
MLResultMLResult_PermissionDeniedFailed due to lack of permission.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • android.permission.RECORD_AUDIO (protection level: dangerous)

The callback will be called whenever the global mic mute gets changed (even if changed by the owner of the callback). The 'context' argument is passed back to the callback as its first argument, and the new mic mute setting is passed to the callback as its second argument.


MLAudioBeginTraitAnalysisFromMicCapture

MLResult MLAudioBeginTraitAnalysisFromMicCapture(
MLAudioTraitAnalysisTarget target,
MLAudioTraitAnalysisCallback callback,
void * callback_context,
MLHandle * out_handle
)

Creates a new analysis input for the specified target.

Parameters

MLAudioTraitAnalysisTargettargetMLAudioTraitAnalysisTarget specifies the analysis target.
MLAudioTraitAnalysisCallbackcallbackMLAudioTraitAnalysisCallback function pointer.
void *callback_contextGeneric data pointer passed back to callback.
MLHandle *out_handleMLHandle used to identify this analysis in subsequent calls.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set control frequencies.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.

Required Permissions:

  • None

Creates a trait analysis, initializes its connection to the device microphones as the audio data source, and returns a handle in the 'out_handle' argument. The 'target' argument specifies the type of trait analysis, which implies the type of audio content to be analyzed. Trait analysis results are returned as a single float, whose meaning is context dependent based on the target. Results may be acquired either on a polling basis by calling MLAudioGetTraitAnalysis, or via a callback set by the optional 'callback' argument of this function.

API Level:

  • 20

MLAudioGetTraitAnalysis

MLResult MLAudioGetTraitAnalysis(
MLHandle handle,
float * out_value
)

Returns the current value of the trait analysis associated with the specified handle.

Parameters

MLHandlehandleMLHandle used to identify the analysis.
float *out_valueCurrent value of analysis.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned control frequencies.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImpelmentedreturn control frequencies because feature has not been implemented yet.

Required Permissions:

  • None

API Level:

  • 20

MLAudioEndTraitAnalysis

MLResult MLAudioEndTraitAnalysis(
MLHandle handle
)

Stops a previously started trait analysis.

Parameters

MLHandlehandleMLHandle used to identify the analysis.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned empty buffe for writing more stream data.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.

Required Permissions:

  • None

Stops the analysis associated with the specified handle.

API Level:

  • 20

MLAudioBeginSpectralAnalysisFromMicCapture

MLResult MLAudioBeginSpectralAnalysisFromMicCapture(
MLAudioSpectralAnalysisTarget target,
MLAudioSpectralAnalysisCallback callback,
void * callback_context,
MLHandle * out_handle
)

Starts a new spectral analysis that provides frequency spectrum energy derived from mic signals.

Parameters

MLAudioSpectralAnalysisTargettargetMLAudioSpectralAnalysisTarget specifies the analysis target.
MLAudioSpectralAnalysisCallbackcallbackMLAudioSpectralAnalysisCallback function pointer.
void *callback_contextGeneric data pointer passed back to callback.
MLHandle *out_handleMLHandle used to identify this analysis in subsequent calls.

Returns

MLResultMLResult_OKSuccessfully released buffer.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.

Required Permissions:

  • None

Creates a spectral analysis, initializes its connection to the device microphones as the audio data source, and returns a handle in the 'out_handle' argument. The 'target' argument specifies the type of spectral analysis, which implies the type of audio content to be analyzed. Spectral analysis results are returned in the MLAudioSpectralAnalysis struct, which contains a time window of spectral analysis values. Results may be acquired either on a polling basis by calling MLAudioGetSpectralAnalysis, or via a callback set by the optional 'callback' argument of this function, triggered whenever new values are available. Cleanup of MLAudioSpectralAnalysis passed in the optional callback is handled by the ml_audio library; the caller is not responsible for deallocating memory if the callback is used.

API Level:

  • 20

MLAudioGetSpectralAnalysis

MLResult MLAudioGetSpectralAnalysis(
MLHandle handle,
MLAudioSpectralAnalysis * out_values
)

Returns the current value of the spectral analysis associated with the specified handle.

Parameters

MLHandlehandleMLHandle used to identify the analysis.
MLAudioSpectralAnalysis *out_valuesMLAudioSpectralAnalysis containing the current values of a spectral analysis.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully returned latency for sound input.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

Allocates memory at out_values->values based on the MLAudioSpectralAnalysisTarget associated with the specified handle. The caller is responsible for deallocating this memory after each call to MLAudioGetSpectralAnalysis.

API Level:

  • 20

MLAudioEndSpectralAnalysis

MLResult MLAudioEndSpectralAnalysis(
MLHandle handle
)

Stops a previously started spectral analysis.

Parameters

MLHandlehandleMLHandle used to identify the analysis.

Returns

MLResultMLResult_OKSuccessfully stopped spectral analysis.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.

Required Permissions:

  • None

Stops the analysis associated with the specified handle.

API Level:

  • 20

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%

#pragma once

#include "ml_api.h"
#include "ml_types.h"

ML_EXTERN_C_BEGIN



typedef enum MLAudioState {
MLAudioState_Stopped,
MLAudioState_Playing,
MLAudioState_Paused,
MLAudioState_Ensure32Bits = 0x7FFFFFFF
} MLAudioState;

typedef enum MLAudioSoundEvent {
MLAudioSoundEvent_End,
MLAudioSoundEvent_Loop,
MLAudioSoundEvent_MutedBySystem,
MLAudioSoundEvent_UnmutedBySystem,
MLAudioSoundEvent_DuckedBySystem,
MLAudioSoundEvent_UnduckedBySystem,
MLAudioSoundEvent_ResourceDestroyed,
MLAudioSoundEvent_Ensure32Bits = 0x7FFFFFFF
} MLAudioSoundEvent;

typedef enum MLAudioMediaEvent {
MLAudioMediaEvent_Play,
MLAudioMediaEvent_Stop,
MLAudioMediaEvent_Pause,
MLAudioMediaEvent_NextTrack,
MLAudioMediaEvent_PrevTrack,
MLAudioMediaEvent_Ensure32Bits = 0x7FFFFFFF
} MLAudioMediaEvent;

typedef enum MLAudioOutputDevice {
MLAudioOutputDevice_Wearable,
MLAudioOutputDevice_USB,
MLAudioOutputDevice_Bluetooth,
MLAudioOutputDevice_HearingAid,
MLAudioOutputDevice_Ensure32Bits = 0x7FFFFFFF
} MLAudioOutputDevice;
typedef enum MLAudioMicCaptureType {
MLAudioMicCaptureType_VoiceComm,
MLAudioMicCaptureType_VoiceCapture,
MLAudioMicCaptureType_WorldCapture=4,
MLAudioMicCaptureType_RawMicsAndAECRef,
MLAudioMicCaptureType_Ensure32Bits=0x7FFFFFFF
} MLAudioMicCaptureType;

typedef struct MLAudioMultibandLevel {
float main;
float lf;
float mf;
float hf;
} MLAudioMultibandLevel;


typedef struct MLAudioDispersionProperties {
MLAudioMultibandLevel gain;
float pre_delay;
} MLAudioDispersionProperties;

typedef struct MLAudioReverbProperties {
MLAudioMultibandLevel gain;
float pre_delay;
float decay_time;
float decay_time_lf_ratio;
float decay_time_hf_ratio;
} MLAudioReverbProperties;


typedef struct MLAudioSpatialSoundDistanceProperties {
float min_distance;
float max_distance;
float rolloff_factor;
} MLAudioSpatialSoundDistanceProperties;

typedef struct MLAudioSpatialSoundRadiationProperties {
float inner_angle;
float outer_angle;
float outer_gain;
float outer_gain_lf;
float outer_gain_mf;
float outer_gain_hf;
} MLAudioSpatialSoundRadiationProperties;

typedef struct MLAudioRaycast {
MLVec3f eye_point;
MLVec3f end_point;
} MLAudioRaycast;

typedef struct MLAudioObstruction {
float factor;
MLVec3f hit_point;
} MLAudioObstruction;

typedef struct MLAudioRaycastRequest {
MLHandle source_id;
MLHandle image_id;
uint32_t leg_index;
MLAudioRaycast ray;
} MLAudioRaycastRequest;

typedef struct MLAudioRaycastResult {
MLHandle source_id;
MLHandle image_id;
uint32_t leg_index;
MLAudioRaycast ray;
MLAudioObstruction obstruction;
} MLAudioRaycastResult;

typedef enum MLAudioSampleFormat {
MLAudioSampleFormat_Int,
MLAudioSampleFormat_Float,
MLAudioSampleFormat_Ensure32Bits = 0x7FFFFFFF
} MLAudioSampleFormat;

typedef enum MLAudioChannelFormat {
MLAudioChannelFormat_Default,
MLAudioChannelFormat_AmbisonicAmbix,
MLAudioChannelFormat_Ensure32Bits = 0x7FFFFFFF,
} MLAudioChannelFormat;

typedef struct MLAudioBufferFormat {
uint32_t channel_count;
uint32_t samples_per_second;
uint32_t bits_per_sample;
uint32_t valid_bits_per_sample;
MLAudioSampleFormat sample_format;
MLAudioChannelFormat channel_format;
} MLAudioBufferFormat;

typedef struct MLAudioBuffer {
uint8_t *ptr;
uint32_t size;
} MLAudioBuffer;

typedef enum MLAudioTraitAnalysisTarget {
MLAudioTraitAnalysisTarget_AmbientSoundLevelDbfs,
MLAudioTraitAnalysisTarget_UserVoicePresence,
MLAudioTraitAnalysisTarget_UserVoiceLevelDbfs,
MLAudioTraitAnalysisTarget_UserVoicePitch,
MLAudioTraitAnalysisTarget_Ensure32Bits = 0x7FFFFFFF
} MLAudioTraitAnalysisTarget;

typedef enum MLAudioSpectralAnalysisTarget {
MLAudioSpectralAnalysisTarget_UserVoiceSpectrumMfcc,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumBark,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumMel,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumThirdOctave,
MLAudioSpectralAnalysisTarget_Ensure32Bits = 0x7FFFFFFF
} MLAudioSpectralAnalysisTarget;

typedef struct MLAudioSpectralAnalysis {
float *values;
int32_t num_columns;
int32_t num_rows;
} MLAudioSpectralAnalysis;

enum {
MLResultAPIPrefix_Audio = MLRESULT_PREFIX(0x9e11)
};

typedef enum MLAudioResult {
MLAudioResult_NotImplemented = MLResultAPIPrefix_Audio,
MLAudioResult_HandleNotFound,
MLAudioResult_InvalidSampleRate,
MLAudioResult_InvalidBitsPerSample,
MLAudioResult_InvalidValidBits,
MLAudioResult_InvalidSampleFormat,
MLAudioResult_InvalidChannelCount,
MLAudioResult_InvalidBufferSize,
MLAudioResult_BufferNotReady,
MLAudioResult_FileNotFound,
MLAudioResult_FileNotRecognized,
MLAudioResult_ResourceNotFound,
MLAudioResult_ResourceDiscarded,
MLAudioResult_OperationUnavailable,
MLAudioResult_OperationNotReady,
MLAudioResult_InternalConfigError,
MLAudioResult_Ensure32Bits = 0x7FFFFFFF
} MLAudioResult;

ML_API const char* ML_CALL MLAudioGetResultString(MLResult result_code);

typedef void (*MLAudioSoundEventCallback)(MLHandle handle, MLAudioSoundEvent event, void *context);

typedef void (*MLAudioMediaEventCallback)(MLAudioMediaEvent event, void *context);

typedef void (*MLAudioBufferCallback)(MLHandle handle, void *context);

typedef void (*MLAudioResourceDiscardedCallback)(MLHandle resource, void *context);

typedef void (*MLAudioMasterVolumeChangedCallback)(float new_volume, void *context);

typedef void (*MLAudioOutputMuteChangedCallback)(bool is_muted, void *context);

typedef void (*MLAudioOutputDeviceChangedCallback)(MLAudioOutputDevice current_device, void *context);

typedef void (*MLAudioMicMuteCallback)(bool is_muted, void *context);

typedef void (*MLAudioTraitAnalysisCallback)(MLHandle handle, MLAudioTraitAnalysisTarget target, float value, void *context);

typedef void (*MLAudioSpectralAnalysisCallback)(MLHandle handle, MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysis values, void *context);


ML_API MLResult ML_CALL MLAudioCreateLoadedResource(int file, bool dynamic_decode, MLAudioResourceDiscardedCallback callback, void *context, MLHandle *out_resource);

ML_API MLResult ML_CALL MLAudioCreateStreamedResource(int file, MLAudioResourceDiscardedCallback callback, void *context, MLHandle *out_resource);

ML_API MLResult ML_CALL MLAudioCheckResource(MLHandle resource, bool *out_is_ready);

ML_API MLResult ML_CALL MLAudioGetResourceSize(MLHandle resource, uint32_t *out_size_in_bytes);

ML_API MLResult ML_CALL MLAudioRefreshResource(MLHandle resource, int file);

ML_API MLResult ML_CALL MLAudioDestroyResource(MLHandle resource);

ML_API MLResult ML_CALL MLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateSoundWithLoadedFile(int file, bool auto_destroy, bool dynamic_decode, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateSoundWithStreamedFile(int file, bool auto_destroy, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateSoundWithBufferedOutput(const MLAudioBufferFormat *format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void *context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioDestroySound(MLHandle handle);

ML_API MLResult ML_CALL MLAudioStartSound(MLHandle handle);

ML_API MLResult ML_CALL MLAudioStopSound(MLHandle handle);

ML_API MLResult ML_CALL MLAudioPauseSound(MLHandle handle);

ML_API MLResult ML_CALL MLAudioResumeSound(MLHandle handle);

ML_API MLResult ML_CALL MLAudioGetSoundState(MLHandle handle, MLAudioState *out_state);

ML_API MLResult ML_CALL MLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat *out_format);

ML_API MLResult ML_CALL MLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void *context);

ML_API MLResult ML_CALL MLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void *context);


ML_API MLResult ML_CALL MLAudioSetSoundVolumeLinear(MLHandle handle, float volume);

ML_API MLResult ML_CALL MLAudioGetSoundVolumeLinear(MLHandle handle, float *out_volume);

ML_API MLResult ML_CALL MLAudioSetSoundVolumeDb(MLHandle handle, float volume);

ML_API MLResult ML_CALL MLAudioGetSoundVolumeDb(MLHandle handle, float *out_volume);

ML_API MLResult ML_CALL MLAudioSetSoundPitch(MLHandle handle, float pitch);

ML_API MLResult ML_CALL MLAudioGetSoundPitch(MLHandle handle, float *out_pitch);

ML_API MLResult ML_CALL MLAudioSetSoundMute(MLHandle handle, bool is_muted);

ML_API MLResult ML_CALL MLAudioGetSoundMute(MLHandle handle, bool *out_is_muted);

ML_API MLResult ML_CALL MLAudioSetSoundBypassesMasterVolume(MLHandle handle, bool is_bypassing);

ML_API MLResult ML_CALL MLAudioGetSoundBypassesMasterVolume(MLHandle handle, bool *out_is_bypassing);

ML_API MLResult ML_CALL MLAudioSetSoundLooping(MLHandle handle, bool is_looping);

ML_API MLResult ML_CALL MLAudioGetSoundLooping(MLHandle handle, bool *out_is_looping);

ML_API MLResult ML_CALL MLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec);

ML_API MLResult ML_CALL MLAudioGetStreamedFileOffset(MLHandle handle, uint32_t *out_offset_in_msec);

ML_API MLResult ML_CALL MLAudioGetOutputDevice(MLAudioOutputDevice *out_current_device);

ML_API MLResult ML_CALL MLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void *context);

ML_API MLResult ML_CALL MLAudioResetAcousticScene();

ML_API MLResult ML_CALL MLAudioBeginAcousticSceneUpdate();

ML_API MLResult ML_CALL MLAudioEndAcousticSceneUpdate();

ML_API MLResult ML_CALL MLAudioSetAcousticSceneMapEnable(bool is_enabled);

ML_API MLResult ML_CALL MLAudioGetAcousticSceneMapEnable(bool *out_is_enabled);

ML_API MLResult ML_CALL MLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel *transmission);

ML_API MLResult ML_CALL MLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel *out_transmission);

ML_API MLResult ML_CALL MLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties *properties);

ML_API MLResult ML_CALL MLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties *out_properties);

ML_API MLResult ML_CALL MLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties *properties);

ML_API MLResult ML_CALL MLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties *out_properties);

ML_API MLResult ML_CALL MLAudioGetChangedAcousticMap(uint32_t prev_map_tag, uint8_t **out_map_data, uint32_t *out_map_size_in_bytes, uint32_t *out_map_tag);


ML_API MLResult ML_CALL MLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundEnable(MLHandle handle, bool *out_is_enabled);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f *position);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f *out_position);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf *direction);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf *out_direction);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundBillboarding(MLHandle id, bool is_billboarding);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundBillboarding(MLHandle id, bool *out_is_billboarding);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundObstruction(MLHandle id, uint32_t channel, const MLAudioObstruction *left_ear, const MLAudioObstruction *right_ear);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundObstruction(MLHandle id, uint32_t channel, MLAudioObstruction *out_left_ear, MLAudioObstruction *out_right_ear);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundObstructionOverride(MLHandle id, const MLAudioMultibandLevel *override);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundObstructionOverride(MLHandle id, MLAudioMultibandLevel *out_override);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties *properties);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties *out_properties);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundRadiation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundRadiationProperties *properties);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundRadiation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundRadiationProperties *out_properties);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);

ML_API MLResult ML_CALL MLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative);

ML_API MLResult ML_CALL MLAudioGetSpatialSoundHeadRelative(MLHandle handle, bool *out_is_head_relative);

ML_API MLResult ML_CALL MLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest ** out_raycast_requests, uint32_t *out_request_count);

ML_API MLResult ML_CALL MLAudioSetSpatialRaycastResults(MLAudioRaycastResult * raycast_results, uint32_t result_count);

ML_API MLResult ML_CALL 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);

ML_API MLResult ML_CALL MLAudioGetBufferedOutputLatency(MLHandle handle, float *out_latency_in_msec);

ML_API MLResult ML_CALL MLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t *out_frames_played);

ML_API MLResult ML_CALL MLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer *out_buf);

ML_API MLResult ML_CALL MLAudioReleaseOutputBuffer(MLHandle handle);

ML_API MLResult ML_CALL MLAudioGetMasterVolume(float *out_volume);

ML_API MLResult ML_CALL MLAudioSetMasterVolumeCallback(MLAudioMasterVolumeChangedCallback callback, void *context);

ML_API MLResult ML_CALL MLAudioGetOutputMute(bool *out_is_muted);

ML_API MLResult ML_CALL MLAudioSetOutputMuteCallback(MLAudioOutputMuteChangedCallback callback, void *context);


ML_API MLResult ML_CALL MLAudioCreateInputFromMicCapture(MLAudioMicCaptureType mic_capture_type, const MLAudioBufferFormat *format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void *context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateInputFromVirtualCapture(const MLAudioBufferFormat *format, uint32_t buffer_size, MLAudioBufferCallback callback, void *callback_context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateInputFromMixedCapture(const MLAudioBufferFormat *format, uint32_t buffer_size, MLAudioBufferCallback callback, void *callback_context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioDestroyInput(MLHandle handle);

ML_API MLResult ML_CALL MLAudioStartInput(MLHandle handle);

ML_API MLResult ML_CALL MLAudioStopInput(MLHandle handle);

ML_API MLResult ML_CALL MLAudioGetInputState(MLHandle handle, MLAudioState *out_state);

ML_API MLResult ML_CALL MLAudioGetBufferedInputDefaults(uint32_t channel_count, uint32_t samples_per_second, MLAudioBufferFormat *out_format, uint32_t *out_recommended_size_in_bytes, uint32_t *out_min_size_in_bytes);

ML_API MLResult ML_CALL MLAudioGetBufferedInputLatency(MLHandle handle, float *out_latency_in_msec);

ML_API MLResult ML_CALL MLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer *out_buf);

ML_API MLResult ML_CALL MLAudioReleaseInputBuffer(MLHandle handle);

ML_API MLResult ML_CALL MLAudioSetMicMute(bool is_muted);

ML_API MLResult ML_CALL MLAudioGetMicMute(bool *out_is_muted);

ML_API MLResult ML_CALL MLAudioSetMicMuteCallback(MLAudioMicMuteCallback callback, void *context);

ML_API MLResult ML_CALL MLAudioBeginTraitAnalysisFromMicCapture(MLAudioTraitAnalysisTarget target, MLAudioTraitAnalysisCallback callback, void *callback_context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioGetTraitAnalysis(MLHandle handle, float *out_value);

ML_API MLResult ML_CALL MLAudioEndTraitAnalysis(MLHandle handle);

ML_API MLResult ML_CALL MLAudioBeginSpectralAnalysisFromMicCapture(MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysisCallback callback, void *callback_context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioGetSpectralAnalysis(MLHandle handle, MLAudioSpectralAnalysis *out_values);

ML_API MLResult ML_CALL MLAudioEndSpectralAnalysis(MLHandle handle);

ML_EXTERN_C_END