Version: 20 Mar 2024

ml_audio.h

Classes

	Name
struct	MLAudioMultibandLevel Properties specifying a broadband level and three sub-band levels.
struct	MLAudioDispersionProperties Properties specifying acoustic dispersion (clustered reflections).
struct	MLAudioReverbProperties Properties specifying acoustic reverberation.
struct	MLAudioSpatialSoundDistanceProperties
struct	MLAudioSpatialSoundRadiationProperties
struct	MLAudioRaycast Two points in space describing a ray.
struct	MLAudioObstruction Obstruction along a ray.
struct	MLAudioRaycastRequest ID-tracked request for a single raycast operation.
struct	MLAudioRaycastResult ID-tracked result for a single raycast operation.
struct	MLAudioBufferFormat Buffer format settings for input and output streams.
struct	MLAudioBuffer
struct	MLAudioSpectralAnalysis

Types

	Name
typedef struct MLAudioMultibandLevel	MLAudioMultibandLevel Properties specifying a broadband level and three sub-band levels.
typedef struct MLAudioDispersionProperties	MLAudioDispersionProperties Properties specifying acoustic dispersion (clustered reflections).
typedef struct MLAudioReverbProperties	MLAudioReverbProperties Properties specifying acoustic reverberation.
typedef struct MLAudioSpatialSoundDistanceProperties	MLAudioSpatialSoundDistanceProperties
typedef struct MLAudioSpatialSoundRadiationProperties	MLAudioSpatialSoundRadiationProperties
typedef struct MLAudioRaycast	MLAudioRaycast Two points in space describing a ray.
typedef struct MLAudioObstruction	MLAudioObstruction Obstruction along a ray.
typedef struct MLAudioRaycastRequest	MLAudioRaycastRequest ID-tracked request for a single raycast operation.
typedef struct MLAudioRaycastResult	MLAudioRaycastResult ID-tracked result for a single raycast operation.
typedef struct MLAudioBufferFormat	MLAudioBufferFormat Buffer format settings for input and output streams.
typedef struct MLAudioBuffer	MLAudioBuffer
typedef struct MLAudioSpectralAnalysis	MLAudioSpectralAnalysis
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
enum	MLAudioState { MLAudioState_Stopped, MLAudioState_Playing, MLAudioState_Paused, MLAudioState_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioSoundEvent { MLAudioSoundEvent_End, MLAudioSoundEvent_Loop, MLAudioSoundEvent_MutedBySystem, MLAudioSoundEvent_UnmutedBySystem, MLAudioSoundEvent_DuckedBySystem, MLAudioSoundEvent_UnduckedBySystem, MLAudioSoundEvent_ResourceDestroyed, MLAudioSoundEvent_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioMediaEvent { MLAudioMediaEvent_Play, MLAudioMediaEvent_Stop, MLAudioMediaEvent_Pause, MLAudioMediaEvent_NextTrack, MLAudioMediaEvent_PrevTrack, MLAudioMediaEvent_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioOutputDevice { MLAudioOutputDevice_Wearable, MLAudioOutputDevice_USB, MLAudioOutputDevice_Bluetooth, MLAudioOutputDevice_HearingAid, MLAudioOutputDevice_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioMicCaptureType { MLAudioMicCaptureType_VoiceComm, MLAudioMicCaptureType_VoiceCapture, MLAudioMicCaptureType_WorldCapture =4, MLAudioMicCaptureType_RawMicsAndAECRef, MLAudioMicCaptureType_Ensure32Bits =0x7FFFFFFF } The type of mic input to capture.
enum	MLAudioSampleFormat { MLAudioSampleFormat_Int, MLAudioSampleFormat_Float, MLAudioSampleFormat_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioChannelFormat { MLAudioChannelFormat_Default, MLAudioChannelFormat_AmbisonicAmbix, MLAudioChannelFormat_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioTraitAnalysisTarget { MLAudioTraitAnalysisTarget_AmbientSoundLevelDbfs, MLAudioTraitAnalysisTarget_UserVoicePresence, MLAudioTraitAnalysisTarget_UserVoiceLevelDbfs, MLAudioTraitAnalysisTarget_UserVoicePitch, MLAudioTraitAnalysisTarget_Ensure32Bits = 0x7FFFFFFF }
enum	MLAudioSpectralAnalysisTarget { MLAudioSpectralAnalysisTarget_UserVoiceSpectrumMfcc, MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumBark, MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumMel, MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumThirdOctave, MLAudioSpectralAnalysisTarget_Ensure32Bits = 0x7FFFFFFF }
enum	Anonymous Enum 3 { MLResultAPIPrefix_Audio = ( 0x9e11 << 16) }
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 } Return values for Audio Service API calls.

Functions

	Name
const char *	MLAudioGetResultString(MLResult result_code) Returns an ASCII string for each result code.
MLResult	MLAudioCreateLoadedResource(int file, bool dynamic_decode, MLAudioResourceDiscardedCallback callback, void context, MLHandle out_resource) Creates a new Loaded Resource that references a loaded audio file.
MLResult	MLAudioCreateStreamedResource(int file, MLAudioResourceDiscardedCallback callback, void context, MLHandle out_resource) Creates a new audio resource that references a streamed audio file.
MLResult	MLAudioCheckResource(MLHandle resource, bool * out_is_ready) Queries whether a Loaded or Streamed Resource has been discarded due to system limits.
MLResult	MLAudioGetResourceSize(MLHandle resource, uint32_t * out_size_in_bytes) Queries the size of the memory footprint for a Loaded Resource.
MLResult	MLAudioRefreshResource(MLHandle resource, int file) Refreshes a resource whose data was discarded due to system limits.
MLResult	MLAudioDestroyResource(MLHandle resource) Destroys a previously created audio resource.
MLResult	MLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle) Creates a sound output referencing a Loaded Audio Resource.
MLResult	MLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle) Creates a sound output referencing a Streamed Audio Resource.
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.
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.
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.
MLResult	MLAudioDestroySound(MLHandle handle) Destroys a previously created sound output.
MLResult	MLAudioStartSound(MLHandle handle) Starts playback for a sound output.
MLResult	MLAudioStopSound(MLHandle handle) Stops playback for a sound output.
MLResult	MLAudioPauseSound(MLHandle handle) Pauses playback for a currently playing sound output.
MLResult	MLAudioResumeSound(MLHandle handle) Resumes playback for a currently paused sound output.
MLResult	MLAudioGetSoundState(MLHandle handle, MLAudioState * out_state) Queries the playback state of a sound output.
MLResult	MLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat * out_format) Queries the audio format of a sound output.
MLResult	MLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void * context) Registers a callback for Sound Events relating to a sound output.
MLResult	MLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void * context) Registers a callback for media transport events.
MLResult	MLAudioSetSoundVolumeLinear(MLHandle handle, float volume) Sets the volume of a sound output using a linear scale.
MLResult	MLAudioGetSoundVolumeLinear(MLHandle handle, float * out_volume) Queries the volume of a sound output in a linear scale.
MLResult	MLAudioSetSoundVolumeDb(MLHandle handle, float volume) Sets the volume of a sound output using a decibel scale.
MLResult	MLAudioGetSoundVolumeDb(MLHandle handle, float * out_volume) Queries the volume of a sound output using a decibel scale.
MLResult	MLAudioSetSoundPitch(MLHandle handle, float pitch) Sets the pitch of a sound output by modifying its playback speed.
MLResult	MLAudioGetSoundPitch(MLHandle handle, float * out_pitch) Queries the pitch of a sound output which corresponds to its playback speed.
MLResult	MLAudioSetSoundMute(MLHandle handle, bool is_muted) Sets the mute state of a sound output.
MLResult	MLAudioGetSoundMute(MLHandle handle, bool * out_is_muted) Queries the mute state of a sound output.
MLResult	MLAudioSetSoundBypassesMasterVolume(MLHandle handle, bool is_bypassing) Sets whether a sound output is exempt from attenuation due to master volume.
MLResult	MLAudioGetSoundBypassesMasterVolume(MLHandle handle, bool * out_is_bypassing) Queries whether a sound output is exempt from attenuation due to master volume.
MLResult	MLAudioSetSoundLooping(MLHandle handle, bool is_looping) Sets whether a sound output is looping or not.
MLResult	MLAudioGetSoundLooping(MLHandle handle, bool * out_is_looping) Queries whether a sound output is looping or not.
MLResult	MLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec) Sets the playback position of a sound output that's playing a Streamed File.
MLResult	MLAudioGetStreamedFileOffset(MLHandle handle, uint32_t * out_offset_in_msec) Queries the playback position of a sound output that's playing a Streamed File.
MLResult	MLAudioGetOutputDevice(MLAudioOutputDevice * out_current_device) Queries which type of sound output device is being used for sound output.
MLResult	MLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void * context) Registers a callback for when the active audio hardware output has changed.
MLResult	MLAudioResetAcousticScene() Resets the Acoustic Scene.
MLResult	MLAudioBeginAcousticSceneUpdate() Pauses the processing of changes to the Acoustic Scene.
MLResult	MLAudioEndAcousticSceneUpdate() Resumes the processing of changes to the Acoustic Scene.
MLResult	MLAudioSetAcousticSceneMapEnable(bool is_enabled) Sets whether spatial rendering emulates the acoustics of the user's environment.
MLResult	MLAudioGetAcousticSceneMapEnable(bool * out_is_enabled) Queries whether spatial rendering emulates the acoustics of the user's environment.
MLResult	MLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel * transmission) Sets the default attenuation applied to obstructed spatial sounds.
MLResult	MLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel * out_transmission) Queries the default attenuation applied to obstructed spatial sounds.
MLResult	MLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties * properties) Sets the default dispersion properties, which control the rendering of clustered reflections.
MLResult	MLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties * out_properties) Queries the default dispersion properties, which control the rendering of clustered reflections.
MLResult	MLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties * properties) Sets the default reverb properties, which control the rendering of late reverberation.
MLResult	MLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties * out_properties) Queries the default reverb properties, which control the rendering of late reverberation.
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.
MLResult	MLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled) Sets whether a sound output is enabled as a spatial sound.
MLResult	MLAudioGetSpatialSoundEnable(MLHandle handle, bool * out_is_enabled) Queries whether a sound output is enabled as a spatial sound.
MLResult	MLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f * position) Sets the 3D position for one channel of a spatial sound.
MLResult	MLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f * out_position) Queries the 3D position of one channel of a spatial sound.
MLResult	MLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf * direction) Sets the 3D direction for one channel of a spatial sound.
MLResult	MLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf * out_direction) Queries the 3D direction of one channel of a spatial sound.
MLResult	MLAudioSetSpatialSoundBillboarding(MLHandle handle, bool is_billboarding) Enables or disables billboarding for all channels of a spatial sound.
MLResult	MLAudioGetSpatialSoundBillboarding(MLHandle handle, bool * out_is_billboarding) Queries whether billboarding is enabled for a spatial sound.
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.
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.
MLResult	MLAudioSetSpatialSoundObstructionOverride(MLHandle handle, const MLAudioMultibandLevel * override) Sets the extent to which a spatial sound is exempt from obstruction effects.
MLResult	MLAudioGetSpatialSoundObstructionOverride(MLHandle handle, MLAudioMultibandLevel * out_override) Queries the extent to which a spatial sound is exempt from obstruction effects.
MLResult	MLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties * properties) Sets the behavior by which a spatial sound is attenuated due to distance.
MLResult	MLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties * out_properties) Queries the behavior by which a spatial sound is attenuated due to distance.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
MLResult	MLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative) Sets whether the position and direction for a spatial sound are interpreted in head-relative coordinates.
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.
MLResult	MLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest * out_raycast_requests, uint32_t out_request_count) Queries a list of ID-tracked requests for raycast operations.
MLResult	MLAudioSetSpatialRaycastResults(MLAudioRaycastResult * raycast_results, uint32_t result_count) Sets the ID-tracked results for previously requested raycast operations.
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.
MLResult	MLAudioGetBufferedOutputLatency(MLHandle handle, float * out_latency_in_msec) Queries the latency for a buffered sound output.
MLResult	MLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t * out_frames_played) Queries the number of audio frames played by a buffered output.
MLResult	MLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer * out_buf) Retrieves an empty buffer for writing audio data for a buffered sound output.
MLResult	MLAudioReleaseOutputBuffer(MLHandle handle) Releases a filled audio output buffer for playback through a buffered sound output.
MLResult	MLAudioGetMasterVolume(float * out_volume) Queries the master volume.
MLResult	MLAudioSetMasterVolumeCallback(MLAudioMasterVolumeChangedCallback callback, void * context) Registers a callback for changes to the master volume.
MLResult	MLAudioGetOutputMute(bool * out_is_muted) Queries the state of the global output mute.
MLResult	MLAudioSetOutputMuteCallback(MLAudioOutputMuteChangedCallback callback, void * context) Registers a callback for changes to the global output mute.
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.
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.
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.
MLResult	MLAudioDestroyInput(MLHandle handle) Destroys a sound input.
MLResult	MLAudioStartInput(MLHandle handle) Starts a sound input.
MLResult	MLAudioStopInput(MLHandle handle) Stops a sound input.
MLResult	MLAudioGetInputState(MLHandle handle, MLAudioState * out_state) Queries the activity state of a sound input.
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.
MLResult	MLAudioGetBufferedInputLatency(MLHandle handle, float * out_latency_in_msec) Queries the latency for a sound input.
MLResult	MLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer * out_buf) Retrieves a full buffer of audio data from a sound input.
MLResult	MLAudioReleaseInputBuffer(MLHandle handle) Releases an input buffer once it has been consumed.
MLResult	MLAudioSetMicMute(bool is_muted) Sets the global input mute state for all input streams.
MLResult	MLAudioGetMicMute(bool * out_is_muted) Queries the global input mute state for all input streams.
MLResult	MLAudioSetMicMuteCallback(MLAudioMicMuteCallback callback, void * context) Registers a callback for changes to the global input mute state.
MLResult	MLAudioBeginTraitAnalysisFromMicCapture(MLAudioTraitAnalysisTarget target, MLAudioTraitAnalysisCallback callback, void context, MLHandle out_handle) Starts a trait analysis of the energy contained in the mic signals.
MLResult	MLAudioGetTraitAnalysis(MLHandle handle, float * out_value) Queries the current value of the trait analysis.
MLResult	MLAudioEndTraitAnalysis(MLHandle handle) Stops a trait analysis.
MLResult	MLAudioBeginSpectralAnalysisFromMicCapture(MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysisCallback callback, void context, MLHandle out_handle) Starts a spectral analysis of the energy contained in the mic signals.
MLResult	MLAudioGetSpectralAnalysis(MLHandle handle, MLAudioSpectralAnalysis * out_values) Queries the current values of a spectral analysis.
MLResult	MLAudioEndSpectralAnalysis(MLHandle handle) Stops a spectral analysis.

Enums Documentation

MLAudioState

Enumerator	Value	Description
MLAudioState_Stopped		Stopped, can be started.
MLAudioState_Playing		Playing, can be stopped or paused.
MLAudioState_Paused		Paused, can be resumed or re-started.
MLAudioState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Possible playback states for sounds and inputs.

MLAudioSoundEvent

Enumerator	Value	Description
MLAudioSoundEvent_End		A sound output has reached the end and is stopping.
MLAudioSoundEvent_Loop		A sound output has reached the end and is looping.
MLAudioSoundEvent_MutedBySystem		A sound output has been muted due to system conditions.
MLAudioSoundEvent_UnmutedBySystem		A previously muted sound output has been unmuted due to system conditions.
MLAudioSoundEvent_DuckedBySystem		A sound output has been ducked due to system conditions.
MLAudioSoundEvent_UnduckedBySystem		A previously ducked sound output has been unducked due to system conditions.
MLAudioSoundEvent_ResourceDestroyed		The resource used by a sound output has been destroyed.
MLAudioSoundEvent_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Possible events for individual sound outputs.

MLAudioMediaEvent

Enumerator	Value	Description
MLAudioMediaEvent_Play		Indicates a user command to play.
MLAudioMediaEvent_Stop		Indicates a user command to stop.
MLAudioMediaEvent_Pause		Indicates a user command to pause.
MLAudioMediaEvent_NextTrack		Indicates a user command to go to next track.
MLAudioMediaEvent_PrevTrack		Indicates a user command to go to previous track.
MLAudioMediaEvent_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Possible media control events initiated by the user.

MLAudioOutputDevice

Enumerator	Value	Description
MLAudioOutputDevice_Wearable		Built-in speakers in the wearable.
MLAudioOutputDevice_USB		USB audio from the beltpack.
MLAudioOutputDevice_Bluetooth		A2DP audio via Bluetooth.
MLAudioOutputDevice_HearingAid		Hearing Aid audio via Bluetooth.
MLAudioOutputDevice_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

The currently active output device.

MLAudioMicCaptureType

Enumerator	Value	Description
MLAudioMicCaptureType_VoiceComm		User voice, suitable for communications. Mono, 16 bit integer, 16k sampling rate.
MLAudioMicCaptureType_VoiceCapture		High fidelity user voice, suitable for recording. Mono, 16 bit integer, 48k sampling rate.
MLAudioMicCaptureType_WorldCapture	=4	Mic mix representing the user's surroundings. Stereo, 16 bit integer, 48k sampling rate.
MLAudioMicCaptureType_RawMicsAndAECRef		All 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	=0x7FFFFFFF	Ensure enum is represented as 32 bits.

The type of mic input to capture.

API Level:

MLAudioSampleFormat

Enumerator	Value	Description
MLAudioSampleFormat_Int		Samples are integer.
MLAudioSampleFormat_Float		Samples are float. Not currently implemented for buffered I/O.
MLAudioSampleFormat_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Possible sample formats for input and output streams.

MLAudioChannelFormat

Enumerator	Value	Description
MLAudioChannelFormat_Default		Infer channel format from buffer format settings.
MLAudioChannelFormat_AmbisonicAmbix		Ambisonic AmbiX format.
MLAudioChannelFormat_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Channel formats for buffered outputs.

MLAudioTraitAnalysisTarget

Enumerator	Value	Description
MLAudioTraitAnalysisTarget_AmbientSoundLevelDbfs		Ambient Sound Level dBFS, a full scale sound level measurement of an ambient mic stream.
MLAudioTraitAnalysisTarget_UserVoicePresence		Voice Presence, indicates absence (0) or presence (1) of voice in a voice mic stream.
MLAudioTraitAnalysisTarget_UserVoiceLevelDbfs		Voice Level dBFS, a full scale sound level measurement of a voice mic stream.
MLAudioTraitAnalysisTarget_UserVoicePitch		Voice Pitch, frequency in hertz of the voice in a voice mic stream.
MLAudioTraitAnalysisTarget_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Available trait analyses of an audio stream.

MLAudioSpectralAnalysisTarget

Enumerator	Value	Description
MLAudioSpectralAnalysisTarget_UserVoiceSpectrumMfcc		Voice Mel Frequency Cepstral Coefficients (MFCC), spectral analysis of a voice mic stream. (typically used for lip-sync).
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumBark		Ambient Sound Spectrum Bark Scale, spectral analysis of ambient mic stream(s) using Bark scale.
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumMel		Ambient Sound Spectrum Mel Scale, spectral analysis of ambient mic stream(s) using Mel scale.
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumThirdOctave		Ambient Sound Spectrum Third Octave Scale, spectral analysis of ambient mic stream(s) using a 1/3 octave scale.
MLAudioSpectralAnalysisTarget_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Available frequency spectrum analyses of an audio stream.

Anonymous Enum 3

Enumerator	Value	Description
MLResultAPIPrefix_Audio	( 0x9e11 << 16)	Defines the prefix for MLAudioResult codes.

MLAudioResult

Enumerator	Value	Description
MLAudioResult_NotImplemented	MLResultAPIPrefix_Audio	Function not implemented.
MLAudioResult_HandleNotFound		Not a valid MLHandle for a sound or input.
MLAudioResult_InvalidSampleRate		Sample rate not supported.
MLAudioResult_InvalidBitsPerSample		Bits per sample not supported.
MLAudioResult_InvalidValidBits		Valid bits per sample not supported.
MLAudioResult_InvalidSampleFormat		Sample format not supported.
MLAudioResult_InvalidChannelCount		Channel count not supported.
MLAudioResult_InvalidBufferSize		Buffer size too small.
MLAudioResult_BufferNotReady		Buffer not ready for read or write.
MLAudioResult_FileNotFound		Specified file not found.
MLAudioResult_FileNotRecognized		Specified file has unsupported format.
MLAudioResult_ResourceNotFound		Specified resource is not on the list.
MLAudioResult_ResourceDiscarded		Data was unloaded or file was closed.
MLAudioResult_OperationUnavailable		Requested operation not possible for given item.
MLAudioResult_OperationNotReady		Requested operation has not yet been processed.
MLAudioResult_InternalConfigError		Internal configuration problem was detected.
MLAudioResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Return values for Audio Service API calls.

API Level:

Types Documentation

MLAudioMultibandLevel

typedef struct MLAudioMultibandLevel MLAudioMultibandLevel;

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

More Info

API Level:

MLAudioDispersionProperties

typedef struct MLAudioDispersionProperties MLAudioDispersionProperties;

Properties specifying acoustic dispersion (clustered reflections).

More Info

API Level:

MLAudioReverbProperties

typedef struct MLAudioReverbProperties MLAudioReverbProperties;

Properties specifying acoustic reverberation.

More Info

API Level:

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:

MLAudioObstruction

typedef struct MLAudioObstruction MLAudioObstruction;

Obstruction along a ray.

More Info

API Level:

MLAudioRaycastRequest

typedef struct MLAudioRaycastRequest MLAudioRaycastRequest;

ID-tracked request for a single raycast operation.

More Info

API Level:

MLAudioRaycastResult

typedef struct MLAudioRaycastResult MLAudioRaycastResult;

ID-tracked result for a single raycast operation.

More Info

API Level:

MLAudioBufferFormat

typedef struct MLAudioBufferFormat MLAudioBufferFormat;

Buffer format settings for input and output streams.

More Info

API Level:

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


MLResult	result_code	MLResult 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


int	file	File descriptor specifying the audio file.
bool	dynamic_decode	Not currently implemented.
MLAudioResourceDiscardedCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_resource	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created resource.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_FileNotRecognized	Failed because file was not recognized.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to invalid bits per sample.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

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

MLAudioCreateStreamedResource

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

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

Parameters


int	file	File descriptor specifying the audio file.
MLAudioResourceDiscardedCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_resource	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created resource.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

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

MLAudioCheckResource

MLResult MLAudioCheckResource(
    MLHandle resource,
    bool * out_is_ready
)

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

Parameters


MLHandle	resource	MLHandle of the resource.
bool *	out_is_ready	If true, the resource is ready to use.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully reported the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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

MLAudioGetResourceSize

MLResult MLAudioGetResourceSize(
    MLHandle resource,
    uint32_t * out_size_in_bytes
)

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

Parameters


MLHandle	resource	MLHandle of the resource.
uint32_t *	out_size_in_bytes	The retrieved size of the memory footprint.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because Streamed Resource was queried.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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

API Level:

MLAudioRefreshResource

MLResult MLAudioRefreshResource(
    MLHandle resource,
    int file
)

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

Parameters


MLHandle	resource	MLHandle of the resource.
int	file	File descriptor specifying the audio file.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully refreshed resource.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_FileNotRecognized	Failed because file was not recognized.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to invalid bits per sample.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleFormat	Failed due to an invalid sample format.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidValidBits	Failed due to invalid valid bits.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

MLAudioDestroyResource

MLResult MLAudioDestroyResource(
    MLHandle resource
)

Destroys a previously created audio resource.

Parameters


MLHandle	resource	MLHandle of the resource.

Returns


MLResult	MLResult_Ok	Successfully destroyed resource.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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

MLAudioCreateSoundWithLoadedResource

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

Creates a sound output referencing a Loaded Audio Resource.

Parameters


MLHandle	resource	MLHandle of the Loaded Resource.
bool	auto_destroy	If true, the sound output is destroyed when playback reaches end of file.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound input.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_FileNotRecognized	Failed because file was not recognized.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to invalid bits per sample.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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

MLAudioCreateSoundWithStreamedResource

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

Creates a sound output referencing a Streamed Audio Resource.

Parameters


MLHandle	resource	MLHandle of the streamed audio resource.
bool	auto_destroy	If true, the sound output is destroyed when playback reaches end of file.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound output.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_ResourceDiscarded	Failed because file was closed.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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


int	file	File descriptor specifying the audio file.
bool	auto_destroy	If true, the sound output is destroyed when playback reaches end of file.
bool	dynamic_decode	Not currently implemented.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound output.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_FileNotRecognized	Failed because file was not recognized.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to invalid bits per sample.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidValidBits	Failed due to invalid valid bits.
MLResult	MLAudioResult_ResourceNotFound	Failed 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


int	file	File descriptor specifying the audio file.
bool	auto_destroy	If true, the sound output is destroyed when playback reaches end of file.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound output.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_FileNotFound	Failed because file was missing.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_ResourceDiscarded	Failed because file was closed.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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 *	format	MLAudioBufferFormat struct specifying the format properties.
uint32_t	buffer_size_in_bytes	Requested size in bytes for each of the output buffers.
MLAudioBufferCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound output.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleFormat	Failed due to an invalid sample format.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidValidBits	Failed due to invalid valid bits.

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:

MLAudioDestroySound

MLResult MLAudioDestroySound(
    MLHandle handle
)

Destroys a previously created sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.

Returns


MLResult	MLResult_Ok	Successfully destroyed sound output.
MLResult	MLResult_UnspecifiedFailure	Failed to destroy sound output due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed to destroy sound output due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed 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


MLHandle	handle	MLHandle of the sound output.

Returns


MLResult	MLResult_Ok	Sound output is started, or continues if already playing.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_ResourceDiscarded	Failed because file was closed.
MLResult	MLAudioResult_ResourceNotFound	Failed because resource was not found.

Required Permissions:

None

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

MLAudioStopSound

MLResult MLAudioStopSound(
    MLHandle handle
)

Stops playback for a sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.

Returns


MLResult	MLResult_Ok	Sound output is stopped, or remains stopped if already stopped.
MLResult	MLResult_UnspecifiedFailure	Failed to stop playback due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed to stop playback due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed to stop playback because feature has not been implemented yet.
MLResult	MLAudioResult_ResourceNotFound	Failed to stop playback because resource was not found.

Required Permissions:

None

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

MLAudioPauseSound

MLResult MLAudioPauseSound(
    MLHandle handle
)

Pauses playback for a currently playing sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.

Returns


MLResult	MLResult_Ok	Sound output is paused, or remains paused if already paused.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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

MLAudioResumeSound

MLResult MLAudioResumeSound(
    MLHandle handle
)

Resumes playback for a currently paused sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.

Returns


MLResult	MLResult_Ok	Sound output resumes playing.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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

MLAudioGetSoundState

MLResult MLAudioGetSoundState(
    MLHandle handle,
    MLAudioState * out_state
)

Queries the playback state of a sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.
MLAudioState *	out_state	MLAudioState enum to be filled with the current playback state.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

The MLAudioState enum defines the possible playback states which are Stopped, Playing and Paused.

MLAudioGetSoundFormat

MLResult MLAudioGetSoundFormat(
    MLHandle handle,
    MLAudioBufferFormat * out_format
)

Queries the audio format of a sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.
MLAudioBufferFormat *	out_format	MLAudioBufferFormat struct to be filled with the format properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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

MLAudioSetSoundEventCallback

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

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

Parameters


MLHandle	handle	MLHandle of the sound output.
MLAudioSoundEventCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully registered the callback.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

API Level:

MLAudioSetMediaEventCallback

MLResult MLAudioSetMediaEventCallback(
    MLAudioMediaEventCallback callback,
    void * context
)

Registers a callback for media transport events.

Parameters


MLAudioMediaEventCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.

Returns


MLResult	MLResult_AllocFailed	If memory allocation fails.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully registered the callback.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

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

API Level:

MLAudioSetSoundVolumeLinear

MLResult MLAudioSetSoundVolumeLinear(
    MLHandle handle,
    float volume
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
float	volume	The linear volume that the sound output will be set to.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioGetSoundVolumeLinear

MLResult MLAudioGetSoundVolumeLinear(
    MLHandle handle,
    float * out_volume
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
float *	out_volume	Retrieved linear volume of the sound output.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioSetSoundVolumeDb

MLResult MLAudioSetSoundVolumeDb(
    MLHandle handle,
    float volume
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
float	volume	The dB volume that the sound output will be set to.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioGetSoundVolumeDb

MLResult MLAudioGetSoundVolumeDb(
    MLHandle handle,
    float * out_volume
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
float *	out_volume	Retrieved dB volume of the sound output.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioSetSoundPitch

MLResult MLAudioSetSoundPitch(
    MLHandle handle,
    float pitch
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
float	pitch	The pitch of the sound output to be set.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioGetSoundPitch

MLResult MLAudioGetSoundPitch(
    MLHandle handle,
    float * out_pitch
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
float *	out_pitch	Retrieved pitch of the sound output.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioSetSoundMute

MLResult MLAudioSetSoundMute(
    MLHandle handle,
    bool is_muted
)

Sets the mute state of a sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.
bool	is_muted	If true, the sound output will be muted.

Returns


MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioGetSoundMute

MLResult MLAudioGetSoundMute(
    MLHandle handle,
    bool * out_is_muted
)

Queries the mute state of a sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.
bool *	out_is_muted	If true, the sound output is muted.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

API Level:

MLAudioSetSoundBypassesMasterVolume

MLResult MLAudioSetSoundBypassesMasterVolume(
    MLHandle handle,
    bool is_bypassing
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
bool	is_bypassing	Indicates whether the sound output should bypass master volume or not.

Returns


MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLResult_IncompatibleSKU	Failed due to feature not being supported on current device version.

Required Permissions:

None

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

API Level:

MLAudioGetSoundBypassesMasterVolume

MLResult MLAudioGetSoundBypassesMasterVolume(
    MLHandle handle,
    bool * out_is_bypassing
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
bool *	out_is_bypassing	Indicates whether the sound output is bypassing master volume or not.

Returns


MLResult	MLResult_Ok	Successfully queried the bypassing state of the sound output.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLResult_IncompatibleSKU	Failed due to feature not being supported on current device version.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.

Required Permissions:

None

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

API Level:

MLAudioSetSoundLooping

MLResult MLAudioSetSoundLooping(
    MLHandle handle,
    bool is_looping
)

Sets whether a sound output is looping or not.

Parameters


MLHandle	handle	MLHandle of the sound output.
bool	is_looping	Determines whether the sound output is looping or not.

Returns


MLResult	MLResult_Ok	Successfully set looping of audio.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioGetSoundLooping

MLResult MLAudioGetSoundLooping(
    MLHandle handle,
    bool * out_is_looping
)

Queries whether a sound output is looping or not.

Parameters


MLHandle	handle	MLHandle of the sound output.
bool *	out_is_looping	If true, the sound output state is looping.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

MLAudioSetStreamedFileOffset

MLResult MLAudioSetStreamedFileOffset(
    MLHandle handle,
    uint32_t offset_in_msec
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
uint32_t	offset_in_msec	The playback position in milliseconds the sound output will be set to.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

The playback position is in milliseconds and can be set regardless of the playback state.

MLAudioGetStreamedFileOffset

MLResult MLAudioGetStreamedFileOffset(
    MLHandle handle,
    uint32_t * out_offset_in_msec
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
uint32_t *	out_offset_in_msec	Retrieved playback position.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

The playback position is in milliseconds.

MLAudioGetOutputDevice

MLResult MLAudioGetOutputDevice(
    MLAudioOutputDevice * out_current_device
)

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

Parameters


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

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully indicated the type of output device.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

This is a global configuration that is not specific to individual sound outputs.

MLAudioSetOutputDeviceCallback

MLResult MLAudioSetOutputDeviceCallback(
    MLAudioOutputDeviceChangedCallback callback,
    void * context
)

Registers a callback for when the active audio hardware output has changed.

Parameters


MLAudioOutputDeviceChangedCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_Ok	Successfully registered the callback.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

API Level:

MLAudioResetAcousticScene

MLResult MLAudioResetAcousticScene()

Resets the Acoustic Scene.

Returns


MLResult	MLResult_Ok	Successfully reset the Acoustic Scene.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	No 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:

MLAudioBeginAcousticSceneUpdate

MLResult MLAudioBeginAcousticSceneUpdate()

Pauses the processing of changes to the Acoustic Scene.

Returns


MLResult	MLResult_Ok	Successfully began the Acoustic Scene update.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioEndAcousticSceneUpdate

MLResult MLAudioEndAcousticSceneUpdate()

Resumes the processing of changes to the Acoustic Scene.

Returns


MLResult	MLResult_Ok	Successfully ended the Acoustic Scene update.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	No 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:

MLAudioSetAcousticSceneMapEnable

MLResult MLAudioSetAcousticSceneMapEnable(
    bool is_enabled
)

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

Parameters


bool	is_enabled	If true, the Acoustic Map will be enabled.

Returns


MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioGetAcousticSceneMapEnable

MLResult MLAudioGetAcousticSceneMapEnable(
    bool * out_is_enabled
)

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

Parameters


bool *	out_is_enabled	If true, the Acoustic Map is enabled.

Returns


MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioSetAcousticSceneTransmissionDefault

MLResult MLAudioSetAcousticSceneTransmissionDefault(
    const MLAudioMultibandLevel * transmission
)

Sets the default attenuation applied to obstructed spatial sounds.

Parameters


const MLAudioMultibandLevel *	transmission	MLAudioMultibandLevel struct to set the default properties.

Returns


MLResult	MLResult_Ok	Successfully set the default properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioGetAcousticSceneTransmissionDefault

MLResult MLAudioGetAcousticSceneTransmissionDefault(
    MLAudioMultibandLevel * out_transmission
)

Queries the default attenuation applied to obstructed spatial sounds.

Parameters


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

Returns


MLResult	MLResult_Ok	Successfully retrieved the default properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioSetAcousticSceneDispersionDefault

MLResult MLAudioSetAcousticSceneDispersionDefault(
    const MLAudioDispersionProperties * properties
)

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

Parameters


const MLAudioDispersionProperties *	properties	MLAudioDispersionProperties struct to set the default properties.

Returns


MLResult	MLResult_Ok	Successfully set the default properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioGetAcousticSceneDispersionDefault

MLResult MLAudioGetAcousticSceneDispersionDefault(
    MLAudioDispersionProperties * out_properties
)

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

Parameters


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

Returns


MLResult	MLResult_Ok	Successfully retrieved the default properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioSetAcousticSceneReverbDefault

MLResult MLAudioSetAcousticSceneReverbDefault(
    const MLAudioReverbProperties * properties
)

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

Parameters


const MLAudioReverbProperties *	properties	MLAudioReverbProperties struct to set the properties.

Returns


MLResult	MLResult_Ok	Successfully set the default properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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.

API Level:

MLAudioGetAcousticSceneReverbDefault

MLResult MLAudioGetAcousticSceneReverbDefault(
    MLAudioReverbProperties * out_properties
)

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

Parameters


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

Returns


MLResult	MLResult_Ok	Successfully retrieved the default properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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.

API Level:

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_t	prev_map_tag	The map tag received in previous call.
uint8_t **	out_map_data	Retrieved pointer to serialized copy of Acoustic Map data if prev_map_tag != out_map_tag.
uint32_t *	out_map_size_in_bytes	Retrieved length of serialized Acoustic Map data in bytes.
uint32_t *	out_map_tag	Retrieved current map tag to be passed in subsequent call.

Returns


MLResult	MLResult_Ok	Successfully retrieved properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal 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:

MLAudioSetSpatialSoundEnable

MLResult MLAudioSetSpatialSoundEnable(
    MLHandle handle,
    bool is_enabled
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
bool	is_enabled	If true, spatial audio will be enabled for a sound output.

Returns


MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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


MLHandle	handle	MLHandle of the sound output.
bool *	out_is_enabled	If true, spatial audio is be enabled for a sound output.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLVec3f *	position	Struct to set the position.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLVec3f *	out_position	Struct to be filled with the position.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed 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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLQuaternionf *	direction	Struct to set the radiation direction.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed to set radiation direction due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed 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.

MLAudioGetSpatialSoundDirection

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

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

Parameters


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLQuaternionf *	out_direction	Struct to be filled with the radiation direction.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

MLAudioSetSpatialSoundBillboarding

MLResult MLAudioSetSpatialSoundBillboarding(
    MLHandle handle,
    bool is_billboarding
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
bool	is_billboarding	If true, billboarding will be enabled.

Returns


MLResult	MLResult_OK	Successfully set the value.
MLResult	MLAudioResult_HandleNotFound	Unable to find resource handle.
MLResult	MLAudioResult_OperationUnavailable	Operation 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:

MLAudioGetSpatialSoundBillboarding

MLResult MLAudioGetSpatialSoundBillboarding(
    MLHandle handle,
    bool * out_is_billboarding
)

Queries whether billboarding is enabled for a spatial sound.

Parameters


MLHandle	handle	MLHandle of the sound output.
bool *	out_is_billboarding	If true, billboarding is enabled.

Returns


MLResult	MLResult_OK	Successfully retrieved the value.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_OperationUnavailable	Operation is unavailable for this sound output.

Required Permissions:

None

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioObstruction *	left_ear	MLAudioObstruction struct to set the direct path obstruction properties for the left ear.
const MLAudioObstruction *	right_ear	MLAudioObstruction struct to set the direct path obstruction properties for the right ear.

Returns


MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_OperationUnavailable	Operation is unavailable for this sound output.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_InternalConfigError	Internal configuration error.
MLResult	MLAudioResult_NotImplemented	Internal 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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioObstruction *	out_left_ear	MLAudioObstruction struct to be filled with the obstruction properties for the left ear.
MLAudioObstruction *	out_right_ear	MLAudioObstruction struct to be filled with the obstruction properties for the right ear.

Returns


MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_OperationUnavailable	Operation is unavailable for this sound output.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal 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.

API Level:

MLAudioSetSpatialSoundObstructionOverride

MLResult MLAudioSetSpatialSoundObstructionOverride(
    MLHandle handle,
    const MLAudioMultibandLevel * override
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
const MLAudioMultibandLevel *	override	MLAudioMultibandLevel struct to set the override properties.

Returns


MLResult	MLResult_OK	Successfully set the properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLAudioResult_HandleNotFound	Unable to find resource handle.
MLResult	MLAudioResult_OperationUnavailable	Operation is unavailable for this sound output.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal 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:

MLAudioGetSpatialSoundObstructionOverride

MLResult MLAudioGetSpatialSoundObstructionOverride(
    MLHandle handle,
    MLAudioMultibandLevel * out_override
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
MLAudioMultibandLevel *	out_override	MLAudioMultibandLevel struct to be filled with the override properties.

Returns


MLResult	MLResult_OK	Successfully retrieved the properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLAudioResult_HandleNotFound	Unable to find resource handle.
MLResult	MLAudioResult_OperationUnavailable	Operation is unavailable for this sound output.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal 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:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioSpatialSoundDistanceProperties *	properties	MLAudioSpatialSoundDistanceProperties struct to set the properties.

Returns


MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioSpatialSoundDistanceProperties *	out_properties	MLAudioSpatialSoundDistanceProperties struct to be filled with the properties.

Returns


MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioSpatialSoundRadiationProperties *	properties	MLAudioSpatialSoundRadiationProperties struct to set the properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioSpatialSoundRadiationProperties *	out_properties	MLAudioSpatialSoundRadiationProperties struct to be filled with the properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioMultibandLevel *	level	MLAudioMultibandLevel struct to set the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioMultibandLevel *	out_level	MLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioMultibandLevel *	level	MLAudioMultibandLevel struct to set the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioMultibandLevel *	out_level	MLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioMultibandLevel *	level	MLAudioMultibandLevel struct to set the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

The 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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioMultibandLevel *	out_level	MLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
const MLAudioMultibandLevel *	level	MLAudioMultibandLevel struct to set the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
uint32_t	channel	Channel of the sound output.
MLAudioMultibandLevel *	out_level	MLAudioMultibandLevel struct to be filled with the gain and eq properties.

Returns


MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_HandleNotFound	Handle not found.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal error.

Required Permissions:

None

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.

API Level:

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


MLHandle	handle	MLHandle of the sound output.
bool	is_head_relative	If true, coordinates will be head-relative.

Returns


MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown failure.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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:

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


MLHandle	handle	MLHandle of the sound output.
bool *	out_is_head_relative	If true, coordinates are head-relative.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown failure.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

API Level:

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_requests	MLAudioRaycastRequest struct to be filled with requests for raycast operation.
uint32_t *	out_request_count	Value to be filled with number of raycast operations requested.

Returns


MLResult	MLResult_Ok	Successfully set the properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal 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:

MLAudioSetSpatialRaycastResults

MLResult MLAudioSetSpatialRaycastResults(
    MLAudioRaycastResult * raycast_results,
    uint32_t result_count
)

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

Parameters


MLAudioRaycastResult *	raycast_results	MLAudioRaycastResult struct to set the list of raycast operation results.
uint32_t	result_count	Sets the number of raycast results.

Returns


MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_InvalidParam	If input parameter is invalid.
MLResult	MLResult_UnspecifiedFailure	Internal error.
MLResult	MLAudioResult_InternalConfigError	Internal config error.
MLResult	MLAudioResult_NotImplemented	Internal 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:

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_t	channel_count	Number of audio channels.
uint32_t	samples_per_second	Sample rate for the buffered output.
float	max_pitch_change	Top pitch (1.0 - 2.0) for this sound output.
MLAudioBufferFormat *	out_format	MLAudioBufferFormat struct to be filled with recommended format properties.
uint32_t *	out_recommended_size_in_bytes	Retrieved recommended size.
uint32_t *	out_min_size_in_bytes	Retrieved minimum allowable size.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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:

MLAudioGetBufferedOutputLatency

MLResult MLAudioGetBufferedOutputLatency(
    MLHandle handle,
    float * out_latency_in_msec
)

Queries the latency for a buffered sound output.

Parameters


MLHandle	handle	MLHandle of the sound output.
float *	out_latency_in_msec	Retrieved latency in milliseconds.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed 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:

MLAudioGetBufferedOutputFramesPlayed

MLResult MLAudioGetBufferedOutputFramesPlayed(
    MLHandle handle,
    uint64_t * out_frames_played
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
uint64_t *	out_frames_played	Retrieved number of audio frames played.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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:

MLAudioGetOutputBuffer

MLResult MLAudioGetOutputBuffer(
    MLHandle handle,
    MLAudioBuffer * out_buf
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.
MLAudioBuffer *	out_buf	Retrieved MLAudioBuffer struct pointer to buffer for writing audio data.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the buffer.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_BufferNotReady	Failed because buffer was not ready.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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:

MLAudioReleaseOutputBuffer

MLResult MLAudioReleaseOutputBuffer(
    MLHandle handle
)

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

Parameters


MLHandle	handle	MLHandle of the sound output.

Returns


MLResult	MLResult_Ok	Successfully released the buffer.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_BufferNotReady	Failed because buffer was not ready.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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:

MLAudioGetMasterVolume

MLResult MLAudioGetMasterVolume(
    float * out_volume
)

Queries the master volume.

Parameters


float *	out_volume	Retrieved master volume.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because 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


MLAudioMasterVolumeChangedCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_Ok	Successfully registered the callback.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

MLAudioGetOutputMute

MLResult MLAudioGetOutputMute(
    bool * out_is_muted
)

Queries the state of the global output mute.

Parameters


bool *	bool	out_is_muted If true, global output is muted.

Returns


MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown failure.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

API Level:

MLAudioSetOutputMuteCallback

MLResult MLAudioSetOutputMuteCallback(
    MLAudioOutputMuteChangedCallback callback,
    void * context
)

Registers a callback for changes to the global output mute.

Parameters


MLAudioOutputMuteChangedCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_Ok	Successfully registered the callback.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

API Level:

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


MLAudioMicCaptureType	mic_capture_type	MLAudioMicCaptureType enum specifying the type of mic capture created.
const MLAudioBufferFormat *	format	MLAudioBufferFormat struct specifying the format properties.
uint32_t	buffer_size	Requested size in bytes for each of the two stream buffers.
MLAudioBufferCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created a sound input.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to an invalid bits per sample.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleFormat	Failed due to an invalid sample format.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidValidBits	Failed due to an invalid valid bits per sample.
MLResult	MLAudioResult_NotImplemented	Failed 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:

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 *	format	MLAudioBufferFormat struct specifying the format properties.
uint32_t	buffer_size	Requested size in bytes of the buffers.
MLAudioBufferCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound input.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to an invalid bits per sample.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleFormat	Failed due to an invalid sample format.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidValidBits	Failed due to an invalid valid bits per sample.
MLResult	MLAudioResult_NotImplemented	Failed 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.

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 *	format	MLAudioBufferFormat struct specifying the format properties.
uint32_t	buffer_size	Requested size in bytes of the buffers.
MLAudioBufferCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully created sound input.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_InvalidBitsPerSample	Failed due to an invalid bits per sample.
MLResult	MLAudioResult_InvalidBufferSize	Failed due to an invalid buffer size.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleFormat	Failed due to an invalid sample format.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_InvalidValidBits	Failed due to an invalid valid bits per sample.
MLResult	MLAudioResult_NotImplemented	Failed 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.

MLAudioDestroyInput

MLResult MLAudioDestroyInput(
    MLHandle handle
)

Destroys a sound input.

Parameters


MLHandle	handle	MLHandle of the sound input.

Returns


MLResult	MLResult_Ok	Successfully destroyed a sound input.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

MLAudioStartInput

MLResult MLAudioStartInput(
    MLHandle handle
)

Starts a sound input.

Parameters


MLHandle	handle	MLHandle of the sound input.

Returns


MLResult	MLResult_Ok	Sound input is started, or continues if already playing.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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

MLAudioStopInput

MLResult MLAudioStopInput(
    MLHandle handle
)

Stops a sound input.

Parameters


MLHandle	handle	MLHandle of the sound input.

Returns


MLResult	MLResult_Ok	Sound input is stopped, or remains stopped if already stopped.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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


MLHandle	handle	MLHandle of the sound input.
MLAudioState *	out_state	MLAudioState enum of the sound input.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

The 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_t	channel_count	Number of audio channels.
uint32_t	samples_per_second	Sample rate for the buffered input.
MLAudioBufferFormat *	out_format	MLAudioBufferFormat struct to be filled with recommended format properties.
uint32_t *	out_recommended_size_in_bytes	Retrieved recommended size.
uint32_t *	out_min_size_in_bytes	Retrieved minimum allowable size.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the properties.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InvalidChannelCount	Failed due to an invalid channel count.
MLResult	MLAudioResult_InvalidSampleRate	Failed due to an invalid sample rate.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.

Required Permissions:

None

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:

MLAudioGetBufferedInputLatency

MLResult MLAudioGetBufferedInputLatency(
    MLHandle handle,
    float * out_latency_in_msec
)

Queries the latency for a sound input.

Parameters


MLHandle	handle	MLHandle of the sound input.
float *	out_latency_in_msec	Retrieved latency in milliseconds.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed 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:

MLAudioGetInputBuffer

MLResult MLAudioGetInputBuffer(
    MLHandle handle,
    MLAudioBuffer * out_buf
)

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

Parameters


MLHandle	handle	MLHandle of the sound input.
MLAudioBuffer *	out_buf	Retrieved MLAudioBuffer struct pointer to buffer for reading audio data.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the buffer.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_BufferNotReady	Failed because buffer was not ready.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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:

MLAudioReleaseInputBuffer

MLResult MLAudioReleaseInputBuffer(
    MLHandle handle
)

Releases an input buffer once it has been consumed.

Parameters


MLHandle	handle	MLHandle of the sound input.

Returns


MLResult	MLResult_Ok	Successfully released the buffer.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_BufferNotReady	Failed because buffer was not ready.
MLResult	MLAudioResult_HandleNotFound	Failed due to a missing handle.
MLResult	MLAudioResult_InternalConfigError	Failed due to an internal configuration error.
MLResult	MLAudioResult_NotImplemented	Failed because feature has not been implemented yet.
MLResult	MLAudioResult_OperationUnavailable	Failed because operation is unavailable.

Required Permissions:

None

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:

MLAudioSetMicMute

MLResult MLAudioSetMicMute(
    bool is_muted
)

Sets the global input mute state for all input streams.

Parameters


bool	is_muted	If true, capture streams will be muted globally.

Returns


MLResult	MLResult_Ok	Successfully set the value.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed 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_muted	If true, capture streams are muted globally.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed 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:

MLAudioSetMicMuteCallback

MLResult MLAudioSetMicMuteCallback(
    MLAudioMicMuteCallback callback,
    void * context
)

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

Parameters


MLAudioMicMuteCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.

Returns


MLResult	MLResult_AllocFailed	Failed due to memory allocation failure.
MLResult	MLResult_Ok	Successfully registered the callback.
MLResult	MLResult_PermissionDenied	Failed due to lack of permission.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImplemented	Failed 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


MLAudioTraitAnalysisTarget	target	MLAudioTraitAnalysisTarget enum specifying the type of analysis requested.
MLAudioTraitAnalysisCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully began analysis.
MLResult	MLResult_UnspecifiedFailure	Failed 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:

MLAudioGetTraitAnalysis

MLResult MLAudioGetTraitAnalysis(
    MLHandle handle,
    float * out_value
)

Queries the current value of the trait analysis.

Parameters


MLHandle	handle	MLHandle of the analysis.
float *	out_value	Retrieved value of trait analysis.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved the value.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_NotImpelmented	return control frequencies because feature has not been implemented yet.

Required Permissions:

None

API Level:

MLAudioEndTraitAnalysis

MLResult MLAudioEndTraitAnalysis(
    MLHandle handle
)

Stops a trait analysis.

Parameters


MLHandle	handle	MLHandle of the analysis.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully ended analysis.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.

Required Permissions:

None

API Level:

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


MLAudioSpectralAnalysisTarget	target	MLAudioSpectralAnalysisTarget enum specifying type of analysis requested.
MLAudioSpectralAnalysisCallback	callback	Callback function pointer.
void *	context	Generic data pointer passed back through the callback.
MLHandle *	out_handle	MLHandle to be used in subsequent calls.

Returns


MLResult	MLResult_OK	Successfully began analysis.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_UnspecifiedFailure	Failed 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:

MLAudioGetSpectralAnalysis

MLResult MLAudioGetSpectralAnalysis(
    MLHandle handle,
    MLAudioSpectralAnalysis * out_values
)

Queries the current values of a spectral analysis.

Parameters


MLHandle	handle	MLHandle of the spectral analysis.
MLAudioSpectralAnalysis *	out_values	MLAudioSpectralAnalysis struct to be filled with the results properties.

Returns


MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_Ok	Successfully retrieved analysis.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.
MLResult	MLAudioResult_OperationUnavailable	Failed 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:

MLAudioEndSpectralAnalysis

MLResult MLAudioEndSpectralAnalysis(
    MLHandle handle
)

Stops a spectral analysis.

Parameters


MLHandle	handle	MLHandle of the spectral analysis.

Returns


MLResult	MLResult_OK	Successfully stopped analysis.
MLResult	MLResult_InvalidParam	Failed due to an invalid parameter.
MLResult	MLResult_UnspecifiedFailure	Failed due to an unknown error.

Required Permissions:

None

API Level:

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

ml_audio.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

MLAudioState​

MLAudioSoundEvent​

MLAudioMediaEvent​

MLAudioOutputDevice​

MLAudioMicCaptureType​

MLAudioSampleFormat​

MLAudioChannelFormat​

MLAudioTraitAnalysisTarget​

MLAudioSpectralAnalysisTarget​

Anonymous Enum 3​

MLAudioResult​

Types Documentation​

MLAudioMultibandLevel​

MLAudioDispersionProperties​

MLAudioReverbProperties​

MLAudioSpatialSoundDistanceProperties​

MLAudioSpatialSoundRadiationProperties​

MLAudioRaycast​

MLAudioObstruction​

MLAudioRaycastRequest​

MLAudioRaycastResult​

MLAudioBufferFormat​

MLAudioBuffer​

MLAudioSpectralAnalysis​

MLAudioSoundEventCallback​

MLAudioMediaEventCallback​

MLAudioBufferCallback​

MLAudioResourceDiscardedCallback​

MLAudioMasterVolumeChangedCallback​

MLAudioOutputMuteChangedCallback​

MLAudioOutputDeviceChangedCallback​

MLAudioMicMuteCallback​

MLAudioTraitAnalysisCallback​

MLAudioSpectralAnalysisCallback​

Functions Documentation​

MLAudioGetResultString​

MLAudioCreateLoadedResource​

MLAudioCreateStreamedResource​

MLAudioCheckResource​

MLAudioGetResourceSize​

MLAudioRefreshResource​

MLAudioDestroyResource​

MLAudioCreateSoundWithLoadedResource​

MLAudioCreateSoundWithStreamedResource​

MLAudioCreateSoundWithLoadedFile​

MLAudioCreateSoundWithStreamedFile​

MLAudioCreateSoundWithBufferedOutput​

MLAudioDestroySound​

MLAudioStartSound​

MLAudioStopSound​

MLAudioPauseSound​

MLAudioResumeSound​

MLAudioGetSoundState​

MLAudioGetSoundFormat​

MLAudioSetSoundEventCallback​

MLAudioSetMediaEventCallback​

MLAudioSetSoundVolumeLinear​

MLAudioGetSoundVolumeLinear​

MLAudioSetSoundVolumeDb​

MLAudioGetSoundVolumeDb​

MLAudioSetSoundPitch​

MLAudioGetSoundPitch​

MLAudioSetSoundMute​

MLAudioGetSoundMute​

MLAudioSetSoundBypassesMasterVolume​

MLAudioGetSoundBypassesMasterVolume​

MLAudioSetSoundLooping​

MLAudioGetSoundLooping​

MLAudioSetStreamedFileOffset​

MLAudioGetStreamedFileOffset​

MLAudioGetOutputDevice​

MLAudioSetOutputDeviceCallback​

MLAudioResetAcousticScene​

MLAudioBeginAcousticSceneUpdate​

Classes

Types

Enums

Functions

Enums Documentation

MLAudioState

MLAudioSoundEvent

MLAudioMediaEvent

MLAudioOutputDevice

MLAudioMicCaptureType

MLAudioSampleFormat

MLAudioChannelFormat

MLAudioTraitAnalysisTarget

MLAudioSpectralAnalysisTarget

Anonymous Enum 3

MLAudioResult

Types Documentation

MLAudioMultibandLevel

MLAudioDispersionProperties

MLAudioReverbProperties

MLAudioSpatialSoundDistanceProperties

MLAudioSpatialSoundRadiationProperties

MLAudioRaycast

MLAudioObstruction

MLAudioRaycastRequest

MLAudioRaycastResult

MLAudioBufferFormat

MLAudioBuffer

MLAudioSpectralAnalysis

MLAudioSoundEventCallback

MLAudioMediaEventCallback

MLAudioBufferCallback

MLAudioResourceDiscardedCallback

MLAudioMasterVolumeChangedCallback

MLAudioOutputMuteChangedCallback

MLAudioOutputDeviceChangedCallback

MLAudioMicMuteCallback

MLAudioTraitAnalysisCallback

MLAudioSpectralAnalysisCallback

Functions Documentation

MLAudioGetResultString

MLAudioCreateLoadedResource

MLAudioCreateStreamedResource

MLAudioCheckResource

MLAudioGetResourceSize

MLAudioRefreshResource

MLAudioDestroyResource

MLAudioCreateSoundWithLoadedResource

MLAudioCreateSoundWithStreamedResource

MLAudioCreateSoundWithLoadedFile

MLAudioCreateSoundWithStreamedFile

MLAudioCreateSoundWithBufferedOutput

MLAudioDestroySound

MLAudioStartSound

MLAudioStopSound

MLAudioPauseSound

MLAudioResumeSound

MLAudioGetSoundState

MLAudioGetSoundFormat

MLAudioSetSoundEventCallback

MLAudioSetMediaEventCallback

MLAudioSetSoundVolumeLinear

MLAudioGetSoundVolumeLinear

MLAudioSetSoundVolumeDb

MLAudioGetSoundVolumeDb

MLAudioSetSoundPitch

MLAudioGetSoundPitch

MLAudioSetSoundMute

MLAudioGetSoundMute

MLAudioSetSoundBypassesMasterVolume

MLAudioGetSoundBypassesMasterVolume

MLAudioSetSoundLooping

MLAudioGetSoundLooping

MLAudioSetStreamedFileOffset

MLAudioGetStreamedFileOffset

MLAudioGetOutputDevice

MLAudioSetOutputDeviceCallback

MLAudioResetAcousticScene

MLAudioBeginAcousticSceneUpdate

MLAudioEndAcousticSceneUpdate