Skip to main content
Version: 21 Aug 2024

ml_audio.h

Classes

Name
structMLAudioMultibandLevel
Properties specifying a broadband level and three sub-band levels.
structMLAudioDispersionProperties
Properties specifying acoustic dispersion (clustered reflections).
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
Properties specifying acoustic dispersion (clustered reflections).
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 an audio resource's data is being discarded to make room for other resource data. Resource data that is not being referenced by a sound will be discarded before resource data that is being referenced by a sound. Resources that are being played by a sound will not have their data discarded.
typedef void()(float new_volume, void context)MLAudioMasterVolumeChangedCallback
Callback to notify when the master volume has been changed.
typedef void()(bool is_muted, void context)MLAudioOutputMuteChangedCallback
Callback to notify when the global output mute has been changed.
typedef void()(MLAudioOutputDevice current_device, void context)MLAudioOutputDeviceChangedCallback
Callback to notify when the active output device has changed.
typedef void()(bool is_muted, void context)MLAudioMicMuteCallback
Callback to notify when the 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 set 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 Loaded 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)
Queries whether a Loaded or Streamed Resource has been discarded due to system limits.
MLResultMLAudioGetResourceSize(MLHandle resource, uint32_t * out_size_in_bytes)
Queries the size of the memory footprint for a Loaded Resource.
MLResultMLAudioRefreshResource(MLHandle resource, int file)
Refreshes a resource whose data was discarded due to system limits.
MLResultMLAudioDestroyResource(MLHandle resource)
Destroys a previously created audio resource.
MLResultMLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle)
Creates a sound output referencing a Loaded Audio Resource.
MLResultMLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle)
Creates a sound output referencing a Streamed Audio Resource.
MLResultMLAudioCreateSoundWithLoadedFile(int file, bool auto_destroy, bool dynamic_decode, MLHandle * out_handle)
Creates a sound output that uses audio data loaded from a file descriptor into memory.
MLResultMLAudioCreateSoundWithStreamedFile(int file, bool auto_destroy, MLHandle * out_handle)
Creates a sound output that streams audio data from flash memory via a file descriptor.
MLResultMLAudioCreateSoundWithBufferedOutput(const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle)
Creates a sound output that plays a client-provided stream of buffered audio data.
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 currently playing sound output.
MLResultMLAudioResumeSound(MLHandle handle)
Resumes playback for a currently paused sound output.
MLResultMLAudioGetSoundState(MLHandle handle, MLAudioState * out_state)
Queries the playback state of a sound output.
MLResultMLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat * out_format)
Queries the audio format of a sound output.
MLResultMLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void * context)
Registers a callback for Sound Events relating to a sound output.
MLResultMLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void * context)
Registers a callback for media transport events.
MLResultMLAudioSetSoundVolumeLinear(MLHandle handle, float volume)
Sets the volume of a sound output using a linear scale.
MLResultMLAudioGetSoundVolumeLinear(MLHandle handle, float * out_volume)
Queries the volume of a sound output in 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)
Queries the volume of a sound output using a decibel scale.
MLResultMLAudioSetSoundPitch(MLHandle handle, float pitch)
Sets the pitch of a sound output by modifying its playback speed.
MLResultMLAudioGetSoundPitch(MLHandle handle, float * out_pitch)
Queries the pitch of a sound output which corresponds to its playback speed.
MLResultMLAudioSetSoundMute(MLHandle handle, bool is_muted)
Sets the mute state of a sound output.
MLResultMLAudioGetSoundMute(MLHandle handle, bool * out_is_muted)
Queries the mute state of a sound output.
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)
Queries whether a sound output is looping or not.
MLResultMLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec)
Sets the playback position of a sound output that's playing a Streamed File.
MLResultMLAudioGetStreamedFileOffset(MLHandle handle, uint32_t * out_offset_in_msec)
Queries the playback position of a sound output that's playing a Streamed File.
MLResultMLAudioGetOutputDevice(MLAudioOutputDevice * out_current_device)
Queries which type of sound output device is being used for sound output.
MLResultMLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void * context)
Registers a callback for when the active audio hardware output has changed.
MLResultMLAudioResetAcousticScene()
Resets the Acoustic Scene.
MLResultMLAudioBeginAcousticSceneUpdate()
Pauses the processing of changes to the Acoustic Scene.
MLResultMLAudioEndAcousticSceneUpdate()
Resumes the processing of changes to the Acoustic Scene.
MLResultMLAudioSetAcousticSceneMapEnable(bool is_enabled)
Sets whether spatial rendering emulates the acoustics of the user's environment.
MLResultMLAudioGetAcousticSceneMapEnable(bool * out_is_enabled)
Queries whether spatial rendering emulates the acoustics of the user's environment.
MLResultMLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel * transmission)
Sets the default attenuation applied to obstructed spatial sounds.
MLResultMLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel * out_transmission)
Queries the default attenuation applied to obstructed spatial sounds.
MLResultMLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties * properties)
Sets the default dispersion properties, which control the rendering of clustered reflections.
MLResultMLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties * out_properties)
Queries the default dispersion properties, which control the rendering of clustered reflections.
MLResultMLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties * properties)
Sets the default reverb properties, which control the rendering of late reverberation.
MLResultMLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties * out_properties)
Queries the default reverb properties, which control the rendering of late reverberation.
MLResultMLAudioGetChangedAcousticMap(uint32_t prev_map_tag, uint8_t * out_map_data, uint32_t out_map_size_in_bytes, uint32_t * out_map_tag)
INTERNAL USE ONLY: Retrieves the Acoustic Map if it has been updated since the previous call.
MLResultMLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled)
Sets whether a sound output is enabled as a spatial sound.
MLResultMLAudioGetSpatialSoundEnable(MLHandle handle, bool * out_is_enabled)
Queries whether a sound output is enabled as a spatial sound.
MLResultMLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f * position)
Sets the 3D position for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f * out_position)
Queries the 3D position of one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf * direction)
Sets the 3D direction for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf * out_direction)
Queries the 3D direction of one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundBillboarding(MLHandle handle, bool is_billboarding)
Enables or disables billboarding for all channels of a spatial sound.
MLResultMLAudioGetSpatialSoundBillboarding(MLHandle handle, bool * out_is_billboarding)
Queries whether billboarding is enabled for a spatial sound.
MLResultMLAudioSetSpatialSoundObstruction(MLHandle handle, uint32_t channel, const MLAudioObstruction left_ear, const MLAudioObstruction right_ear)
Sets the direct path obstruction status for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundObstruction(MLHandle handle, uint32_t channel, MLAudioObstruction out_left_ear, MLAudioObstruction out_right_ear)
Queries the direct path obstruction status for one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundObstructionOverride(MLHandle handle, const MLAudioMultibandLevel * override)
Sets the extent to which a spatial sound is exempt from obstruction effects.
MLResultMLAudioGetSpatialSoundObstructionOverride(MLHandle handle, MLAudioMultibandLevel * out_override)
Queries the extent to which a spatial sound is exempt from obstruction effects.
MLResultMLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties * properties)
Sets the behavior by which a spatial sound is attenuated due to distance.
MLResultMLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties * out_properties)
Queries the behavior by which a spatial sound is attenuated due to distance.
MLResultMLAudioSetSpatialSoundRadiation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundRadiationProperties * properties)
Sets a radiation pattern that describes the directionality for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundRadiation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundRadiationProperties * out_properties)
Queries the radiation pattern that describes the directionality for one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the gain and 3-band EQ on the Direct Path for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Queries the gain and 3-band EQ on the Direct Path for one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets a gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Queries the gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Queries the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level)
Sets the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound.
MLResultMLAudioGetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level)
Queries the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound.
MLResultMLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative)
Sets whether the position and direction for a spatial sound are interpreted in head-relative coordinates.
MLResultMLAudioGetSpatialSoundHeadRelative(MLHandle handle, bool * out_is_head_relative)
Queries whether the position and direction for a spatial sound are interpreted in head-relative coordinates.
MLResultMLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest * out_raycast_requests, uint32_t out_request_count)
Queries 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)
Queries the minimum and recommended settings for buffered sound outputs.
MLResultMLAudioGetBufferedOutputLatency(MLHandle handle, float * out_latency_in_msec)
Queries the latency for a buffered sound output.
MLResultMLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t * out_frames_played)
Queries the number of audio frames played by a buffered output.
MLResultMLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer * out_buf)
Retrieves an empty buffer for writing audio data for a buffered sound output.
MLResultMLAudioReleaseOutputBuffer(MLHandle handle)
Releases a filled audio output buffer for playback through a buffered sound output.
MLResultMLAudioGetMasterVolume(float * out_volume)
Queries the master volume.
MLResultMLAudioSetMasterVolumeCallback(MLAudioMasterVolumeChangedCallback callback, void * context)
Registers a callback for changes to the master volume.
MLResultMLAudioGetOutputMute(bool * out_is_muted)
Queries the state of the global output mute.
MLResultMLAudioSetOutputMuteCallback(MLAudioOutputMuteChangedCallback callback, void * context)
Registers a callback for changes to the global output mute.
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 wearable microphones.
MLResultMLAudioCreateInputFromVirtualCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void 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 context, MLHandle * out_handle)
Creates a new sound input that provides a mixed capture stream.
MLResultMLAudioDestroyInput(MLHandle handle)
Destroys a sound input.
MLResultMLAudioStartInput(MLHandle handle)
Starts a sound input.
MLResultMLAudioStopInput(MLHandle handle)
Stops a sound input.
MLResultMLAudioGetInputState(MLHandle handle, MLAudioState * out_state)
Queries the activity 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)
Queries the minimum and recommended settings for buffered sound inputs.
MLResultMLAudioGetBufferedInputLatency(MLHandle handle, float * out_latency_in_msec)
Queries the latency for a sound input.
MLResultMLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer * out_buf)
Retrieves a full buffer of audio data from a sound input.
MLResultMLAudioReleaseInputBuffer(MLHandle handle)
Releases an input buffer once it has been consumed.
MLResultMLAudioSetMicMute(bool is_muted)
Sets the global input mute state for all input streams.
MLResultMLAudioGetMicMute(bool * out_is_muted)
Queries the global input mute state for all input streams.
MLResultMLAudioSetMicMuteCallback(MLAudioMicMuteCallback callback, void * context)
Registers a callback for changes to the global input mute state.
MLResultMLAudioBeginTraitAnalysisFromMicCapture(MLAudioTraitAnalysisTarget target, MLAudioTraitAnalysisCallback callback, void context, MLHandle out_handle)
Starts a trait analysis of the energy contained in the mic signals.
MLResultMLAudioGetTraitAnalysis(MLHandle handle, float * out_value)
Queries the current value of the trait analysis.
MLResultMLAudioEndTraitAnalysis(MLHandle handle)
Stops a trait analysis.
MLResultMLAudioBeginSpectralAnalysisFromMicCapture(MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysisCallback callback, void context, MLHandle out_handle)
Starts a spectral analysis of the energy contained in the mic signals.
MLResultMLAudioGetSpectralAnalysis(MLHandle handle, MLAudioSpectralAnalysis * out_values)
Queries the current values of a spectral analysis.
MLResultMLAudioEndSpectralAnalysis(MLHandle handle)
Stops a 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 looping.
MLAudioSoundEvent_MutedBySystemA sound output has been muted due to system conditions.
MLAudioSoundEvent_UnmutedBySystemA previously muted sound output has been unmuted due to system conditions.
MLAudioSoundEvent_DuckedBySystemA sound output has been 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 for buffered I/O.
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.


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 (MFCC), 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 a 1/3 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;

Properties 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 describing the distance attenuation of a spatial sound using two distances, between which attention values are interpolated.

More Info


MLAudioSpatialSoundRadiationProperties

typedef struct MLAudioSpatialSoundRadiationProperties MLAudioSpatialSoundRadiationProperties;

Properties describing the directionality of a spatial sound using two cones, between which attention values are interpolated.

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 to/from buffered outputs and inputs.

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 which is non-blocking, except for calls to MLAudioDestroySound which will be blocked until the callback returns (unless the 'Destroy' call is called from the same thread as the callback, in which case it won't be blocked).


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 which is non-blocking.


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 which is non-blocking, except for calls to MLAudioDestroySound and MLAudioDestroyInput (for sounds and inputs respectively) which will be blocked until the callback returns (unless the 'Destroy' call is called from the same thread as the callback, in which case it won't be blocked).


MLAudioResourceDiscardedCallback

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

Callback to notify when an audio resource's data is being discarded to make room for other resource data. Resource data that is not being referenced by a sound will be discarded before resource data that is being referenced by a sound. Resources that are being played by a sound will not have their data discarded.

note

The callback will be called on a separate thread which is non-blocking.


MLAudioMasterVolumeChangedCallback

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

Callback to notify when the master volume has been changed.

note

The callback will be called on a separate thread which is non-blocking.


MLAudioOutputMuteChangedCallback

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

Callback to notify when the global output mute has been changed.

note

The callback will be called on a separate thread which is non-blocking.


MLAudioOutputDeviceChangedCallback

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

Callback to notify when the active output device has changed.

note

The callback will be called on a separate thread which is non-blocking.


MLAudioMicMuteCallback

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

Callback to notify when the global mic mute has been changed.

note

The callback will be called on a separate thread which is non-blocking.


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 which is non-blocking.


MLAudioSpectralAnalysisCallback

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

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

note

The callback will be called on a separate thread which is non-blocking.


Functions Documentation

MLAudioGetResultString

const char * MLAudioGetResultString(
MLResult result_code
)

Returns an ASCII string for each result code.

Parameters

MLResultresult_codeMLResult to be converted.

MLResult and MLAudioResult codes are converted to more detailed descriptions.

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 Loaded Resource that references a loaded audio file.

Parameters

intfileFile descriptor specifying the audio file.
booldynamic_decodeNot currently implemented.
MLAudioResourceDiscardedCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_resourceMLHandle to be used in subsequent calls.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotRecognizedFailed because file was not recognized.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration 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

Loaded Audio Resources provide the ability to preload audio files that stay in memory, so a single audio file can be played by multiple sound outputs. The resource can be used to create a sound output by passing the resource ID (MLHandle) provided by this function via out_resource to MLAudioCreateSoundWithLoadedResource. Files can be of type WAV, FLAC, MP3 and OGG, can be stereo or mono, can have 16kHz to 48kHz sample rate, and can be represented as 16-bit, 24-bit, and 32-bit integers or 32-bit floats.

The audio data for a Loaded Resource can be discarded by the system due to memory limits. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling MLAudioRefreshResource. MLAudioResourceDiscardedCallback is an optional argument to this function that will result in a callback to inform the client if the audio data for this Loaded Resource has been discarded due to system limits.


MLAudioCreateStreamedResource

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

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

Parameters

intfileFile descriptor specifying the audio file.
MLAudioResourceDiscardedCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_resourceMLHandle to be used in subsequent calls.

Returns

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

Required Permissions:

  • None

Streamed Audio Resources provide the ability to pre-establish a persistent reference to an audio file (in the form of a file descriptor), so a single audio file can be streamed by multiple sound outputs, with audio data streamed from flash memory into main memory in chunks during playback. The resource can be used to create a sound output by passing the resource ID (MLHandle) provided by this function via out_resource to MLAudioCreateSoundWithStreamedResource. Files can be of type WAV, FLAC, MP3 and OGG, can be stereo or mono, can have 16kHz to 48kHz sample rate, and can be represented as 16-bit, 24-bit, and 32-bit integers or 32-bit floats.

The File Descriptor for a Streamed Resource can be discarded by the system due to a limited number of available File Descriptors. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling MLAudioRefreshResource. MLAudioResourceDiscardedCallback is an optional argument to this function that will result in a callback to inform the client if the File Descriptor for this Streamed Resource has been discarded due to system limits.


MLAudioCheckResource

MLResult MLAudioCheckResource(
MLHandle resource,
bool * out_is_ready
)

Queries whether a Loaded or Streamed Resource has been discarded due to system limits.

Parameters

MLHandleresourceMLHandle of the resource.
bool *out_is_readyIf true, the resource is ready to use.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully reported the value.
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

The audio data for a Loaded Resource can be discarded by the system due to memory limits. The File Descriptor for a Streamed Resource can be discarded by the system due to a limited number of available File Descriptors. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling MLAudioRefreshResource.


MLAudioGetResourceSize

MLResult MLAudioGetResourceSize(
MLHandle resource,
uint32_t * out_size_in_bytes
)

Queries the size of the memory footprint for a Loaded Resource.

Parameters

MLHandleresourceMLHandle of the resource.
uint32_t *out_size_in_bytesThe retrieved size of the memory footprint.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_NotImplementedFailed because Streamed Resource was queried.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

For Loaded Resources using compressed file formats, the data is decompressed when loaded, and the size of the decompressed data is reported. For Streamed Resources, this call will fail with MLAudioResult_NotImplemented.

API Level:

  • 7

MLAudioRefreshResource

MLResult MLAudioRefreshResource(
MLHandle resource,
int file
)

Refreshes a resource whose data was discarded due to system limits.

Parameters

MLHandleresourceMLHandle of the resource.
intfileFile descriptor specifying the audio file.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully refreshed resource.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_FileNotRecognizedFailed because file was not recognized.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration 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

The audio data for a Loaded Resource can be discarded by the system due to memory limits. The File Descriptor for a Streamed Resource can be discarded by the system due to a limited number of available File Descriptors. Resources that are not being referenced by a sound output will be discarded prior to resources that are being referenced. Resources that are being played by a sound output will not be discarded. If a resource has been discarded, it must be refreshed prior to use by calling this function.


MLAudioDestroyResource

MLResult MLAudioDestroyResource(
MLHandle resource
)

Destroys a previously created audio resource.

Parameters

MLHandleresourceMLHandle of the resource.

Returns

MLResultMLResult_OkSuccessfully destroyed 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

Even if a resource is currently in use it will be destroyed immediately. If a sound output is playing the resource, the sound will be stopped and a corresponding Sound Event callback of type MLAudioSoundEvent_ResourceDestroyed will be issued.


MLAudioCreateSoundWithLoadedResource

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

Creates a sound output referencing a Loaded Audio Resource.

Parameters

MLHandleresourceMLHandle of the Loaded Resource.
boolauto_destroyIf true, the sound output is destroyed when playback reaches end of file.
MLHandle *out_handleMLHandle to be used in subsequent calls.

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 configuration 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

Once created, a sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound.


MLAudioCreateSoundWithStreamedResource

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

Creates a sound output referencing a Streamed Audio Resource.

Parameters

MLHandleresourceMLHandle of the streamed audio resource.
boolauto_destroyIf true, the sound output is destroyed when playback reaches end of file.
MLHandle *out_handleMLHandle to be used in subsequent calls.

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 configuration 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

Once created, a sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound.


MLAudioCreateSoundWithLoadedFile

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

Creates a sound output that uses audio data loaded from a file descriptor into memory.

Parameters

intfileFile descriptor specifying the audio file.
boolauto_destroyIf true, the sound output is destroyed when playback reaches end of file.
booldynamic_decodeNot currently implemented.
MLHandle *out_handleMLHandle to be used in subsequent calls.

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 configuration 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

Once created, the sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound. Files can be of type WAV, FLAC, MP3 and OGG, can be stereo or mono, can have 16kHz to 48kHz sample rate, and can be represented as 16-bit, 24-bit, and 32-bit integers or 32-bit floats.


MLAudioCreateSoundWithStreamedFile

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

Creates a sound output that streams audio data from flash memory via a file descriptor.

Parameters

intfileFile descriptor specifying the audio file.
boolauto_destroyIf true, the sound output is destroyed when playback reaches end of file.
MLHandle *out_handleMLHandle to be used in subsequent calls.

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 configuration error.
MLResultMLAudioResult_ResourceDiscardedFailed because file was closed.
MLResultMLAudioResult_ResourceNotFoundFailed because resource was not found.

Required Permissions:

  • None

Once created, the sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound. Files can be of type WAV, FLAC, MP3 and OGG, can be stereo or mono, can have 16kHz to 48kHz sample rate, and can be represented as 16-bit, 24-bit, and 32-bit integers or 32-bit floats.


MLAudioCreateSoundWithBufferedOutput

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

Creates a sound output that plays a client-provided stream of buffered audio data.

Parameters

const MLAudioBufferFormat *formatMLAudioBufferFormat struct specifying the format properties.
uint32_tbuffer_size_in_bytesRequested size in bytes for each of the output buffers.
MLAudioBufferCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_handleMLHandle to be used in subsequent calls.

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 configuration 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

The sound output allocates a double buffer that the caller is responsible for continuously filling with audio data. This can be done within a callback of type MLAudioBufferCallback that is set via the 'callback' argument or by polling MLAudioGetOutputBuffer if no callback is set. When polling, a return value of MLAudioResult_BufferNotReady indicates the sound output is not ready and the caller must wait. Setting the 'buffer_size_in_bytes' argument to 0 will utilize the system-preferred buffer size. Double-buffers can optionally be pre-filled prior to starting the sound. Once created, a sound output can be configured and controlled by calling other MLAudio API calls, passing the sound ID (MLHandle) provided by this function via out_handle. Playback can be started by calling MLAudioStartSound. Audio data can be mono, stereo, 4-channel (ambisonics), 6-channel (5.1), 8-channel (7.1), or 12-channel (7.1.4). It can have 16kHz to 48kHz sample rate, and must be 16-bit integer.

API Level:

  • 7

MLAudioDestroySound

MLResult MLAudioDestroySound(
MLHandle handle
)

Destroys a previously created sound output.

Parameters

MLHandlehandleMLHandle of 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 of the sound output.

Returns

MLResultMLResult_OkSound output is started, or continues if already playing.
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

Calling this function on a playing sound has no effect and returns success. Calling this function on a paused sound will start the sound output from the beginning. When starting playback for a buffered output stream, the "out_frames_played" counter retrieved by calling MLAudioGetBufferedOutputFramesPlayed is reset to 0.


MLAudioStopSound

MLResult MLAudioStopSound(
MLHandle handle
)

Stops playback for a sound output.

Parameters

MLHandlehandleMLHandle of the sound output.

Returns

MLResultMLResult_OkSound output is stopped, or remains stopped if already stopped.
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

Calling this function on a stopped sound has no effect and returns success.


MLAudioPauseSound

MLResult MLAudioPauseSound(
MLHandle handle
)

Pauses playback for a currently playing sound output.

Parameters

MLHandlehandleMLHandle of the sound output.

Returns

MLResultMLResult_OkSound output is paused, or remains paused if already paused.
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

If the sound output is not playing, the pause will fail with MLAudioResult_OperationUnavailable. Calling this function on a paused sound has no effect and returns success.


MLAudioResumeSound

MLResult MLAudioResumeSound(
MLHandle handle
)

Resumes playback for a currently paused sound output.

Parameters

MLHandlehandleMLHandle of the sound output.

Returns

MLResultMLResult_OkSound output resumes playing.
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

Calling this function on a paused sound will resume playback from the current position. Calling this function on a playing or stopped sound will fail with MLAudioResult_OperationUnavailable.


MLAudioGetSoundState

MLResult MLAudioGetSoundState(
MLHandle handle,
MLAudioState * out_state
)

Queries the playback state of a sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
MLAudioState *out_stateMLAudioState enum to be filled with the current playback state.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the properties.
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 enum defines the possible playback states which are Stopped, Playing and Paused.


MLAudioGetSoundFormat

MLResult MLAudioGetSoundFormat(
MLHandle handle,
MLAudioBufferFormat * out_format
)

Queries the audio format of a sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
MLAudioBufferFormat *out_formatMLAudioBufferFormat struct to be filled with the format properties.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the properties.
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

For sound outputs referencing streamed resources, the format is not available until ~100 milliseconds after playback has started.


MLAudioSetSoundEventCallback

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

Registers a callback for Sound Events relating to a sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
MLAudioSoundEventCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.

Returns

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

Required Permissions:

  • None

Sound outputs generate events as specified in the MLAudioSoundEvent enum, such as when a sound has looped, stopped, etc. Each of these events will trigger the MLAudioSoundEventCallback.

API Level:

  • 20

MLAudioSetMediaEventCallback

MLResult MLAudioSetMediaEventCallback(
MLAudioMediaEventCallback callback,
void * context
)

Registers a callback for media transport events.

Parameters

MLAudioMediaEventCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.

Returns

MLResultMLResult_AllocFailedIf memory allocation fails.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully registered the callback.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Media transport events can be triggered by devices such as bluetooth media controls. The possible events include Stop, Start, Pause, NextTrack and PrevTrack as specified in the MLAudioMediaEvent enum.

API Level:

  • 20

MLAudioSetSoundVolumeLinear

MLResult MLAudioSetSoundVolumeLinear(
MLHandle handle,
float volume
)

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

Parameters

MLHandlehandleMLHandle of the sound output.
floatvolumeThe linear volume that the sound output will be set to.

Returns

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

Required Permissions:

  • None

The range of valid values is from 0 to 8. A value of 0 indicates silence. A value of 1 indicates unity gain. A maximum value of 8 indicates 8x unity gain (+18 dB).


MLAudioGetSoundVolumeLinear

MLResult MLAudioGetSoundVolumeLinear(
MLHandle handle,
float * out_volume
)

Queries the volume of a sound output in a linear scale.

Parameters

MLHandlehandleMLHandle of the sound output.
float *out_volumeRetrieved linear volume of the sound output.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of valid values is from 0 to 8. A value of 0 indicates silence. A value of 1 indicates unity gain. A maximum value of 8 indicates 8x unity gain (+18 dB).


MLAudioSetSoundVolumeDb

MLResult MLAudioSetSoundVolumeDb(
MLHandle handle,
float volume
)

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

Parameters

MLHandlehandleMLHandle of the sound output.
floatvolumeThe dB volume that the sound output will be set to.

Returns

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

Required Permissions:

  • None

The range of valid values is from -100 dB to +18 dB. A value of -100 dB indicates silence. A value of 0 dB indicates unity gain. A maximum value of 18 dB indicates 8x unity gain.


MLAudioGetSoundVolumeDb

MLResult MLAudioGetSoundVolumeDb(
MLHandle handle,
float * out_volume
)

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

Parameters

MLHandlehandleMLHandle of the sound output.
float *out_volumeRetrieved dB volume of the sound output.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of valid values is from -100 dB to +18 dB. A value of -100 dB indicates silence. A value of 0 dB indicates unity gain. A maximum value of 18 dB indicates 8x unity gain.


MLAudioSetSoundPitch

MLResult MLAudioSetSoundPitch(
MLHandle handle,
float pitch
)

Sets the pitch of a sound output by modifying its playback speed.

Parameters

MLHandlehandleMLHandle of the sound output.
floatpitchThe pitch of the sound output to be set.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_InvalidBufferSizeFailed due to an invalid buffer size.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of valid values is from 0.5 which plays at half speed and produces an octave shift down, to 2.0 which plays at double speed and produces an octave shift up. The default value of 1.0 plays the sound at its original speed and pitch.


MLAudioGetSoundPitch

MLResult MLAudioGetSoundPitch(
MLHandle handle,
float * out_pitch
)

Queries the pitch of a sound output which corresponds to its playback speed.

Parameters

MLHandlehandleMLHandle of the sound output.
float *out_pitchRetrieved pitch of the sound output.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The range of valid values is from 0.5 which plays at half speed and produces an octave shift down, to 2.0 which plays at double speed and produces an octave shift up. At the default value of 1.0 the sound plays at its original speed and pitch.


MLAudioSetSoundMute

MLResult MLAudioSetSoundMute(
MLHandle handle,
bool is_muted
)

Sets the mute state of a sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
boolis_mutedIf true, the sound output will be muted.

Returns

MLResultMLResult_OkSuccessfully set the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The 'sound mute' of a sound output only affects that one sound output.


MLAudioGetSoundMute

MLResult MLAudioGetSoundMute(
MLHandle handle,
bool * out_is_muted
)

Queries the mute state of a sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
bool *out_is_mutedIf true, the sound output is muted.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

The 'sound mute' of a sound output only affects that one sound output.

API Level:

  • 20

MLAudioSetSoundBypassesMasterVolume

MLResult MLAudioSetSoundBypassesMasterVolume(
MLHandle handle,
bool is_bypassing
)

Sets whether a sound output is exempt from attenuation due to master volume.

Parameters

MLHandlehandleMLHandle of the sound output.
boolis_bypassingIndicates whether the sound output should bypass master volume or not.

Returns

MLResultMLResult_OkSuccessfully set the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLResult_IncompatibleSKUFailed due to feature not being supported on current device version.

Required Permissions:

  • None

This call sets whether a sound output is bypassing master volume, making it effectively "always audible" (assuming it is neither muted nor set to zero volume on a per-sound basis). This option is available only on certain SKUs; trying to set it when the device is not compatible will produce an error as listed below. In addition, this option only works when a sound is non-spatial; the non-spatial sound parameters volume, pitch, etc remain active for sounds that are bypassing master volume.

API Level:

  • 20

MLAudioGetSoundBypassesMasterVolume

MLResult MLAudioGetSoundBypassesMasterVolume(
MLHandle handle,
bool * out_is_bypassing
)

Queries whether a sound output is exempt from attenuation due to master volume.

Parameters

MLHandlehandleMLHandle of 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 being 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 queries whether a sound output is bypassing master volume, making it effectively "always audible" (assuming it is neither muted nor set to zero volume on a per-sound basis). This option is available only on certain SKUs; trying to query it when the device is not compatible will produce an error as listed below. In addition, this option only works when a sound is non-spatial; the non-spatial sound parameters volume, pitch, etc remain active for sounds that are bypassing master volume.

API Level:

  • 20

MLAudioSetSoundLooping

MLResult MLAudioSetSoundLooping(
MLHandle handle,
bool is_looping
)

Sets whether a sound output is looping or not.

Parameters

MLHandlehandleMLHandle of 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 use Loaded Files and Streamed Files (and their audio resource equivalents). If a sound output is set to looping, then when it reaches the end of the file, it continues playing from the beginning of the file. Looping is not available for sound outputs that use Buffered Outputs.


MLAudioGetSoundLooping

MLResult MLAudioGetSoundLooping(
MLHandle handle,
bool * out_is_looping
)

Queries whether a sound output is looping or not.

Parameters

MLHandlehandleMLHandle of the sound output.
bool *out_is_loopingIf true, the sound output state is looping.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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 use Loaded Files and Streamed Files (and their audio resource equivalents). If a sound output is set to looping, then when it reaches the end of the file, it continues playing from the beginning of the file. Looping is not available for sound outputs that use Buffered Outputs.


MLAudioSetStreamedFileOffset

MLResult MLAudioSetStreamedFileOffset(
MLHandle handle,
uint32_t offset_in_msec
)

Sets the playback position of a sound output that's playing a Streamed File.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_toffset_in_msecThe playback position in milliseconds the sound output will be set to.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully set the value.
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 playback position is in milliseconds and can be set regardless of the playback state.


MLAudioGetStreamedFileOffset

MLResult MLAudioGetStreamedFileOffset(
MLHandle handle,
uint32_t * out_offset_in_msec
)

Queries the playback position of a sound output that's playing a Streamed File.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_t *out_offset_in_msecRetrieved playback position.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

The playback position is in milliseconds.


MLAudioGetOutputDevice

MLResult MLAudioGetOutputDevice(
MLAudioOutputDevice * out_current_device
)

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

Parameters

MLAudioOutputDevice *out_current_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 when the active audio hardware output has changed.

Parameters

MLAudioOutputDeviceChangedCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.

Returns

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

Required Permissions:

  • None

API Level:

  • 8

MLAudioResetAcousticScene

MLResult MLAudioResetAcousticScene()

Resets the Acoustic Scene.

Returns

MLResultMLResult_OkSuccessfully reset the Acoustic Scene.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundNo custom scene exists for client.

Required Permissions:

  • None

Each client of this audio API is automatically assigned an Acoustic Scene that specifies the acoustic behaviors of that client's spatial audio content. An Acoustic Scene can be modified and customized by calling functions in the ACOUSTICS section of this audio API. This function resets the caller's Acoustic Scene to its initial default state.

API Level:

  • 20

MLAudioBeginAcousticSceneUpdate

MLResult MLAudioBeginAcousticSceneUpdate()

Pauses the processing of changes to the Acoustic Scene.

Returns

MLResultMLResult_OkSuccessfully began the Acoustic Scene update.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

This function signals the beginning of a collection of changes to the Acoustic Scene, intended to be heard at the same time. After calling MLAudioBeginAcousticSceneUpdate, any subsequent calls to functions in the ACOUSTICS section of this audio API will be deferred, and will be applied simultaneously when MLAudioEndAcousticSceneUpdate is called.

API Level:

  • 20

MLAudioEndAcousticSceneUpdate

MLResult MLAudioEndAcousticSceneUpdate()

Resumes the processing of changes to the Acoustic Scene.

Returns

MLResultMLResult_OkSuccessfully ended the Acoustic Scene update.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundNo custom scene exists for client.

Required Permissions:

  • None

This function signals the ending of a collection of changes to the Acoustic Scene, causing them to be heard at the same time. After calling MLAudioBeginAcousticSceneUpdate, any subsequent calls to functions in the ACOUSTICS section of this audio API will be deferred, and will be applied simultaneously when MLAudioEndAcousticSceneUpdate is called.

API Level:

  • 20

MLAudioSetAcousticSceneMapEnable

MLResult MLAudioSetAcousticSceneMapEnable(
bool is_enabled
)

Sets whether spatial rendering emulates the acoustics of the user's environment.

Parameters

boolis_enabledIf true, the Acoustic Map will be enabled.

Returns

MLResultMLResult_OkSuccessfully set the value.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The Acoustic Map 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 physical environment.

API Level:

  • 20

MLAudioGetAcousticSceneMapEnable

MLResult MLAudioGetAcousticSceneMapEnable(
bool * out_is_enabled
)

Queries whether spatial rendering emulates the acoustics of the user's environment.

Parameters

bool *out_is_enabledIf true, the Acoustic Map is enabled.

Returns

MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The Acoustic Map is a device-curated representation of the acoustics of the local physical environment. When the Acoustic Map is enabled, virtual objects sound as though they exist in the local physical environment.

API Level:

  • 20

MLAudioSetAcousticSceneTransmissionDefault

MLResult MLAudioSetAcousticSceneTransmissionDefault(
const MLAudioMultibandLevel * transmission
)

Sets the default attenuation applied to obstructed spatial sounds.

Parameters

const MLAudioMultibandLevel *transmissionMLAudioMultibandLevel struct to set the default properties.

Returns

MLResultMLResult_OkSuccessfully set the default properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The propagation of virtual sound in space can be obstructed by virtual objects created by the client, or by the virtual representation of the local physical environment. In cases where these obstructions have no transmission properties defined, the Acoustic Scene default transmission properties set by this function are used. Transmission properties are specified by an MLAudioMultibandLevel struct in which values of [1, (1, 1, 1)] represent fully unobstructed, while [0, (1, 1, 1)] or [1, (0, 0, 0)] both represent fully obstructed.

API Level:

  • 20

MLAudioGetAcousticSceneTransmissionDefault

MLResult MLAudioGetAcousticSceneTransmissionDefault(
MLAudioMultibandLevel * out_transmission
)

Queries the default attenuation applied to obstructed spatial sounds.

Parameters

MLAudioMultibandLevel *out_transmissionMLAudioMultibandLevel struct to be filled with the default properties.

Returns

MLResultMLResult_OkSuccessfully retrieved the default properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The propagation of virtual sound in space can be obstructed by virtual objects created by the client, or by the virtual representation of the local physical environment. In cases where these obstructions have no transmission properties defined, the Acoustic Scene default transmission properties queried by this function are used. Transmission properties are specified by an MLAudioMultibandLevel struct in which values of [1, (1, 1, 1)] represent fully unobstructed, while [0, (1, 1, 1)] or [1, (0, 0, 0)] both represent fully obstructed.

API Level:

  • 20

MLAudioSetAcousticSceneDispersionDefault

MLResult MLAudioSetAcousticSceneDispersionDefault(
const MLAudioDispersionProperties * properties
)

Sets the default dispersion properties, which control the rendering of clustered reflections.

Parameters

const MLAudioDispersionProperties *propertiesMLAudioDispersionProperties struct to set the default properties.

Returns

MLResultMLResult_OkSuccessfully set the default properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. Dispersion comprises the clustered non-discrete reflections that precede the reverb. In areas where no dispersion properties are explicitly defined, the Acoustic Scene default dispersion properties set by this function are used. Dispersion properties are specified by an MLAudioDispersionProperties struct which specifies a gain using an MLAudioMultibandLevel, and a pre-delay. If the pre-delay setting is greater than the pre-delay of the default reverb properties, it will be clamped to an equal value.

This 'AcousticScene' API sets a shared acoustic processing effect that is applied to multiple spatial sounds. To set the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioSetSpatialSoundDispersionSendLevel.

API Level:

  • 20

MLAudioGetAcousticSceneDispersionDefault

MLResult MLAudioGetAcousticSceneDispersionDefault(
MLAudioDispersionProperties * out_properties
)

Queries the default dispersion properties, which control the rendering of clustered reflections.

Parameters

MLAudioDispersionProperties *out_propertiesMLAudioDispersionProperties struct to be filled with the default properties.

Returns

MLResultMLResult_OkSuccessfully retrieved the default properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. Dispersion comprises the clustered non-discrete reflections that precede the reverb. In areas where no dispersion properties are explicitly defined, the Acoustic Scene default dispersion properties queried by this function are used. Dispersion properties are specified by an MLAudioDispersionProperties struct which specifies a gain using an MLAudioMultibandLevel, and a pre-delay.

This 'AcousticScene' API queries a shared acoustic processing effect that is applied to multiple spatial sounds. To query the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioGetSpatialSoundDispersionSendLevel.

API Level:

  • 20

MLAudioSetAcousticSceneReverbDefault

MLResult MLAudioSetAcousticSceneReverbDefault(
const MLAudioReverbProperties * properties
)

Sets the default reverb properties, which control the rendering of late reverberation.

Parameters

const MLAudioReverbProperties *propertiesMLAudioReverbProperties struct to set the properties.

Returns

MLResultMLResult_OkSuccessfully set the default properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. The reverb comprises late stage sound decay caused by the acoustic space. In areas where no reverb properties are explicitly defined, the Acoustic Scene default reverb properties set by this function are used. Reverb properties are specified by an MLAudioReverbProperties struct which specifies a gain using an MLAudioMultibandLevel, a pre-delay, and the time and frequency contour of the reverb envelope. If the pre-delay setting is less than the pre-delay of the default dispersion properties, it will be clamped to an equal value.

This 'AcousticScene' API sets a shared acoustic processing effect that is applied to multiple spatial sounds. To set the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioSetSpatialSoundReverbSendLevel.

API Level:

  • 20

MLAudioGetAcousticSceneReverbDefault

MLResult MLAudioGetAcousticSceneReverbDefault(
MLAudioReverbProperties * out_properties
)

Queries the default reverb properties, which control the rendering of late reverberation.

Parameters

MLAudioReverbProperties *out_propertiesMLAudioReverbProperties struct to be filled with the default properties.

Returns

MLResultMLResult_OkSuccessfully retrieved the default properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

The propagation model for a spatial sound has 4 parts: direct path, reflections, dispersion, and reverb. The reverb comprises late stage sound decay caused by the acoustic space. In areas where no reverb properties are explicitly defined, the Acoustic Scene default reverb properties queried by this function are used. Reverb properties are specified by an MLAudioReverbProperties struct which specifies a gain using an MLAudioMultibandLevel, a pre-delay, and the time and frequency contour of the reverb envelope.

This 'AcousticScene' API queries a shared acoustic processing effect that is applied to multiple spatial sounds. To query the per-sound mix levels for this effect, see the corresponding 'SpatialSoundSendLevel' API which is MLAudioGetSpatialSoundReverbSendLevel.

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
)

INTERNAL USE ONLY: Retrieves the Acoustic Map if it has been updated since the previous call.

Parameters

uint32_tprev_map_tagThe map tag received in previous call.
uint8_t **out_map_dataRetrieved pointer to serialized copy of Acoustic Map data if prev_map_tag != out_map_tag.
uint32_t *out_map_size_in_bytesRetrieved length of serialized Acoustic Map data in bytes.
uint32_t *out_map_tagRetrieved current map tag to be passed in subsequent call.

Returns

MLResultMLResult_OkSuccessfully retrieved properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.

Required Permissions:

  • None

Acoustic Map data is a device-curated representation of the acoustics of the local physical environment. The out_map_data argument will point to a serialized copy of the map and must deleted after use. This function is intended for internal use and should not be called by clients of the MLAudio API.

API Level:

  • 20

MLAudioSetSpatialSoundEnable

MLResult MLAudioSetSpatialSoundEnable(
MLHandle handle,
bool is_enabled
)

Sets whether a sound output is enabled as a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
boolis_enabledIf true, spatial audio will be enabled for a sound output.

Returns

MLResultMLResult_OkSuccessfully set the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

Enabling a sound output as a spatial sound will cause each of its channels to be rendered at a per-channel-specified position in 3D space. Spatial sounds also have other customizable per-channel properties such as direction, radiation, distance attenuation, etc. All these properties can be set whether or not a sound output is currently enabled as a spatial sound. Simulated acoustics for spatial sounds are defined by the client's Acoustic Scene. By default, sound outputs are not enabled as spatial sounds.


MLAudioGetSpatialSoundEnable

MLResult MLAudioGetSpatialSoundEnable(
MLHandle handle,
bool * out_is_enabled
)

Queries whether a sound output is enabled as a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
bool *out_is_enabledIf true, spatial audio is be enabled for a sound output.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

For a sound output enabled as a spatial sound, each of its channels will be rendered at a per-channel-specified position in 3D space. Spatial sounds also have other customizable per-channel properties such as direction, radiation, distance attenuation, etc. All these properties can be queried whether or not a sound output is currently enabled as a spatial sound. Simulated acoustics for spatial sounds are defined by the client's Acoustic Scene. By default, sound outputs are not enabled as spatial sounds.


MLAudioSetSpatialSoundPosition

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

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

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLVec3f *positionStruct to set the position.

Returns

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

Required Permissions:

  • None

Each channel of a spatial sound is rendered at a position specified by an x,y,z point in cartesian coordinates. Positive x is to the right, positive y is up, and positive z is to the rear.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.


MLAudioGetSpatialSoundPosition

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

Queries the 3D position of one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLVec3f *out_positionStruct to be filled with the position.

Returns

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

Required Permissions:

  • None

Each channel of a spatial sound is rendered at a position specified by an x,y,z point in cartesian coordinates. Positive x is to the right, positive y is up, and positive z is to the rear.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.


MLAudioSetSpatialSoundDirection

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

Sets the 3D direction for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLQuaternionf *directionStruct to set the radiation direction.

Returns

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

Required Permissions:

  • None

Each channel of a spatial sound radiates into 3D space with a pattern whose center is specified by the sound channel's direction. The radiation pattern can be set by calling MLAudioSetSpatialSoundRadiation. By default, sounds have billboarding enabled, which overrides the direction for every channel such that they always face the listener. Billboarding can be disabled by calling MLAudioSetSpatialSoundBillboarding.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.


MLAudioGetSpatialSoundDirection

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

Queries the 3D direction of one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLQuaternionf *out_directionStruct to be filled with the radiation direction.

Returns

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

Required Permissions:

  • None

Each channel of a spatial sound radiates into 3D space with a pattern whose center is specified by the sound channel's direction. The radiation pattern can be set by calling MLAudioSetSpatialSoundRadiation. By default, sounds have billboarding enabled, which overrides the direction for every channel such that they always face the listener. Billboarding can be disabled by calling MLAudioSetSpatialSoundBillboarding.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.


MLAudioSetSpatialSoundBillboarding

MLResult MLAudioSetSpatialSoundBillboarding(
MLHandle handle,
bool is_billboarding
)

Enables or disables billboarding for all channels of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
boolis_billboardingIf true, billboarding will be enabled.

Returns

MLResultMLResult_OKSuccessfully set the value.
MLResultMLAudioResult_HandleNotFoundUnable to find resource handle.
MLResultMLAudioResult_OperationUnavailableOperation is unavailable for this sound output.

Required Permissions:

  • None

Billboarding causes each channel of a spatial sound to always face the listener. When billboarding is enabled, channel directions set using MLAudioSetSpatialSoundDirection are ignored. Billboarding gives the impression of an omnidirectional sound, while allowing radiation properties set using MLAudioSetSpatialSoundRadiation to affect this sound's contribution to dispersion and reverb. By default, billboarding is enabled on newly created sound outputs.

API Level:

  • 20

MLAudioGetSpatialSoundBillboarding

MLResult MLAudioGetSpatialSoundBillboarding(
MLHandle handle,
bool * out_is_billboarding
)

Queries whether billboarding is enabled for a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
bool *out_is_billboardingIf true, billboarding is enabled.

Returns

MLResultMLResult_OKSuccessfully retrieved the value.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_OperationUnavailableOperation is unavailable for this sound output.

Required Permissions:

  • None

Billboarding causes each channel of a spatial sound to always face the listener. When billboarding is enabled, channel directions set using MLAudioSetSpatialSoundDirection are ignored. Billboarding gives the impression of an omnidirectional sound, while allowing radiation properties set using MLAudioSetSpatialSoundRadiation to affect this sound's contribution to dispersion and reverb. By default, billboarding is enabled on newly created sound outputs.

API Level:

  • 20

MLAudioSetSpatialSoundObstruction

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

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

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioObstruction *left_earMLAudioObstruction struct to set the direct path obstruction properties for the left ear.
const MLAudioObstruction *right_earMLAudioObstruction struct to set the direct path obstruction properties for the right ear.

Returns

MLResultMLResult_OkSuccessfully set the properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_OperationUnavailableOperation is unavailable for this sound output.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal configuration error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

THIS IS AN INTERNAL FUNCTION INTENDED FOR ENGINE DEVELOPMENT ONLY.

Spatial sounds are subject to obstruction effects by real and virtual objects. Each channel of the spatial sound output contains a left and right ear MLAudioObstruction for the direct path, which can be set by repeated calls to this function. The obstruction effect for each channel of a spatial sound is determined by this set of MLAudioObstruction structs and a set of transmission properties. The MLAudioObstruction hit_point determines which transmission properties to apply and the MLAudioObstruction factor determines the extent to which these properties are applied. Transmission properties can be set globally for the scene using MLAudioSetAcousticSceneTransmissionDefault.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundObstruction

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

Queries the direct path obstruction status for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioObstruction *out_left_earMLAudioObstruction struct to be filled with the obstruction properties for the left ear.
MLAudioObstruction *out_right_earMLAudioObstruction struct to be filled with the obstruction properties for the right ear.

Returns

MLResultMLResult_OkSuccessfully retrieved the properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_OperationUnavailableOperation is unavailable for this sound output.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

THIS IS AN INTERNAL FUNCTION INTENDED FOR ENGINE DEVELOPMENT ONLY.

Spatial sounds are subject to obstruction effects by real and virtual objects. Each channel of the spatial sound output contains a left and right ear MLAudioObstruction for the direct path, which can be queried by this function. The obstruction effect for each channel of a spatial sound is determined by this set of MLAudioObstruction structs and a set of transmission properties. The MLAudioObstruction hit_point determines which transmission properties to apply and the MLAudioObstruction factor determines the extent to which these properties are applied. Transmission properties can be set globally for the scene using MLAudioSetAcousticSceneTransmissionDefault.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundObstructionOverride

MLResult MLAudioSetSpatialSoundObstructionOverride(
MLHandle handle,
const MLAudioMultibandLevel * override
)

Sets the extent to which a spatial sound is exempt from obstruction effects.

Parameters

MLHandlehandleMLHandle of the sound output.
const MLAudioMultibandLevel *overrideMLAudioMultibandLevel struct to set the override properties.

Returns

MLResultMLResult_OKSuccessfully set the properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundUnable to find resource handle.
MLResultMLAudioResult_OperationUnavailableOperation is unavailable for this sound output.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

This function provides a way to prevent obstruction effects on specified spatial sounds. The extent to which a spatial sound is exempt from obstruction effects is specified per band using an MLAudioMultibandLevel struct. The value for each band determines that band's interpolation between its computed obstruction effect, represented by 0, and no obstruction effect, represented by 1. For example, to completely exempt a spatial sound from obstruction effects, set the override argument to [1,1,1,1], and to fully allow obstruction effects set to [0,0,0,0]. On newly created spatial sounds, obstruction override defaults to [0,0,0,0]. For multi-channel spatial sounds, all channels are affected equally by this function.

API Level:

  • 20

MLAudioGetSpatialSoundObstructionOverride

MLResult MLAudioGetSpatialSoundObstructionOverride(
MLHandle handle,
MLAudioMultibandLevel * out_override
)

Queries the extent to which a spatial sound is exempt from obstruction effects.

Parameters

MLHandlehandleMLHandle of the sound output.
MLAudioMultibandLevel *out_overrideMLAudioMultibandLevel struct to be filled with the override properties.

Returns

MLResultMLResult_OKSuccessfully retrieved the properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLAudioResult_HandleNotFoundUnable to find resource handle.
MLResultMLAudioResult_OperationUnavailableOperation is unavailable for this sound output.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Obstruction override provides a way to prevent obstruction effects on specified spatial sounds. The extent to which a spatial sound is exempt from obstruction effects is specified per band using an MLAudioMultibandLevel struct. The value for each band determines that band's interpolation between its computed obstruction effect, represented by 0, and no obstruction effect, represented by 1. For example, a spatial sound completely exempt from obstruction effects has an override value of [1,1,1,1], and a spatial sound fully subject to obstruction effects has an override value of [0,0,0,0]. For multi-channel spatial sounds, all channels are affected equally by the override value.

API Level:

  • 20

MLAudioSetSpatialSoundDistanceAttenuation

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

Sets the behavior by which a spatial sound is attenuated due to distance.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioSpatialSoundDistanceProperties *propertiesMLAudioSpatialSoundDistanceProperties struct to set the properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully set the properties.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

The behavior for distance attenuation is specified by an MLAudioSpatialSoundDistanceProperties struct provided as the properties argument of this function. Within this struct the min_distance specifies the distance from the listener beyond which a spatial sound starts attenuating with distance. The max_distance specifies the distance from the listener beyond which no further attenuation occurs. Between min_distance and max_distance a spatial sound will be attenuated with distance according to the rolloff_factor. A rolloff_factor of 1 will produce distance attenuation that approximates real world distance attenuation. A rolloff_factor greater than 1 will produce distance attenuation that rolls off faster as distance increases, while less than 1 will produce distance attenuation that rolls off more gradually. If rolloff_factor is 0, no distance attenuation will be applied.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundDistanceAttenuation

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

Queries the behavior by which a spatial sound is attenuated due to distance.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioSpatialSoundDistanceProperties *out_propertiesMLAudioSpatialSoundDistanceProperties struct to be filled with the properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully retrieved the properties.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

The behavior for distance attenuation is specified by an MLAudioSpatialSoundDistanceProperties struct reported by the out_properties argument of this function. Within this struct the min_distance specifies the distance from the listener beyond which a spatial sound starts attenuating with distance. The max_distance specifies the distance from the listener beyond which no further attenuation occurs. Between min_distance and max_distance a spatial sound will be attenuated with distance according to the rolloff_factor. A rolloff_factor of 1 will produce distance attenuation that approximates real world distance attenuation. A rolloff_factor greater than 1 will produce distance attenuation that rolls off faster as distance increases, while less than 1 will produce distance attenuation that rolls off more gradually. If rolloff_factor is 0, no distance attenuation will be applied.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundRadiation

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

Sets a radiation pattern that describes the directionality for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioSpatialSoundRadiationProperties *propertiesMLAudioSpatialSoundRadiationProperties struct to set the properties.

Returns

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

Required Permissions:

  • None

Each channel of a spatial sound has a dual cone radiation pattern specified by an MLAudioSpatialSoundRadiationProperties struct. The radiation pattern is oriented toward the listener for all channels if billboarding is enabled, or in the direction set by MLAudioSetSpatialSoundDirection for each channel if billboarding is disabled. The default values for the MLAudioSpatialSoundRadiationProperties struct were chosen to model a human speaking.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundRadiation

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

Queries the radiation pattern that describes the directionality for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioSpatialSoundRadiationProperties *out_propertiesMLAudioSpatialSoundRadiationProperties struct to be filled with the properties.

Returns

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

Required Permissions:

  • None

Each channel of a spatial sound has a dual cone radiation pattern specified by an MLAudioSpatialSoundRadiationProperties struct. The radiation pattern is oriented toward the listener for all channels if billboarding is enabled, or in the direction set by MLAudioSetSpatialSoundDirection for each channel if billboarding is disabled.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundDirectLevel

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

Sets the gain and 3-band EQ on the Direct Path for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq properties.

Returns

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

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Direct Level is applied to the sound traveling directly from the source to the listener. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundDirectLevel

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

Queries the gain and 3-band EQ on the Direct Path for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns

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

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Direct Level is applied to the sound traveling directly from the source to the listener. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundIndirectLevel

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

Sets a gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully set the properties.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Indirect Level is applied to the Reflections, Dispersion, and Reverb stages as a group, combining with the level specified for each individual stage. The Reflections stage consists of discrete reflections off of distinct surfaces. The Dispersion stage consists of clustered groups of late reflections smeared in time. The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ applied to these stages as a group is specified by an MLAudioMultibandLevel struct.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundIndirectLevel

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

Queries the gain and 3-band EQ applied to all indirect paths for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully retrieved the properties.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Indirect Level is applied to the Reflections, Dispersion, and Reverb stages as a group, combining with the level specified for each individual stage. The Reflections stage consists of discrete reflections off of distinct surfaces. The Dispersion stage consists of clustered groups of late reflections smeared in time. The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ applied to these stages as a group is specified by an MLAudioMultibandLevel struct.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundDispersionSendLevel

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

Sets the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq properties.

Returns

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

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Dispersion stage consists of clustered groups of late reflections smeared in time. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.

This 'SpatialSoundSendLevel' API sets the amount of signal that a particular sound feeds into a shared acoustic processing effect. To set the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioSetAcousticSceneDispersionDefault.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundDispersionSendLevel

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

Queries the gain and 3-band EQ on the Dispersion stage for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns

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

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Dispersion stage consists of clustered groups of late reflections smeared in time. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.

This 'SpatialSoundSendLevel' API queries the amount of signal that a particular sound feeds into a shared acoustic processing effect. To query the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioGetAcousticSceneDispersionDefault.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundReverbSendLevel

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

Sets the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
const MLAudioMultibandLevel *levelMLAudioMultibandLevel struct to set the gain and eq properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully set the properties.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.

This 'SpatialSoundSendLevel' API sets the amount of signal that a particular sound feeds into a shared acoustic processing effect. To set the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioSetAcousticSceneReverbDefault.

Spatial sounds require each channel's parameters to be set individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioGetSpatialSoundReverbSendLevel

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

Queries the gain and 3-band EQ on the Reverb stage for one channel of a spatial sound.

Parameters

MLHandlehandleMLHandle of the sound output.
uint32_tchannelChannel of the sound output.
MLAudioMultibandLevel *out_levelMLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns

MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_OkSuccessfully retrieved the properties.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_HandleNotFoundHandle not found.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

Naturally occurring sounds in a physical space are experienced as an initial arrival followed by an increasing number of reflections that tend toward a well-mixed reverberation over time. These reflections provide spatial cues that inform the listener as to the position of the sound and the characteristics of the environment in which it occurs. For spatial sounds, this progression is modeled across four stages: Direct Path, Reflections, Dispersion, and Reverb. The level of each of these stages can be manipulated to achieve the desired perceptual balance between them.

The Reverb stage consists of the well-mixed reverberation tail of the sound. The gain and 3-band EQ for this stage is specified by an MLAudioMultibandLevel struct.

This 'SpatialSoundSendLevel' API queries the amount of signal that a particular sound feeds into a shared acoustic processing effect. To query the properties of the processing effect itself, see the corresponding 'AcousticScene' API which is MLAudioGetAcousticSceneReverbDefault.

Spatial sounds require each channel's parameters to be queried individually. Channels are indexed starting at 0 and follow the track order defined by the audio content. For example, for a spatial sound with stereo content this function should be called twice, passing channel = 0 for left and channel = 1 for right. A sound output must be enabled as a spatial sound using MLAudioSetSpatialSoundEnable for this property to take effect.

API Level:

  • 20

MLAudioSetSpatialSoundHeadRelative

MLResult MLAudioSetSpatialSoundHeadRelative(
MLHandle handle,
bool is_head_relative
)

Sets whether the position and direction for a spatial sound are interpreted in head-relative coordinates.

Parameters

MLHandlehandleMLHandle of the sound output.
boolis_head_relativeIf true, coordinates will be head-relative.

Returns

MLResultMLResult_OkSuccessfully set the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown failure.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

A head-relative coordinate system has an origin and orientation locked to the user's head center and forward direction. For spatial sounds with head-relative enabled, the position and direction as specified by MLAudioSetSpatialSoundPosition and MLAudioSetSpatialSoundDirection (and reported by MLAudioGetSpatialSoundPosition and MLAudioGetSpatialSoundDirection) are interpreted within such a coordinate system. For spatial sounds with head-relative disabled, the position and direction are interpreted within the world coordinate system defined by the platform. By default, head-relative is disabled for spatial sounds.

API Level:

  • 7

MLAudioGetSpatialSoundHeadRelative

MLResult MLAudioGetSpatialSoundHeadRelative(
MLHandle handle,
bool * out_is_head_relative
)

Queries whether the position and direction for a spatial sound are interpreted in head-relative coordinates.

Parameters

MLHandlehandleMLHandle of the sound output.
bool *out_is_head_relativeIf true, coordinates are head-relative.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown failure.
MLResultMLAudioResult_HandleNotFoundFailed due to a missing handle.
MLResultMLAudioResult_InternalConfigErrorFailed due to an internal configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.

Required Permissions:

  • None

A head-relative coordinate system has an origin and orientation locked to the user's head center and forward direction. For spatial sounds with head-relative enabled, the position and direction as specified by MLAudioSetSpatialSoundPosition and MLAudioSetSpatialSoundDirection (and reported by MLAudioGetSpatialSoundPosition and MLAudioGetSpatialSoundDirection) are interpreted within such a coordinate system. For spatial sounds with head-relative disabled, the position and direction are interpreted within the world coordinate system defined by the platform. By default, head-relative is disabled for spatial sounds.

API Level:

  • 20

MLAudioGetSpatialRaycastRequests

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

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

Parameters

MLAudioRaycastRequest **out_raycast_requestsMLAudioRaycastRequest struct to be filled with requests for raycast operation.
uint32_t *out_request_countValue to be filled with number of raycast operations requested.

Returns

MLResultMLResult_OkSuccessfully set the properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

For a custom spatial audio to physics engine integration, typically handled by audio plugins, this function provides a list of raycasts to be performed by the physics engine.

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_resultsMLAudioRaycastResult struct to set the list of raycast operation results.
uint32_tresult_countSets the number of raycast results.

Returns

MLResultMLResult_OkSuccessfully retrieved the properties.
MLResultMLResult_InvalidParamIf input parameter is invalid.
MLResultMLResult_UnspecifiedFailureInternal error.
MLResultMLAudioResult_InternalConfigErrorInternal config error.
MLResultMLAudioResult_NotImplementedInternal error.

Required Permissions:

  • None

For a custom spatial audio to physics engine integration, typically handled by audio plugins, this function reports the results of raycasts performed by the physics engine.

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
)

Queries the minimum and recommended settings for buffered sound outputs.

Parameters

uint32_tchannel_countNumber of audio channels.
uint32_tsamples_per_secondSample rate for the buffered output.
floatmax_pitch_changeTop pitch (1.0 - 2.0) for this sound output.
MLAudioBufferFormat *out_formatMLAudioBufferFormat struct to be filled with recommended format properties.
uint32_t *out_recommended_size_in_bytesRetrieved recommended size.
uint32_t *out_min_size_in_bytesRetrieved minimum allowable size.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the properties.
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

This function is typically called before MLAudioCreateSoundWithBufferedOutput. It queries the minimum and recommended buffer sizes for the specified settings of channel count, sample rate, and 'max pitch change'. The max pitch change parameter determines the additional buffer size required to support pitch values greater than 1. Applying a pitch change to a buffered output that is greater than the specified max pitch change can lead to undesirable results.

API Level:

  • 7

MLAudioGetBufferedOutputLatency

MLResult MLAudioGetBufferedOutputLatency(
MLHandle handle,
float * out_latency_in_msec
)

Queries the latency for a buffered sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
float *out_latency_in_msecRetrieved latency in milliseconds.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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 latency for a buffered sound output is the time between when a buffer is enqueued via MLAudioReleaseOutputBuffer and when the corresponding audio is heard from the active audio output device. Note that output latency may change depending on which output device is active (for example, Bluetooth earbuds typically add latency compared to the built-in speakers in the headset).

API Level:

  • 7

MLAudioGetBufferedOutputFramesPlayed

MLResult MLAudioGetBufferedOutputFramesPlayed(
MLHandle handle,
uint64_t * out_frames_played
)

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

Parameters

MLHandlehandleMLHandle of the sound output.
uint64_t *out_frames_playedRetrieved number of audio frames played.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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 call queries the number of audio frames played by a buffered output since the last call to MLAudioStartSound. A subsequent call to MLAudioStartSound sets the count back to 0.

API Level:

  • 7

MLAudioGetOutputBuffer

MLResult MLAudioGetOutputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)

Retrieves an empty buffer for writing audio data for a buffered sound output.

Parameters

MLHandlehandleMLHandle of the sound output.
MLAudioBuffer *out_bufRetrieved MLAudioBuffer struct pointer to buffer for writing audio data.

Returns

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

Required Permissions:

  • None

Standard usage is to call this function by polling or within a callback of type MLAudioBufferCallback registered with MLAudioCreateSoundWithBufferedOutput. This call returns MLAudioResult_BufferNotReady if a buffer is not available for writing audio data, informing the caller to wait. Once filled, the buffer must be released by calling MLAudioReleaseOutputBuffer.

API Level:

  • 7

MLAudioReleaseOutputBuffer

MLResult MLAudioReleaseOutputBuffer(
MLHandle handle
)

Releases a filled audio output buffer for playback through a buffered sound output.

Parameters

MLHandlehandleMLHandle of the sound output.

Returns

MLResultMLResult_OkSuccessfully released the 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 configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

After filling a buffer retrieved by MLAudioGetOutputBuffer, the buffer must be released using this function in order to be played through a sound output.

API Level:

  • 7

MLAudioGetMasterVolume

MLResult MLAudioGetMasterVolume(
float * out_volume
)

Queries the master volume.

Parameters

float *out_volumeRetrieved master volume.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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

MLAudioMasterVolumeChangedCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.

Returns

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

Required Permissions:

  • None

MLAudioGetOutputMute

MLResult MLAudioGetOutputMute(
bool * out_is_muted
)

Queries the state of the global output mute.

Parameters

bool *boolout_is_muted If true, global output is muted.

Returns

MLResultMLResult_OkSuccessfully retrieved the value.
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

API Level:

  • 20

MLAudioSetOutputMuteCallback

MLResult MLAudioSetOutputMuteCallback(
MLAudioOutputMuteChangedCallback callback,
void * context
)

Registers a callback for changes to the global output mute.

Parameters

MLAudioOutputMuteChangedCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.

Returns

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

Required Permissions:

  • None

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 wearable microphones.

Parameters

MLAudioMicCaptureTypemic_capture_typeMLAudioMicCaptureType enum specifying the type of mic capture created.
const MLAudioBufferFormat *formatMLAudioBufferFormat struct specifying the format properties.
uint32_tbuffer_sizeRequested size in bytes for each of the two stream buffers.
MLAudioBufferCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_handleMLHandle to be used in subsequent calls.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created a sound input.
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)

The various mic capture streams represent different configurations of the input from the wearable microphones, intended for different purposes. The 'format' argument must be populated with the correct settings for the mic capture type being requested:

MLAudioMicCaptureType_VoiceComm is intended for remote communications, and uses a channel count of 1 and a sample rate of 16,000.

MLAudioMicCaptureType_VoiceCapture is intended for device-local applications involving user voice, and uses a channel count of 1 and a sample rate of 48,000.

MLAudioMicCaptureType_WorldCapture provides a stereo capture of the user's physical environment, and uses a channel count of 2 and a sample rate of 48,000.

MLAudioMicCaptureType_RawMicsAndAECRef provides a 6-channel capture comprising all 4 mics (unprocessed) plus the AEC reference signal from the amplifier, and uses a channel count of 6 and a sample rate of 48,000.

After creation, the input is started by calling MLAudioStartInput. After the input has been started, the next available full buffer is retrieved by calling MLAudioGetInputBuffer. This can be done on a polling basis, or a callback can be set using the 'callback' argument of the present function to notify when a buffer is available. After retrieving and consuming the next available buffer, MLAudioReleaseInputBuffer must be called to indicate that the buffer has been consumed and is ready to be refilled. MLAudioGetInputBuffer and MLAudioReleaseInputBuffer are valid to call within the callback. The 'buffer_size' argument will use the recommended size if 0 is passed in.

API Level:

  • 20

MLAudioCreateInputFromVirtualCapture

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

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

Parameters

const MLAudioBufferFormat *formatMLAudioBufferFormat struct specifying the format properties.
uint32_tbuffer_sizeRequested size in bytes of the buffers.
MLAudioBufferCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_handleMLHandle to be used in subsequent calls.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound input.
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)

The Virtual Capture stream is a stereo stream capturing the combined audio output mix of the capture-eligible sounds (typically app-generated) currently being played by the audio rendering engine. The 'format' argument must be populated with the correct settings for virtual capture, which uses a channel count of 2 and a sample rate of 48,000.

After creation, the input is started by calling MLAudioStartInput. After the input has been started, the next available full buffer is retrieved by calling MLAudioGetInputBuffer. This can be done on a polling basis, or a callback can be set using the 'callback' argument of the present function to notify when a buffer is available. After retrieving and consuming the next available buffer, MLAudioReleaseInputBuffer must be called to indicate that the buffer has been consumed and is ready to be refilled. MLAudioGetInputBuffer and MLAudioReleaseInputBuffer are valid to call within the callback. The 'buffer_size' argument will use the recommended size if 0 is passed in.


MLAudioCreateInputFromMixedCapture

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

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

Parameters

const MLAudioBufferFormat *formatMLAudioBufferFormat struct specifying the format properties.
uint32_tbuffer_sizeRequested size in bytes of the buffers.
MLAudioBufferCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_handleMLHandle to be used in subsequent calls.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully created sound input.
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)

The Mixed Capture stream is intended for capturing the audible user experience, including both sounds from the physical environment and sounds produced by the device. The stream includes a mix of the 'Virtual Capture' stream, the MLAudioMicCaptureType_VoiceCapture stream, and the MLAudioMicCaptureType_WorldCapture stream. By default the World Capture stream is silent and the other two streams are full volume. These levels can be adjusted by calling MLAudioSetMixedCaptureMix. Independent of the specified MixedCaptureMix, the Voice Capture and World Capture mic signals are scaled on a curve based on the current setting of Master Volume to keep the real and virtual signals in good balance. The Mixed Capture stream uses a channel count of 2 and a sample rate of 48,000.

After creation, the input is started by calling MLAudioStartInput. After the input has been started, the next available full buffer is retrieved by calling MLAudioGetInputBuffer. This can be done on a polling basis, or a callback can be set using the 'callback' argument of the present function to notify when a buffer is available. After retrieving and consuming the next available buffer, MLAudioReleaseInputBuffer must be called to indicate that the buffer has been consumed and is ready to be refilled. MLAudioGetInputBuffer and MLAudioReleaseInputBuffer are valid to call within the callback. The 'buffer_size' argument will use the recommended size if 0 is passed in.


MLAudioDestroyInput

MLResult MLAudioDestroyInput(
MLHandle handle
)

Destroys a sound input.

Parameters

MLHandlehandleMLHandle of the sound input.

Returns

MLResultMLResult_OkSuccessfully destroyed a 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 a sound input.

Parameters

MLHandlehandleMLHandle of the sound input.

Returns

MLResultMLResult_OkSound input is started, or continues if already playing.
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

Calling this function on a playing input has no effect and returns success.


MLAudioStopInput

MLResult MLAudioStopInput(
MLHandle handle
)

Stops a sound input.

Parameters

MLHandlehandleMLHandle of the sound input.

Returns

MLResultMLResult_OkSound input is stopped, or remains stopped if already stopped.
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

Calling this function on a stopped input has no effect and returns success.


MLAudioGetInputState

MLResult MLAudioGetInputState(
MLHandle handle,
MLAudioState * out_state
)

Queries the activity state of a sound input.

Parameters

MLHandlehandleMLHandle of the sound input.
MLAudioState *out_stateMLAudioState enum of the sound input.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the properties.
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 state of sound inputs can be either MLAudioState_Playing or MLAudioState_Stopped, depending on whether MLAudioStartInput or MLAudioStopInput was called most recently. When an input is stopped and restarted, its buffers are emptied and buffering begins again from a clean slate.


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
)

Queries the minimum and recommended settings for buffered sound inputs.

Parameters

uint32_tchannel_countNumber of audio channels.
uint32_tsamples_per_secondSample rate for the buffered input.
MLAudioBufferFormat *out_formatMLAudioBufferFormat struct to be filled with recommended format properties.
uint32_t *out_recommended_size_in_bytesRetrieved recommended size.
uint32_t *out_min_size_in_bytesRetrieved minimum allowable size.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the properties.
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

This function is typically called before one of the MLAudioCreateInput... calls. It queries the minimum and recommended buffer sizes for the specified settings of channel count and sample rate.

API Level:

  • 7

MLAudioGetBufferedInputLatency

MLResult MLAudioGetBufferedInputLatency(
MLHandle handle,
float * out_latency_in_msec
)

Queries the latency for a sound input.

Parameters

MLHandlehandleMLHandle of the sound input.
float *out_latency_in_msecRetrieved latency in milliseconds.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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 latency for a sound input is the time between when a sound is picked up at the microphone and when the corresponding audio becomes available via a call to MLAudioGetInputBuffer.

API Level:

  • 7

MLAudioGetInputBuffer

MLResult MLAudioGetInputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)

Retrieves a full buffer of audio data from a sound input.

Parameters

MLHandlehandleMLHandle of the sound input.
MLAudioBuffer *out_bufRetrieved MLAudioBuffer struct pointer to buffer for reading audio data.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the 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 configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

Standard usage is to call this function by polling or within a callback of type MLAudioBufferCallback registered with one of the MLAudioCreateInput... calls. This call returns MLAudioResult_BufferNotReady if a buffer is not available for reading audio data, informing the caller to wait. Once consumed, the buffer must be released by calling MLAudioReleaseInputBuffer.

API Level:

  • 7

MLAudioReleaseInputBuffer

MLResult MLAudioReleaseInputBuffer(
MLHandle handle
)

Releases an input buffer once it has been consumed.

Parameters

MLHandlehandleMLHandle of the sound input.

Returns

MLResultMLResult_OkSuccessfully released the 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 configuration error.
MLResultMLAudioResult_NotImplementedFailed because feature has not been implemented yet.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

After consuming a buffer retrieved by MLAudioGetInputBuffer, the buffer must be released using this function in order to indicate that the buffer has been consumed and can now be refilled.

API Level:

  • 7

MLAudioSetMicMute

MLResult MLAudioSetMicMute(
bool is_muted
)

Sets the global input mute state for all input streams.

Parameters

boolis_mutedIf true, capture streams will be muted globally.

Returns

MLResultMLResult_OkSuccessfully set the value.
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 global input mute applies to all input streams, including microphones, Virtual Capture and Mixed Capture. Any app with capture privileges can set it, and it will apply for all apps.


MLAudioGetMicMute

MLResult MLAudioGetMicMute(
bool * out_is_muted
)

Queries the global input mute state for all input streams.

Parameters

bool *out_is_mutedIf true, capture streams are muted globally.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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 global input mute applies to all input streams, including microphones, Virtual Capture and Mixed Capture. Any app with capture privileges can set it, and it will apply for all apps.

API Level:

  • 20

MLAudioSetMicMuteCallback

MLResult MLAudioSetMicMuteCallback(
MLAudioMicMuteCallback callback,
void * context
)

Registers a callback for changes to the global input mute state.

Parameters

MLAudioMicMuteCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.

Returns

MLResultMLResult_AllocFailedFailed due to memory allocation failure.
MLResultMLResult_OkSuccessfully registered the 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)

MLAudioBeginTraitAnalysisFromMicCapture

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

Starts a trait analysis of the energy contained in the mic signals.

Parameters

MLAudioTraitAnalysisTargettargetMLAudioTraitAnalysisTarget enum specifying the type of analysis requested.
MLAudioTraitAnalysisCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_handleMLHandle to be used in subsequent calls.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully began analysis.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.

Required Permissions:

  • None

A trait analysis measures the characteristics of an audio stream, producing a single value representing the result of the analysis at a point in time. This function creates a new 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. 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, triggered whenever a new value is available.

API Level:

  • 20

MLAudioGetTraitAnalysis

MLResult MLAudioGetTraitAnalysis(
MLHandle handle,
float * out_value
)

Queries the current value of the trait analysis.

Parameters

MLHandlehandleMLHandle of the analysis.
float *out_valueRetrieved value of trait analysis.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved the value.
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 trait analysis.

Parameters

MLHandlehandleMLHandle of the analysis.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully ended analysis.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.

Required Permissions:

  • None

API Level:

  • 20

MLAudioBeginSpectralAnalysisFromMicCapture

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

Starts a spectral analysis of the energy contained in the mic signals.

Parameters

MLAudioSpectralAnalysisTargettargetMLAudioSpectralAnalysisTarget enum specifying type of analysis requested.
MLAudioSpectralAnalysisCallbackcallbackCallback function pointer.
void *contextGeneric data pointer passed back through the callback.
MLHandle *out_handleMLHandle to be used in subsequent calls.

Returns

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

Required Permissions:

  • None

A spectral analysis measures the characteristics of an audio stream on a per-frequency-band basis. This function creates a new 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 the MLAudioSpectralAnalysis struct passed in the optional callback is handled by the audio system; i.e., the caller is not responsible for deallocating memory if the callback is used.

API Level:

  • 20

MLAudioGetSpectralAnalysis

MLResult MLAudioGetSpectralAnalysis(
MLHandle handle,
MLAudioSpectralAnalysis * out_values
)

Queries the current values of a spectral analysis.

Parameters

MLHandlehandleMLHandle of the spectral analysis.
MLAudioSpectralAnalysis *out_valuesMLAudioSpectralAnalysis struct to be filled with the results properties.

Returns

MLResultMLResult_InvalidParamFailed due to an invalid parameter.
MLResultMLResult_OkSuccessfully retrieved analysis.
MLResultMLResult_UnspecifiedFailureFailed due to an unknown error.
MLResultMLAudioResult_OperationUnavailableFailed because operation is unavailable.

Required Permissions:

  • None

To store the values being queried, this function allocates a memory block which is pointed to by the 'values' field of the MLAudioSpectralAnalysis struct passed as the 'out_values' argument. The format of the data in this memory block can vary based on the selected 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 spectral analysis.

Parameters

MLHandlehandleMLHandle of the spectral analysis.

Returns

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

Required Permissions:

  • None

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 handle, bool is_billboarding);

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

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

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

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

ML_API MLResult ML_CALL MLAudioGetSpatialSoundObstructionOverride(MLHandle handle, 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 *context, MLHandle *out_handle);

ML_API MLResult ML_CALL MLAudioCreateInputFromMixedCapture(const MLAudioBufferFormat *format, uint32_t buffer_size, MLAudioBufferCallback callback, void *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 *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 *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