ml_audio.h
Classes
Name | |
---|---|
struct | MLAudioMultibandLevel Properties specifying a broadband level and three sub-band levels. |
struct | MLAudioDispersionProperties |
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 |
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 audio resource data is being discarded to make room for other resource data. Resources that are not being referenced by a sound will be discarded before resources that are being referenced by a sound. Resources that are being played by a sound will not be discarded. |
typedef void()(float new_volume, void context) | MLAudioMasterVolumeChangedCallback Callback to notify when master volume has been changed. |
typedef void()(bool is_muted, void context) | MLAudioOutputMuteChangedCallback Callback to notify when the global Output Mute has changed. |
typedef void()(MLAudioOutputDevice current_device, void context) | MLAudioOutputDeviceChangedCallback Callback to notify when the output device has changed. |
typedef void()(bool is_muted, void context) | MLAudioMicMuteCallback Callback to notify when global mic mute has been changed. |
typedef void()(MLHandle handle, MLAudioTraitAnalysisTarget target, float value, void context) | MLAudioTraitAnalysisCallback Callback to provide a changed value for a running trait analysis. |
typedef void()(MLHandle handle, MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysis values, void context) | MLAudioSpectralAnalysisCallback Callback to provide a changed value for a running spectral analysis. |
Enums
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 audio 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) Checks whether an audio resource has been discarded due to memory limits. |
MLResult | MLAudioGetResourceSize(MLHandle resource, uint32_t * out_size_in_bytes) Returns the size of the memory footprint for a loaded audio resource. |
MLResult | MLAudioRefreshResource(MLHandle resource, int file) Refreshes an audio resource whose data was discarded due to memory limits. |
MLResult | MLAudioDestroyResource(MLHandle resource) Destroys a previously created audio resource. If there are sounds that are currently playing the resource, they will be stopped, and an event callback will be issued for MLAudioSoundEvent_ResourceDestroyed. |
MLResult | MLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle) Creates a new sound output that plays a loaded audio resource. |
MLResult | MLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle * out_handle) Creates a new sound output that plays a streamed audio resource. |
MLResult | MLAudioCreateSoundWithLoadedFile(int file, bool auto_destroy, bool dynamic_decode, MLHandle * out_handle) Creates a new sound output that plays a loaded file. |
MLResult | MLAudioCreateSoundWithStreamedFile(int file, bool auto_destroy, MLHandle * out_handle) Creates a new sound output that plays a streamed file. |
MLResult | MLAudioCreateSoundWithBufferedOutput(const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle) Creates a new sound output that plays a buffered audio output. |
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 sound output. |
MLResult | MLAudioResumeSound(MLHandle handle) Resumes playback for a sound output. |
MLResult | MLAudioGetSoundState(MLHandle handle, MLAudioState * out_state) Indicates the play state of a sound output. |
MLResult | MLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat * out_format) Returns the audio format of a sound output. |
MLResult | MLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void * context) Registers a callback for events on a sound output. |
MLResult | MLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void * context) Registers a callback for user-issued media control 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) Returns the volume of a sound output using 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) Returns the volume of a sound output using a decibel scale. |
MLResult | MLAudioSetSoundPitch(MLHandle handle, float pitch) Sets the pitch of a sound output. |
MLResult | MLAudioGetSoundPitch(MLHandle handle, float * out_pitch) Returns the pitch of a sound output. |
MLResult | MLAudioSetSoundMute(MLHandle handle, bool is_muted) Mutes or un-mutes a sound output. |
MLResult | MLAudioGetSoundMute(MLHandle handle, bool * out_is_muted) Returns whether a sound output is muted or not. |
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) Returns whether a sound output is looping or not. |
MLResult | MLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec) Sets the playback position for a streamed file. |
MLResult | MLAudioGetStreamedFileOffset(MLHandle handle, uint32_t * out_offset_in_msec) Returns the playback position for a streamed file. |
MLResult | MLAudioGetOutputDevice(MLAudioOutputDevice * out_current_device) Returns which type of sound output device is being used for sound output. |
MLResult | MLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void * context) Registers a callback for audio output device change. |
MLResult | MLAudioResetAcousticScene() Resets the Acoustic Scene associated with the caller. |
MLResult | MLAudioBeginAcousticSceneUpdate() Signals beginning of grouped Acoustic parameter multi-update. |
MLResult | MLAudioEndAcousticSceneUpdate() Signals end of grouped Acoustic parameter multi-update. |
MLResult | MLAudioSetAcousticSceneMapEnable(bool is_enabled) Enables/disables Acoustic Map data for the Acoustic Scene. |
MLResult | MLAudioGetAcousticSceneMapEnable(bool * out_is_enabled) Indicates whether Acoustic Map data is enabled for the Acoustic Scene. |
MLResult | MLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel * transmission) Sets amount of sound transmitted through non-Acoustic Element objects. |
MLResult | MLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel * out_transmission) Returns amount of sound transmitted through non-Acoustic Element objects. |
MLResult | MLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties * properties) Sets the fallback room properties to be used when none are otherwise specified. |
MLResult | MLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties * out_properties) Returns the default room properties used when none are otherwise specified. |
MLResult | MLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties * properties) Sets the fallback room properties to be used when none are otherwise specified. |
MLResult | MLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties * out_properties) Returns the default room properties used when none are otherwise specified. |
MLResult | MLAudioGetChangedAcousticMap(uint32_t prev_map_tag, uint8_t * out_map_data, uint32_t out_map_size_in_bytes, uint32_t * out_map_tag) Returns the Acoustic Map if updated since previous call. |
MLResult | MLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled) Enables/disables 3D audio processing for a sound output. |
MLResult | MLAudioGetSpatialSoundEnable(MLHandle handle, bool * out_is_enabled) Indicates whether 3D audio processing is enabled for a sound output. |
MLResult | MLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f * position) Sets the 3D position for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f * out_position) Returns the 3D position for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf * direction) Sets the radiation direction for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf * out_direction) Returns the radiation direction for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundBillboarding(MLHandle id, bool is_billboarding) Sets a mode where the sound always faces the listener. |
MLResult | MLAudioGetSpatialSoundBillboarding(MLHandle id, bool * out_is_billboarding) Indicates whether the sound automatically faces the listener. |
MLResult | MLAudioSetSpatialSoundObstruction(MLHandle id, uint32_t channel, const MLAudioObstruction left_ear, const MLAudioObstruction right_ear) Sets the direct path obstruction for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundObstruction(MLHandle id, uint32_t channel, MLAudioObstruction out_left_ear, MLAudioObstruction out_right_ear) Returns the direct path obstruction for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundObstructionOverride(MLHandle id, const MLAudioMultibandLevel * override) Sets an override that enables the sound to pass through obstructions. |
MLResult | MLAudioGetSpatialSoundObstructionOverride(MLHandle id, MLAudioMultibandLevel * out_override) Returns the amount of the sound obstruction override. |
MLResult | MLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties * properties) Sets the distance properties for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties * out_properties) Returns the distance properties for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundRadiation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundRadiationProperties * properties) Sets the radiation properties for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundRadiation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundRadiationProperties * out_properties) Returns the radiation properties for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the direct sound level for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Returns the direct sound level for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the indirect sound level for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Returns the indirect sound level for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the dispersion level for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Returns the dispersion level for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel * level) Sets the reverb level for one channel of a sound output. |
MLResult | MLAudioGetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel * out_level) Returns the reverb level for one channel of a sound output. |
MLResult | MLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative) Sets whether the coordinates for a sound output are head relative. |
MLResult | MLAudioGetSpatialSoundHeadRelative(MLHandle handle, bool * out_is_head_relative) Returns whether the coordinates for a sound output are head relative. |
MLResult | MLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest * out_raycast_requests, uint32_t out_request_count) Returns 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) Returns the preferred (i.e. best performing) settings for buffered output. |
MLResult | MLAudioGetBufferedOutputLatency(MLHandle handle, float * out_latency_in_msec) Returns the latency for a buffered output. |
MLResult | MLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t * out_frames_played) Returns the number of audio frames played by a buffered output. |
MLResult | MLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer * out_buf) Returns an empty buffer for writing more buffered data. |
MLResult | MLAudioReleaseOutputBuffer(MLHandle handle) Releases a buffer once it has been filled. |
MLResult | MLAudioGetMasterVolume(float * out_volume) Returns the master volume for the audio system. |
MLResult | MLAudioSetMasterVolumeCallback(MLAudioMasterVolumeChangedCallback callback, void * context) Registers a callback for changes to the master volume. |
MLResult | MLAudioGetOutputMute(bool * out_is_muted) Indicates whether the output mute of the audio system is on or off. |
MLResult | MLAudioSetOutputMuteCallback(MLAudioOutputMuteChangedCallback callback, void * context) Registers a callback for audio output mute change. |
MLResult | MLAudioCreateInputFromMicCapture(MLAudioMicCaptureType mic_capture_type, const MLAudioBufferFormat format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void context, MLHandle * out_handle) Creates a new sound input that provides audio from the mics on the wearable. |
MLResult | MLAudioCreateInputFromVirtualCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void callback_context, MLHandle * out_handle) Creates a new sound input that provides a "virtual capture" stream. |
MLResult | MLAudioCreateInputFromMixedCapture(const MLAudioBufferFormat format, uint32_t buffer_size, MLAudioBufferCallback callback, void callback_context, MLHandle * out_handle) Creates a new sound input that provides a "mixed capture" stream. |
MLResult | MLAudioDestroyInput(MLHandle handle) Destroys a previously created sound input. |
MLResult | MLAudioStartInput(MLHandle handle) Starts capture for a sound input. |
MLResult | MLAudioStopInput(MLHandle handle) Stops capture for a sound input. |
MLResult | MLAudioGetInputState(MLHandle handle, MLAudioState * out_state) Indicates the play 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) Returns the preferred (i.e. best performing) settings for buffered input. |
MLResult | MLAudioGetBufferedInputLatency(MLHandle handle, float * out_latency_in_msec) Returns the latency for a sound input. |
MLResult | MLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer * out_buf) Returns a full buffer containing captured audio data. |
MLResult | MLAudioReleaseInputBuffer(MLHandle handle) Releases a buffer once it has been read. |
MLResult | MLAudioSetMicMute(bool is_muted) Mutes or un-mutes all microphone capture. |
MLResult | MLAudioGetMicMute(bool * out_is_muted) Returns whether all microphone capture is muted or not. |
MLResult | MLAudioSetMicMuteCallback(MLAudioMicMuteCallback callback, void * context) Registers a callback for changes to the global mic mute. |
MLResult | MLAudioBeginTraitAnalysisFromMicCapture(MLAudioTraitAnalysisTarget target, MLAudioTraitAnalysisCallback callback, void callback_context, MLHandle out_handle) Creates a new analysis input for the specified target. |
MLResult | MLAudioGetTraitAnalysis(MLHandle handle, float * out_value) Returns the current value of the trait analysis associated with the specified handle. |
MLResult | MLAudioEndTraitAnalysis(MLHandle handle) Stops a previously started trait analysis. |
MLResult | MLAudioBeginSpectralAnalysisFromMicCapture(MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysisCallback callback, void callback_context, MLHandle out_handle) Starts a new spectral analysis that provides frequency spectrum energy derived from mic signals. |
MLResult | MLAudioGetSpectralAnalysis(MLHandle handle, MLAudioSpectralAnalysis * out_values) Returns the current value of the spectral analysis associated with the specified handle. |
MLResult | MLAudioEndSpectralAnalysis(MLHandle handle) Stops a previously started 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 is looping. | |
MLAudioSoundEvent_MutedBySystem | A sound output has been selectively 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 selectively 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:
- 29
MLAudioSampleFormat
Enumerator | Value | Description |
---|---|---|
MLAudioSampleFormat_Int | Samples are integer. | |
MLAudioSampleFormat_Float | Samples are float. Not currently implemented. | |
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, specified in MLAudioBufferFormat reserved field.
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, 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 Third 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:
- 4
Types Documentation
MLAudioMultibandLevel
typedef struct MLAudioMultibandLevel MLAudioMultibandLevel;
Properties specifying a broadband level and three sub-band levels.
API Level:
- 20
MLAudioDispersionProperties
typedef struct MLAudioDispersionProperties MLAudioDispersionProperties;
\briefProperties specifying acoustic dispersion (clustered reflections).
API Level:
- 20
MLAudioReverbProperties
typedef struct MLAudioReverbProperties MLAudioReverbProperties;
Properties specifying acoustic reverberation.
API Level:
- 20
MLAudioSpatialSoundDistanceProperties
typedef struct MLAudioSpatialSoundDistanceProperties MLAudioSpatialSoundDistanceProperties;
Properties specifying the distance response of a spatial sound.
MLAudioSpatialSoundRadiationProperties
typedef struct MLAudioSpatialSoundRadiationProperties MLAudioSpatialSoundRadiationProperties;
Properties specifying the directivity of a spatial sound.
MLAudioRaycast
typedef struct MLAudioRaycast MLAudioRaycast;
Two points in space describing a ray.
API Level:
- 20
MLAudioObstruction
typedef struct MLAudioObstruction MLAudioObstruction;
Obstruction along a ray.
API Level:
- 20
MLAudioRaycastRequest
typedef struct MLAudioRaycastRequest MLAudioRaycastRequest;
ID-tracked request for a single raycast operation.
API Level:
- 20
MLAudioRaycastResult
typedef struct MLAudioRaycastResult MLAudioRaycastResult;
ID-tracked result for a single raycast operation.
API Level:
- 20
MLAudioBufferFormat
typedef struct MLAudioBufferFormat MLAudioBufferFormat;
Buffer format settings for input and output streams.
API Level:
- 20
MLAudioBuffer
typedef struct MLAudioBuffer MLAudioBuffer;
An audio buffer for passing data from input streams or to output streams.
MLAudioSpectralAnalysis
typedef struct MLAudioSpectralAnalysis MLAudioSpectralAnalysis;
A representation of frequency spectrum energy over a window of time.
MLAudioSoundEventCallback
typedef void(* MLAudioSoundEventCallback) (MLHandle handle, MLAudioSoundEvent event, void *context);
Callback to notify when a sound event has occurred.
The callback will be called on a separate thread.
MLAudioMediaEventCallback
typedef void(* MLAudioMediaEventCallback) (MLAudioMediaEvent event, void *context);
Callback to notify when a media event has occurred.
The callback will be called on a separate thread.
MLAudioBufferCallback
typedef void(* MLAudioBufferCallback) (MLHandle handle, void *context);
Callback to notify when an audio buffer is available for reading or writing.
The callback will be called on a separate thread.
MLAudioResourceDiscardedCallback
typedef void(* MLAudioResourceDiscardedCallback) (MLHandle resource, void *context);
Callback to notify when audio resource data is being discarded to make room for other resource data. Resources that are not being referenced by a sound will be discarded before resources that are being referenced by a sound. Resources that are being played by a sound will not be discarded.
- The callback will be called on a separate thread.
- The audio data should not be refreshed until needed again.
MLAudioMasterVolumeChangedCallback
typedef void(* MLAudioMasterVolumeChangedCallback) (float new_volume, void *context);
Callback to notify when master volume has been changed.
The callback will be called on a separate thread.
MLAudioOutputMuteChangedCallback
typedef void(* MLAudioOutputMuteChangedCallback) (bool is_muted, void *context);
Callback to notify when the global Output Mute has changed.
- The global Output Mute is changed by using voice commands or a bluetooth keyboard with a mute/unmute button.
- The callback will be called on a separate thread.
MLAudioOutputDeviceChangedCallback
typedef void(* MLAudioOutputDeviceChangedCallback) (MLAudioOutputDevice current_device, void *context);
Callback to notify when the output device has changed.
The callback will be called on a separate thread.
MLAudioMicMuteCallback
typedef void(* MLAudioMicMuteCallback) (bool is_muted, void *context);
Callback to notify when global mic mute has been changed.
The callback will be called on a separate thread.
MLAudioTraitAnalysisCallback
typedef void(* MLAudioTraitAnalysisCallback) (MLHandle handle, MLAudioTraitAnalysisTarget target, float value, void *context);
Callback to provide a changed value for a running trait analysis.
The callback will be called on a separate thread.
MLAudioSpectralAnalysisCallback
typedef void(* MLAudioSpectralAnalysisCallback) (MLHandle handle, MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysis values, void *context);
Callback to provide a changed value for a running spectral analysis.
The callback will be called on a separate thread.
Functions Documentation
MLAudioGetResultString
const char * MLAudioGetResultString(
MLResult result_code
)
Returns an ASCII string for each result code.
Parameters
MLResult | result_code | MLResult to select the result code. |
This call returns strings for all of the MLResult and MLAudioResult codes.
Return: ASCII string containing readable version of result code.
MLAudioCreateLoadedResource
MLResult MLAudioCreateLoadedResource(
int file,
bool dynamic_decode,
MLAudioResourceDiscardedCallback callback,
void * context,
MLHandle * out_resource
)
Creates a new audio resource that references a loaded audio file.
Parameters
int | file | File descriptor specifying the file to load. |
bool | dynamic_decode | Not currently implemented. |
MLAudioResourceDiscardedCallback | callback | MLAudioResourceDiscardedCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
MLHandle * | out_resource | MLHandle used in subsequent calls for this resource. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully created new audio 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 configurations 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
Creates a new audio resource that references the audio file specified by the 'file' argument, which it tries to load during resource creation. An optional MLAudioResourceDiscardedCallback will inform the client if the data later gets discarded due to memory limits (or if it fails to load during creation). After creation the resource can be played by passing its id to MLAudioCreateSoundWithLoadedResource.
MLAudioCreateStreamedResource
MLResult MLAudioCreateStreamedResource(
int file,
MLAudioResourceDiscardedCallback callback,
void * context,
MLHandle * out_resource
)
Creates a new audio resource that references a streamed audio file.
Parameters
int | file | File descriptor specifying the file to load. |
MLAudioResourceDiscardedCallback | callback | MLAudioResourceDiscardedCallback Function pointer. |
void * | context | Generic data pointer passed back to callback. |
MLHandle * | out_resource | MLHandle used in subsequent calls for this resource. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully created new audio resource. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_NotImplemented | Failed because of feature has not been implemented yet. |
Required Permissions:
- None
Creates a new audio resource that references the audio file specified by the 'file' argument. An optional MLAudioResourceDiscardedCallback will inform the client if the file's file descriptor later gets discarded due to file descriptor limits (or if a file descriptor cannot be generated during resource creation). After creation the resource can be played by passing its id to MLAudioCreateSoundWithStreamedResource.
MLAudioCheckResource
MLResult MLAudioCheckResource(
MLHandle resource,
bool * out_is_ready
)
Checks whether an audio resource has been discarded due to memory limits.
Parameters
MLHandle | resource | MLHandle used to identify the resource. |
bool * | out_is_ready | Indicates whether the resource is ready or not. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully checked audio resource. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_NotImplemented | Failed because of feature has not been implemented yet. |
MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
This call can be used instead of the MLAudioResourceDiscardedCallback to determine whether an audio resource has been discarded. Resources that are not being referenced by a sound will be discarded before resources that are being referenced by a sound. Resources that are being played by a sound will not be discarded. MLAudioCheckResource can be called just before the resource is needed, or at some other appropriate time for accessing data. However it should not be called constantly on a polling basis to instantly refresh resources that get discarded, since that would defeat the purpose of the memory limit.
MLAudioGetResourceSize
MLResult MLAudioGetResourceSize(
MLHandle resource,
uint32_t * out_size_in_bytes
)
Returns the size of the memory footprint for a loaded audio resource.
Parameters
MLHandle | resource | MLHandle used to identify the resource. |
uint32_t * | out_size_in_bytes | The returned size of the footprint. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully obtained resource size. |
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
This call tells the owner of a loaded resource what size memory footprint is used by the resource. For a loaded resource that is de-compressed when it gets loaded into memory, the value returned will be the de-compressed size. For a loaded resource that stays compressed when loaded, and gets decoded on the fly (not yet implemented), the value returned will be the compressed size. This call always returns the size of the resource's footprint, even when the resource is temporarily discarded and is using no memory. To determine if the size returned is actually being used in memory, call MLAudioCheckResource to find out if the resource is currently discarded. This call will return with an error if it is called for a streamed resource.
API Level:
- 7
MLAudioRefreshResource
MLResult MLAudioRefreshResource(
MLHandle resource,
int file
)
Refreshes an audio resource whose data was discarded due to memory limits.
Parameters
MLHandle | resource | MLHandle used to identify the resource. |
int | file | File descriptor specifying the audio data to refresh. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully refreshed audio 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 configurations 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
This call allows the client to 'refresh' a resource whose data has been discarded. This should be done just prior to the next time the data is needed, or some other convenient time when data access is appropriate, but not right after the data is discarded, as that would defeat the purpose of the memory limit.
MLAudioDestroyResource
MLResult MLAudioDestroyResource(
MLHandle resource
)
Destroys a previously created audio resource. If there are sounds that are currently playing the resource, they will be stopped, and an event callback will be issued for MLAudioSoundEvent_ResourceDestroyed.
Parameters
MLHandle | resource | MLHandle used to identify the resource. |
Returns
MLResult | MLResult_Ok | Successfully destroyed audio 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
MLAudioCreateSoundWithLoadedResource
MLResult MLAudioCreateSoundWithLoadedResource(
MLHandle resource,
bool auto_destroy,
MLHandle * out_handle
)
Creates a new sound output that plays a loaded audio resource.
Parameters
MLHandle | resource | MLHandle specifying the resource to play. |
bool | auto_destroy | If true, the sound output is destroyed when done playing. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound output. |
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 configurations 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
Creates a sound output to play a loaded audio file referenced as a resource. Loaded resources are created and loaded by calling MLAudioCreateLoadedResource. After sound creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.
MLAudioCreateSoundWithStreamedResource
MLResult MLAudioCreateSoundWithStreamedResource(
MLHandle resource,
bool auto_destroy,
MLHandle * out_handle
)
Creates a new sound output that plays a streamed audio resource.
Parameters
MLHandle | resource | MLHandle specifying the resource to play. |
bool | auto_destroy | If true, the sound output is destroyed when done playing. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound output. |
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 configurations 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
Creates a sound output to play a streamed audio file referenced as a resource. Streamed resources are created by calling MLAudioCreateStreamedResource. After sound creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.
MLAudioCreateSoundWithLoadedFile
MLResult MLAudioCreateSoundWithLoadedFile(
int file,
bool auto_destroy,
bool dynamic_decode,
MLHandle * out_handle
)
Creates a new sound output that plays a loaded file.
Parameters
int | file | File descriptor specifying the file to play. |
bool | auto_destroy | If true, the sound output is destroyed when done playing. |
bool | dynamic_decode | Not currently implemented. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound output. |
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 configurations 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
Creates a sound output and loads the audio file specified by the 'file' argument into memory. After creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.
MLAudioCreateSoundWithStreamedFile
MLResult MLAudioCreateSoundWithStreamedFile(
int file,
bool auto_destroy,
MLHandle * out_handle
)
Creates a new sound output that plays a streamed file.
Parameters
int | file | File descriptor specifying the file to play. |
bool | auto_destroy | If true, the sound output is destroyed when done playing. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound output. |
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 configurations error. |
MLResult | MLAudioResult_ResourceDiscarded | Failed because file was closed. |
MLResult | MLAudioResult_ResourceNotFound | Failed because resource was not found. |
Required Permissions:
- None
Creates a sound output and prepares to stream the audio file specified by the 'file' argument. After creation the sound can be started by calling MLAudioStartSound. Supported file formats are all file types supported by the Multimedia Service, mono or stereo, sampled with a frequency in the range from 16 kHz - 48 kHz, and represented as 16, 24, or 32 bit integers or 32-bit floats.
MLAudioCreateSoundWithBufferedOutput
MLResult MLAudioCreateSoundWithBufferedOutput(
const MLAudioBufferFormat * format,
uint32_t buffer_size_in_bytes,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)
Creates a new sound output that plays a buffered audio output.
Parameters
const MLAudioBufferFormat * | format | MLAudioBufferFormat Specifying the audio format of the buffers. |
uint32_t | buffer_size_in_bytes | Requested size in bytes for each of the output buffers. |
MLAudioBufferCallback | callback | MLAudioBufferCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound output. |
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 configurations 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
Creates a sound output and allocates a double-buffer for buffering audio data into it. To write data into the next available buffer call MLAudioGetOutputBuffer to get an empty buffer, then write the data into the buffer, then call MLAudioReleaseOutputBuffer to indicate that the buffer is ready to play. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument specifies the format of which the following are supported: Mono, stereo, 6-channel, 8-channel, or 12-channel; 16 bit integer; a sampling rate between 16k - 48k. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, one or both buffers can optionally be pre-filled, and the sound can be started by calling MLAudioStartSound.
API Level:
- 7
MLAudioDestroySound
MLResult MLAudioDestroySound(
MLHandle handle
)
Destroys a previously created sound output.
Parameters
MLHandle | handle | MLHandle used to identify 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 used to identify the sound output. |
Returns
MLResult | MLResult_Ok | Successfully started playback. |
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
When starting playback for a file (loaded, streamed, system sound), playback starts at the beginning of the file (even after a pause). When starting playback for an output stream, the "frames played" counter gets reset to zero (and if the output stream was previously paused the streaming buffers get reset as well).
MLAudioStopSound
MLResult MLAudioStopSound(
MLHandle handle
)
Stops playback for a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
Returns
MLResult | MLResult_Ok | Successfully stopped playback. |
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
Stops playback for a sound output that's playing or paused.
MLAudioPauseSound
MLResult MLAudioPauseSound(
MLHandle handle
)
Pauses playback for a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
Returns
MLResult | MLResult_Ok | Successfully paused playback. |
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
Pauses playback for a sound output that's playing. If the sound output is not playing, the pause will fail.
MLAudioResumeSound
MLResult MLAudioResumeSound(
MLHandle handle
)
Resumes playback for a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
Returns
MLResult | MLResult_Ok | Successfully resumed playback. |
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
Resumes playback for a sound output that's paused. If the sound output is not paused, the resume will fail.
MLAudioGetSoundState
MLResult MLAudioGetSoundState(
MLHandle handle,
MLAudioState * out_state
)
Indicates the play state of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
MLAudioState * | out_state | Indicates the current play state. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully indicated the state of sound output. |
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 indicates whether the sound output is stopped, playing or paused.
MLAudioGetSoundFormat
MLResult MLAudioGetSoundFormat(
MLHandle handle,
MLAudioBufferFormat * out_format
)
Returns the audio format of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
MLAudioBufferFormat * | out_format | MLAudioBufferFormat struct containing the format info. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned audio format. |
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 returned information includes the channel count, sample rate and bit depth of the sound's audio data. For Streamed Files, the format is not available until about 100+ milliseconds after playback of the Streamed File is started.
MLAudioSetSoundEventCallback
MLResult MLAudioSetSoundEventCallback(
MLHandle handle,
MLAudioSoundEventCallback callback,
void * context
)
Registers a callback for events on a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
MLAudioSoundEventCallback | callback | MLAudioSoundEventCallback function pointer. |
void * | context | Generic data pointer passed back to 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 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Events that can result in a callback being called include: Stopping at the end of a file; looping at the end of a file; a sound output having its volume lowered or restored by the audio policy manager; a sound output being muted or unmuted by the audio policy manager. The 'context' argument is passed back to the callback, along with the particular event type (MLAudioSoundEvent) that caused the callback.
API Level:
- 20
MLAudioSetMediaEventCallback
MLResult MLAudioSetMediaEventCallback(
MLAudioMediaEventCallback callback,
void * context
)
Registers a callback for user-issued media control events.
Parameters
MLAudioMediaEventCallback | callback | MLAudioMediaEventCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
Returns
MLResult | MLResult_AllocFailed | If memory allocation fails. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
Events that can result in a callback being called include: Pressing a play button; pressing a stop button; pressing a pause button; pressing a next track button, pressing a previous track button; The particular event type (MLAudioMediaEvent) that caused the callback is passed to the callback as its first argument.The 'context' argument is passed back to the callback as its second argument.
API Level:
- 20
MLAudioSetSoundVolumeLinear
MLResult MLAudioSetSoundVolumeLinear(
MLHandle handle,
float volume
)
Sets the volume of a sound output using a linear scale.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float | volume | The volume that the sound output will be set to. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set volume of 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of the volume is 0 to 8, with 0 for silence, 1 for unity gain, and 8 for 8x gain.
MLAudioGetSoundVolumeLinear
MLResult MLAudioGetSoundVolumeLinear(
MLHandle handle,
float * out_volume
)
Returns the volume of a sound output using a linear scale.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float * | out_volume | The volume that the sound output is set to. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned volume of 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of the volume is 0 to 8, with 0 for silence, 1 for unity gain, and 8 for 8x gain.
MLAudioSetSoundVolumeDb
MLResult MLAudioSetSoundVolumeDb(
MLHandle handle,
float volume
)
Sets the volume of a sound output using a decibel scale.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float | volume | The volume that the sound output will be set to. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set volume. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of the volume is -100 db to +18 dB, with -100 dB for silence, 0 dB for unity gain, and +18 dB for 8x gain.
MLAudioGetSoundVolumeDb
MLResult MLAudioGetSoundVolumeDb(
MLHandle handle,
float * out_volume
)
Returns the volume of a sound output using a decibel scale.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float * | out_volume | The volume that the sound output is set to. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned volume. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of the volume is -100 db to +18 dB, with -100 dB for silence, 0 dB for unity gain, and +18 dB for 8x gain.
MLAudioSetSoundPitch
MLResult MLAudioSetSoundPitch(
MLHandle handle,
float pitch
)
Sets the pitch of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float | pitch | The pitch that the sound output will be set to. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set pitch of 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 configurations 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 the pitch is 0.5 to 2.0, with 0.5 being one octave down and 2.0 being one octave up (i.e., the pitch is a frequency multiple). A pitch of 1.0 is the default and means no change.
MLAudioGetSoundPitch
MLResult MLAudioGetSoundPitch(
MLHandle handle,
float * out_pitch
)
Returns the pitch of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float * | out_pitch | The pitch that the sound output is set to. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned pitch of 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The range of the pitch is 0.5 to 2.0, with 0.5 being one octave down and 2.0 being one octave up (i.e., the pitch is a frequency multiple). A pitch of 1.0 is the default and means no change.
MLAudioSetSoundMute
MLResult MLAudioSetSoundMute(
MLHandle handle,
bool is_muted
)
Mutes or un-mutes a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
bool | is_muted | Determines whether the sound output is muted or not. |
Returns
MLResult | MLResult_Ok | Successfully muted or unmuted sound output. |
MLResult | MLResult_UnspecifiedFailure | Failed sound due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed sound due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed sound due to an internal configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed sound because feature has not been implemented yet. |
Required Permissions:
- None
This mute control is entirely under the control of the owner of the sound output, and is separate from any muting done by the audio policy manager.
MLAudioGetSoundMute
MLResult MLAudioGetSoundMute(
MLHandle handle,
bool * out_is_muted
)
Returns whether a sound output is muted or not.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
bool * | out_is_muted | Indicates whether the sound output is muted or not. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully obtained mute state of 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
This mute control is entirely under the control of the owner of the sound output, and will not indicate whether the sound output has been muted by the audio policy manager. To find out about the latter, use MLAudioSetSoundEventCallback to register a callback that will provide "policy mute" events.
API Level:
- 20
MLAudioSetSoundBypassesMasterVolume
MLResult MLAudioSetSoundBypassesMasterVolume(
MLHandle handle,
bool is_bypassing
)
Sets whether a sound output is exempt from attenuation due to master volume.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
bool | is_bypassing | Sets whether the sound output should bypass master volume or not. |
Returns
MLResult | MLResult_Ok | Successfully set the bypassing state of the sound output. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLResult_IncompatibleSKU | Failed due to feature not 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
Setting this option on a sound output causes its output to bypass master volume, making it effectively "always audible" (assuming it is neither muted nor set to zero volume on a per-sound basis). This option is available only on certain SKUs; trying to set it when the device is not compatible will produce an error as listed below. In addition, this option only works when a sound is non-spatial; the non-spatial sound parameters volume, pitch, etc remain active for sounds that are bypassing master volume.
API Level:
- 20
MLAudioGetSoundBypassesMasterVolume
MLResult MLAudioGetSoundBypassesMasterVolume(
MLHandle handle,
bool * out_is_bypassing
)
Queries whether a sound output is exempt from attenuation due to master volume.
Parameters
MLHandle | handle | MLHandle used to identify 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 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 reports whether a sound output is bypassing master volume, making it effectively "always audible" (assuming it is neither muted nor set to zero volume on a per-sound basis). This option is available only on certain SKUs; trying to query it when the device is not compatible will produce an error as listed below. In addition, this option only works when a sound is non-spatial; the non-spatial sound parameters volume, pitch, etc remain active for sounds that are bypassing master volume.
API Level:
- 20
MLAudioSetSoundLooping
MLResult MLAudioSetSoundLooping(
MLHandle handle,
bool is_looping
)
Sets whether a sound output is looping or not.
Parameters
MLHandle | handle | MLHandle used to identify 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 play files (loaded, streamed, system sounds). The loop goes from the very beginning to the very end of the file. Looping does not apply to sound outputs that are output streams.
MLAudioGetSoundLooping
MLResult MLAudioGetSoundLooping(
MLHandle handle,
bool * out_is_looping
)
Returns whether a sound output is looping or not.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
bool * | out_is_looping | Indicates whether the sound output is looping or not. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully obtained looping state of sound output. |
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
API Level:
- 20
MLAudioSetStreamedFileOffset
MLResult MLAudioSetStreamedFileOffset(
MLHandle handle,
uint32_t offset_in_msec
)
Sets the playback position for a streamed file.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | offset_in_msec | Sets the new playback position. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set playback position. |
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
This function will cause a streaming file to jump to a new location. The playback position is specified in milliseconds. This function can be used while a streaming file is playing, paused or stopped.
MLAudioGetStreamedFileOffset
MLResult MLAudioGetStreamedFileOffset(
MLHandle handle,
uint32_t * out_offset_in_msec
)
Returns the playback position for a streamed file.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t * | out_offset_in_msec | Indicates the current playback position. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned playback position for streamed file. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
This function can be used while a streaming file is playing, paused or stopped.
MLAudioGetOutputDevice
MLResult MLAudioGetOutputDevice(
MLAudioOutputDevice * out_current_device
)
Returns which type of sound output device is being used for sound output.
Parameters
MLAudioOutputDevice * | out_current_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 audio output device change.
Parameters
MLAudioOutputDeviceChangedCallback | callback | MLAudioOutputDeviceChangedCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_Ok | Successfully registered callback. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The callback will be called whenever the output device changes. The current output device is passed back to the callback as its first argument, and the 'context' argument is passed to the callback as its second argument.
API Level:
- 8
MLAudioResetAcousticScene
MLResult MLAudioResetAcousticScene()
Resets the Acoustic Scene associated with the caller.
Returns
MLResult | MLResult_Ok | If reset was successful. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | No custom scene exists for client. |
Required Permissions:
- None
Removes all Acoustic Elements and restores default scene. Resets any modifications to the acoustic scene previously made by the caller.
API Level:
- 20
MLAudioBeginAcousticSceneUpdate
MLResult MLAudioBeginAcousticSceneUpdate()
Signals beginning of grouped Acoustic parameter multi-update.
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The multi-update parameters include global Acoustic Scene params and Acoustic Element params. Intended to be followed by a call to MLAcousticEndAcousticSceneUpdate signifying the end of the multi-update.
API Level:
- 20
MLAudioEndAcousticSceneUpdate
MLResult MLAudioEndAcousticSceneUpdate()
Signals end of grouped Acoustic parameter multi-update.
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_HandleNotFound | No custom scene exists for client. |
Required Permissions:
- None
The multi-update parameters include global Acoustic Scene params and Acoustic Element params. Intended to be preceded by a call to MLAcousticBeginAcousticSceneUpdate signifying the beginning of the multi-update.
API Level:
- 20
MLAudioSetAcousticSceneMapEnable
MLResult MLAudioSetAcousticSceneMapEnable(
bool is_enabled
)
Enables/disables Acoustic Map data for the Acoustic Scene.
Parameters
bool | is_enabled | Determines whether Acoustic Map is enabled. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Acoustic Map data is a device-curated representation of the acoustics of the local physical environment. Enabling the Acoustic Map makes virtual objects sound as though they exist in the local environment.
API Level:
- 20
MLAudioGetAcousticSceneMapEnable
MLResult MLAudioGetAcousticSceneMapEnable(
bool * out_is_enabled
)
Indicates whether Acoustic Map data is enabled for the Acoustic Scene.
Parameters
bool * | out_is_enabled | Indicates whether Acoustic Map is enabled. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
API Level:
- 20
MLAudioSetAcousticSceneTransmissionDefault
MLResult MLAudioSetAcousticSceneTransmissionDefault(
const MLAudioMultibandLevel * transmission
)
Sets amount of sound transmitted through non-Acoustic Element objects.
Parameters
const MLAudioMultibandLevel * | transmission | MLAudioMultibandLevel to set the default transmission. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Transmission is specified using MLAudioMultibandLevel, which includes gain and 3-band EQ. The values [1, (1, 1, 1)] represents fully transmissive while [0, (1, 1, 1)] or [1, (0, 0, 0)] represents fully obstructed.
API Level:
- 20
MLAudioGetAcousticSceneTransmissionDefault
MLResult MLAudioGetAcousticSceneTransmissionDefault(
MLAudioMultibandLevel * out_transmission
)
Returns amount of sound transmitted through non-Acoustic Element objects.
Parameters
MLAudioMultibandLevel * | out_transmission | MLAudioMultibandLevel to return the default transmission. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Transmission is specified using MLAudioMultibandLevel, which includes gain and 3-band EQ. The values [1, (1, 1, 1)] represents fully transmissive while [0, (1, 1, 1)] or [1, (0, 0, 0)] represents fully obstructed.
API Level:
- 20
MLAudioSetAcousticSceneDispersionDefault
MLResult MLAudioSetAcousticSceneDispersionDefault(
const MLAudioDispersionProperties * properties
)
Sets the fallback room properties to be used when none are otherwise specified.
Parameters
const MLAudioDispersionProperties * | properties | MLAudioDispersionProperties to set the default dispersion properties. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Dispersion properties are specified using MLAudioDispersionProperties, which includes reflections gain (MLAudioMultibandLevel) and reflections delay time.
API Level:
- 20
MLAudioGetAcousticSceneDispersionDefault
MLResult MLAudioGetAcousticSceneDispersionDefault(
MLAudioDispersionProperties * out_properties
)
Returns the default room properties used when none are otherwise specified.
Parameters
MLAudioDispersionProperties * | out_properties | MLAudioDispersionProperties to return the default dispersion properties. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Dispersion properties are specified using MLAudioDispersionProperties, which includes reflections gain (MLAudioMultibandLevel) and reflections delay time.
API Level:
- 20
MLAudioSetAcousticSceneReverbDefault
MLResult MLAudioSetAcousticSceneReverbDefault(
const MLAudioReverbProperties * properties
)
Sets the fallback room properties to be used when none are otherwise specified.
Parameters
const MLAudioReverbProperties * | properties | MLAudioReverbProperties to set the default reverb properties. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Reverb properties are specified using MLAudioReverbProperties, which includes reflections gain (MLAudioMultibandLevel), reflections delay time, reverb gain (MLAudioMultibandLevel), reverb delay time, and frequency-dependent reverb decay times.
API Level:
- 20
MLAudioGetAcousticSceneReverbDefault
MLResult MLAudioGetAcousticSceneReverbDefault(
MLAudioReverbProperties * out_properties
)
Returns the default room properties used when none are otherwise specified.
Parameters
MLAudioReverbProperties * | out_properties | MLAudioReverbProperties to return the default reverb properties. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
Reverb properties are specified using MLAudioReverbProperties, which includes reverb gain (MLAudioMultibandLevel), reverb delay time, and frequency-dependent reverb decay times.
API Level:
- 20
MLAudioGetChangedAcousticMap
MLResult MLAudioGetChangedAcousticMap(
uint32_t prev_map_tag,
uint8_t ** out_map_data,
uint32_t * out_map_size_in_bytes,
uint32_t * out_map_tag
)
Returns the Acoustic Map if updated since previous call.
Parameters
uint32_t | prev_map_tag | The last map tag received in previous call. |
uint8_t ** | out_map_data | Receives serialized Acoustic Map data if map tag is stale. |
uint32_t * | out_map_size_in_bytes | Receives length of serialized Acoustic Map data in bytes. |
uint32_t * | out_map_tag | Receives current map tag, to be passed in following call. |
Returns
MLResult | MLResult_Ok | If call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
Required Permissions:
- None
The Acoustic Map is the system-managed representation of the acoustic environment.
Caller is responsible for deallocating the memory used by out_partner_crossfeed_handles and out_partner_crossfeed_outputs.
API Level:
- 20
MLAudioSetSpatialSoundEnable
MLResult MLAudioSetSpatialSoundEnable(
MLHandle handle,
bool is_enabled
)
Enables/disables 3D audio processing for a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
bool | is_enabled | Determines whether 3D processing is on or off. |
Returns
MLResult | MLResult_Ok | Successfully enabled or disabled 3D audio processing. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The 3D audio processing for a sound output can be turned on or off by this function (default is off). When 3D processing is enabled, the 3D position should be set by calling MLAudioSetSpatialSoundPosition. When 3D processing is disabled, stereo sounds will play their left and right channels directly to the left and right speakers or earphones, and mono sounds will be panned center.
MLAudioGetSpatialSoundEnable
MLResult MLAudioGetSpatialSoundEnable(
MLHandle handle,
bool * out_is_enabled
)
Indicates whether 3D audio processing is enabled for a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
bool * | out_is_enabled | Indicates whether 3D processing is on or off. |
Returns
MLResult | MLResult_InvalidParam | Failed is enabled due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully indicated whether 3D audio processing is enabled. |
MLResult | MLResult_UnspecifiedFailure | Failed is enabled due to an unknown error. |
MLResult | MLAudioResult_HandleNotFound | Failed is enabled due to a missing handle. |
MLResult | MLAudioResult_InternalConfigError | Failed is enabled due to an internal configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed is enabled because feature has not been implemented yet. |
Required Permissions:
- None
MLAudioSetSpatialSoundPosition
MLResult MLAudioSetSpatialSoundPosition(
MLHandle handle,
uint32_t channel,
const MLVec3f * position
)
Sets the 3D position for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose position is being set. |
const MLVec3f * | position | MLVec3f struct to set the position. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set 3D position of audio channel. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this funtions sets the perceived position within the user's environment. Multi-channel sounds require the 3D position to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right. Positive x is right. Positive y is up. Positive z is back.
MLAudioGetSpatialSoundPosition
MLResult MLAudioGetSpatialSoundPosition(
MLHandle handle,
uint32_t channel,
MLVec3f * out_position
)
Returns the 3D position for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose position is being read. |
MLVec3f * | out_position | MLVec3f struct to return the position. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned 3D position of audio channel. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Multi-channel sounds require the 3D position to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right. Positive x is right. Positive y is up. Positive z is back.
MLAudioSetSpatialSoundDirection
MLResult MLAudioSetSpatialSoundDirection(
MLHandle handle,
uint32_t channel,
const MLQuaternionf * direction
)
Sets the radiation direction for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose direction is being set. |
const MLQuaternionf * | direction | MLQuaternionf struct to set the direction. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set radiation direction. |
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 directionS due to an internal configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
For sounds that have been set to radiate in a directional way by MLAudioSetSpatialSoundRadiation, this function sets the direction of the radiation. Multi-channel sounds require the radiation direction to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
MLAudioGetSpatialSoundDirection
MLResult MLAudioGetSpatialSoundDirection(
MLHandle handle,
uint32_t channel,
MLQuaternionf * out_direction
)
Returns the radiation direction for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose direction is being read. |
MLQuaternionf * | out_direction | MLQuaternionf struct to return the direction. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned radiation direction. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Multi-channel sounds require the radiation direction to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
MLAudioSetSpatialSoundBillboarding
MLResult MLAudioSetSpatialSoundBillboarding(
MLHandle id,
bool is_billboarding
)
Sets a mode where the sound always faces the listener.
Parameters
MLHandle | id | MLHandle Used to identify the sound output. |
bool | is_billboarding | Determines whether the sound always faces the listener. |
Returns
MLResult | MLResult_OK | If the call was successful. |
MLResult | MLAudioResult_HandleNotFound | Unable to find resource handle. |
MLResult | MLAudioResult_OperationUnavailable | Unavailable for this sound. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this call can be used to ensure a spatial sound always faces the listener. This allows the sound's radiation pattern to be used for proper acoustic propagation, while always ensuring the listener hears the sound head on. While this setting is enabled, values set by MLAudioSetSpatialSoundDirection are unused.
API Level:
- 20
MLAudioGetSpatialSoundBillboarding
MLResult MLAudioGetSpatialSoundBillboarding(
MLHandle id,
bool * out_is_billboarding
)
Indicates whether the sound automatically faces the listener.
Parameters
MLHandle | id | MLHandle Used to identify the sound output. |
bool * | out_is_billboarding | Indicates whether the sound automatically faces the listener. |
Returns
MLResult | MLResult_OK | Successfully returned distance properties. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLAudioResult_HandleNotFound | Failed due to a missing handle. |
MLResult | MLAudioResult_OperationUnavailable | Unavailable for this sound. |
Required Permissions:
- None
API Level:
- 20
MLAudioSetSpatialSoundObstruction
MLResult MLAudioSetSpatialSoundObstruction(
MLHandle id,
uint32_t channel,
const MLAudioObstruction * left_ear,
const MLAudioObstruction * right_ear
)
Sets the direct path obstruction for one channel of a sound output.
Parameters
MLHandle | id | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose obstruction is being set. |
const MLAudioObstruction * | left_ear | MLAudioObstruction for the direct path to left ear. |
const MLAudioObstruction * | right_ear | MLAudioObstruction for the direct path to right ear. |
Returns
MLResult | MLResult_Ok | If the call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_OperationUnavailable | Unavailable for this sound. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this call sets the obstruction of the direct path from that source to each ear of the listener. Multi-channel sounds require the ear obstructions to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
This API property is not intended to be user-specified, but rather set as part of a physics update.
API Level:
- 20
MLAudioGetSpatialSoundObstruction
MLResult MLAudioGetSpatialSoundObstruction(
MLHandle id,
uint32_t channel,
MLAudioObstruction * out_left_ear,
MLAudioObstruction * out_right_ear
)
Returns the direct path obstruction for one channel of a sound output.
Parameters
MLHandle | id | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose obstruction is being set. |
MLAudioObstruction * | out_left_ear | MLAudioObstruction to return the obstruction for left ear. |
MLAudioObstruction * | out_right_ear | MLAudioObstruction to return the obstruction for right ear. |
Returns
MLResult | MLResult_Ok | If the call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Handle not found. |
MLResult | MLAudioResult_OperationUnavailable | Unavailable for this sound. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Multi-channel sounds require the ear obstructions to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
This API property is not intended to be user-specified, but rather set as part of a physics update.
API Level:
- 20
MLAudioSetSpatialSoundObstructionOverride
MLResult MLAudioSetSpatialSoundObstructionOverride(
MLHandle id,
const MLAudioMultibandLevel * override
)
Sets an override that enables the sound to pass through obstructions.
Parameters
MLHandle | id | MLHandle Used to identify the sound output. |
const MLAudioMultibandLevel * | override | MLAudioMultibandLevel used to set the override. |
Returns
MLResult | MLResult_OK | If the call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Unable to find resource handle. |
MLResult | MLAudioResult_OperationUnavailable | Unavailable for this sound. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this call can be used to vary the degree to which the sound passes through obstructions. A MultibandLevel is used to set the override values, 0 representing no change, 1 representing fully transmissive, per band. For multi-channel sounds, all channels are affected equally by the single obstruction override for the sound.
API Level:
- 20
MLAudioGetSpatialSoundObstructionOverride
MLResult MLAudioGetSpatialSoundObstructionOverride(
MLHandle id,
MLAudioMultibandLevel * out_override
)
Returns the amount of the sound obstruction override.
Parameters
MLHandle | id | MLHandle Used to identify the sound output. |
MLAudioMultibandLevel * | out_override | MLAudioMultibandLevel used to return the override. |
Returns
MLResult | MLResult_OK | If the call was successful. |
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLAudioResult_HandleNotFound | Unable to find resource handle. |
MLResult | MLAudioResult_OperationUnavailable | Unavailable for this sound. |
MLResult | MLResult_UnspecifiedFailure | Internal error. |
MLResult | MLAudioResult_InternalConfigError | Internal config error. |
MLResult | MLAudioResult_NotImplemented | Internal error. |
Required Permissions:
- None
Obstruction override is returned as a MultibandLevel, with 0 representing no change and 1 representing fully transmissive, per band. For multi-channel sounds, all channels are affected equally by the single obstruction override for the sound.
API Level:
- 20
MLAudioSetSpatialSoundDistanceAttenuation
MLResult MLAudioSetSpatialSoundDistanceAttenuation(
MLHandle handle,
uint32_t channel,
const MLAudioSpatialSoundDistanceProperties * properties
)
Sets the distance properties for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose distance properties are being set. |
const MLAudioSpatialSoundDistanceProperties * | properties | MLAudioSpatialSoundDistanceProperties struct to set the properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets the way in which distance affects sound volume. Multi-channel sounds require the distance properties to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioGetSpatialSoundDistanceAttenuation
MLResult MLAudioGetSpatialSoundDistanceAttenuation(
MLHandle handle,
uint32_t channel,
MLAudioSpatialSoundDistanceProperties * out_properties
)
Returns the distance properties for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose distance properties are being read. |
MLAudioSpatialSoundDistanceProperties * | out_properties | MLAudioSpatialSoundDistanceProperties struct to return the properties. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
Multi-channel sounds require the distance properties to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioSetSpatialSoundRadiation
MLResult MLAudioSetSpatialSoundRadiation(
MLHandle handle,
uint32_t channel,
const MLAudioSpatialSoundRadiationProperties * properties
)
Sets the radiation properties for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose radiation properties are being set. |
const MLAudioSpatialSoundRadiationProperties * | properties | MLAudioSpatialSoundRadiationProperties struct to set the properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set radiation 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets the degree of directionality in the sound projection. The default setting is for sounds to be omnidirectional (equal projection in all directions). Multi-channel sounds require the radiation properties to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioGetSpatialSoundRadiation
MLResult MLAudioGetSpatialSoundRadiation(
MLHandle handle,
uint32_t channel,
MLAudioSpatialSoundRadiationProperties * out_properties
)
Returns the radiation properties for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose radiation properties are being set. |
MLAudioSpatialSoundRadiationProperties * | out_properties | MLAudioSpatialSoundRadiationProperties struct to return the properties. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned radiation 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Multi-channel sounds require the radiation properties to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioSetSpatialSoundDirectLevel
MLResult MLAudioSetSpatialSoundDirectLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the direct sound level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose direct level is being set. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set direct send levels. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the direct component of the sound, i.e., the audio mix for the part of the sound not affected by room acoustics. Multi-channel sounds require the direct send levels to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioGetSpatialSoundDirectLevel
MLResult MLAudioGetSpatialSoundDirectLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Returns the direct sound level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose direct level is being read. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to return the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned direct send levels. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Multi-channel sounds require the direct sound level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioSetSpatialSoundIndirectLevel
MLResult MLAudioSetSpatialSoundIndirectLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the indirect sound level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose indirect sound level is being set. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the indirect component of the sound, i.e., the audio mix for the part of the sound that's affected by room acoustics (includes reflections and reverb). Multi-channel sounds require the indirect sound level to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioGetSpatialSoundIndirectLevel
MLResult MLAudioGetSpatialSoundIndirectLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Returns the indirect sound level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose indirect sound level is being read. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to return the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
Multi-channel sounds require the indirect sound level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioSetSpatialSoundDispersionSendLevel
MLResult MLAudioSetSpatialSoundDispersionSendLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the dispersion level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose dispersion level is being set. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set room send levels. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the dispersion component of the sound, i.e., the audio mix for late clustered reflections caused by room acoustics (also controlled by MLAudioSetSpatialSoundIndirectLevel). Multi-channel sounds require the dispersion level to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioGetSpatialSoundDispersionSendLevel
MLResult MLAudioGetSpatialSoundDispersionSendLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Returns the dispersion level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose dispersion level is being read. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to return the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned room send levels. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
Multi-channel sounds require the dispersion level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioSetSpatialSoundReverbSendLevel
MLResult MLAudioSetSpatialSoundReverbSendLevel(
MLHandle handle,
uint32_t channel,
const MLAudioMultibandLevel * level
)
Sets the reverb level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose reverb level is being set. |
const MLAudioMultibandLevel * | level | MLAudioMultibandLevel struct to set the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
When 3D audio processing is enabled for a sound output (see MLAudioSetSpatialSoundEnable) this function sets gain and 3-band eq for the reverb component of the sound, i.e., the audio mix for late reverberation caused by room acoustics (also controlled by MLAudioSetSpatialSoundIndirectLevel). Multi-channel sounds require the reverb level to be set individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioGetSpatialSoundReverbSendLevel
MLResult MLAudioGetSpatialSoundReverbSendLevel(
MLHandle handle,
uint32_t channel,
MLAudioMultibandLevel * out_level
)
Returns the reverb level for one channel of a sound output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint32_t | channel | Selects the channel whose reverb level is being read. |
MLAudioMultibandLevel * | out_level | MLAudioMultibandLevel struct to return the gain and eq. |
Returns
MLResult | MLResult_InvalidParam | If input parameter is invalid. |
MLResult | MLResult_Ok | If the call was successful. |
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
Multi-channel sounds require the reverb level to be read individually for each channel by calling this function once for each channel. For mono sounds use channel = 0. For stereo sounds use channel = 0 for left and channel = 1 for right.
API Level:
- 20
MLAudioSetSpatialSoundHeadRelative
MLResult MLAudioSetSpatialSoundHeadRelative(
MLHandle handle,
bool is_head_relative
)
Sets whether the coordinates for a sound output are head relative.
Parameters
MLHandle | handle | MLHandle Used to identify the sound output. |
bool | is_head_relative | Determines whether the coordinates are head relative. |
Returns
MLResult | MLResult_Ok | Successfully set the relative state of coordinates. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
This call can be used to make the coordinate system of the specified sound be head relative, in which case the user's head position and orientation are ignored when simulating the sound's spatial position and direction. This is useful for sounds attached to graphics objects that don't use headpose, or when the desired effect is for sound position and direction to be fixed relative to the head. Head relative sounds always point at the user's head like "billboarding" graphics. If a sound is not explicitly told to use head relative coordinates, world coordinates are used by default.
API Level:
- 7
MLAudioGetSpatialSoundHeadRelative
MLResult MLAudioGetSpatialSoundHeadRelative(
MLHandle handle,
bool * out_is_head_relative
)
Returns whether the coordinates for a sound output are head relative.
Parameters
MLHandle | handle | MLHandle Used to identify the sound output. |
bool * | out_is_head_relative | Indicates whether the coordinates are head relative. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned whether coordinates are head relative. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
This call can be used to determine if the coordinate system of the specified sound has been set to be head relative.
API Level:
- 20
MLAudioGetSpatialRaycastRequests
MLResult MLAudioGetSpatialRaycastRequests(
MLAudioRaycastRequest ** out_raycast_requests,
uint32_t * out_request_count
)
Returns a list of ID-tracked requests for raycast operations.
Parameters
MLAudioRaycastRequest ** | out_raycast_requests | Returns list of requests for raycast operation. |
uint32_t * | out_request_count | Returns number of raycast operations requested. |
Returns
MLResult | MLResult_Ok | If the call was successful. |
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
- This function is not intended to be called directly by developers.
- The caller is responsible for deallocating the memory containing the raycast requests.
API Level:
- 20
MLAudioSetSpatialRaycastResults
MLResult MLAudioSetSpatialRaycastResults(
MLAudioRaycastResult * raycast_results,
uint32_t result_count
)
Sets the ID-tracked results for previously requested raycast operations.
Parameters
MLAudioRaycastResult * | raycast_results | Sets the list of raycast operation results. |
uint32_t | result_count | Sets the number of raycast results. |
Returns
MLResult | MLResult_Ok | If the call was successful. |
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
This function is not intended to be called directly by developers.
API Level:
- 20
MLAudioGetBufferedOutputDefaults
MLResult MLAudioGetBufferedOutputDefaults(
uint32_t channel_count,
uint32_t samples_per_second,
float max_pitch_change,
MLAudioBufferFormat * out_format,
uint32_t * out_recommended_size_in_bytes,
uint32_t * out_min_size_in_bytes
)
Returns the preferred (i.e. best performing) settings for buffered output.
Parameters
uint32_t | channel_count | Number of audio channels (e.g. 2 for stereo). |
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 | Recommended settings for MLAudioBufferFormat. |
uint32_t * | out_recommended_size_in_bytes | Recommended size for the buffers. |
uint32_t * | out_min_size_in_bytes | Minimum allowable size for the buffers. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned preferred settings for buffered output. |
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
API Level:
- 7
MLAudioGetBufferedOutputLatency
MLResult MLAudioGetBufferedOutputLatency(
MLHandle handle,
float * out_latency_in_msec
)
Returns the latency for a buffered output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
float * | out_latency_in_msec | Indicates the latency in milliseconds. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned latency for buffered output. |
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
This function returns the latency between the time a buffer is enqueued via MLAudioReleaseOutputBuffer and the time its audio is heard at the speakers or earphones.
API Level:
- 7
MLAudioGetBufferedOutputFramesPlayed
MLResult MLAudioGetBufferedOutputFramesPlayed(
MLHandle handle,
uint64_t * out_frames_played
)
Returns the number of audio frames played by a buffered output.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
uint64_t * | out_frames_played | The number of audio frames played. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned number of audio frames by buffered output. |
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 function returns the number of frames that have been sent down to the audio mixer (-not- the number that have been passed to the buffers) since the last time MLAudioStartSound was called for this output. Note that the perceived sound may be slightly behind this value due to the buffer latency (which can be queried by calling MLAudioGetBufferedOutputLatency). Pausing and resuming does not affect the frame count.
API Level:
- 7
MLAudioGetOutputBuffer
MLResult MLAudioGetOutputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)
Returns an empty buffer for writing more buffered data.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
MLAudioBuffer * | out_buf | MLAudioBuffer containing the buf to write into. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned empty 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
This function returns an output buffer when one of the output buffers is empty and needs more data. It is possible to call this function in a polling fashion. However for greater efficiency it is recommended to provide a callback to the 'create' function (in which case this function may be called from within the callback).
API Level:
- 7
MLAudioReleaseOutputBuffer
MLResult MLAudioReleaseOutputBuffer(
MLHandle handle
)
Releases a buffer once it has been filled.
Parameters
MLHandle | handle | MLHandle used to identify the sound output. |
Returns
MLResult | MLResult_Ok | Successfully released 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
After receiving an empty buffer from MLAudioGetOutputBuffer and writing audio data into that buffer, call this function to indicate that the buffer has been filled and can now be played.
API Level:
- 7
MLAudioGetMasterVolume
MLResult MLAudioGetMasterVolume(
float * out_volume
)
Returns the master volume for the audio system.
Parameters
float * | out_volume | The current setting of master volume. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully return master volume. |
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 | MLAudioMasterVolumeChangedCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_Ok | Successfully register callback to the master volume. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The callback will be called whenever the master volume gets changed (even if changed by the owner of the callback). The 'context' argument is passed back to the callback as its first argument, and the new master volume setting is passed to the callback as its second argument.
MLAudioGetOutputMute
MLResult MLAudioGetOutputMute(
bool * out_is_muted
)
Indicates whether the output mute of the audio system is on or off.
Parameters
bool * | out_is_muted | Indicates whether the audio output is muted or not. |
Returns
MLResult | MLResult_Ok | Successfully indicated state of output mute. |
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
Queries the current status of the output mute.
API Level:
- 20
MLAudioSetOutputMuteCallback
MLResult MLAudioSetOutputMuteCallback(
MLAudioOutputMuteChangedCallback callback,
void * context
)
Registers a callback for audio output mute change.
Parameters
MLAudioOutputMuteChangedCallback | callback | MLAudioOutputMuteChangedCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_Ok | Successfully registered callback for audio output mute change. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
Required Permissions:
- None
The callback will be called whenever the output mute changes (even if changed by the owner of the callback). The output mute setting is passed back to the callback as its first argument, and the 'context' argument is passed to the callback as its second argument.
API Level:
- 8
MLAudioCreateInputFromMicCapture
MLResult MLAudioCreateInputFromMicCapture(
MLAudioMicCaptureType mic_capture_type,
const MLAudioBufferFormat * format,
uint32_t buffer_size_in_bytes,
MLAudioBufferCallback callback,
void * context,
MLHandle * out_handle
)
Creates a new sound input that provides audio from the mics on the wearable.
Parameters
MLAudioMicCaptureType | mic_capture_type | MLAudioMicCaptureType specifying the type of mic capture created. |
const MLAudioBufferFormat * | format | MLAudioBufferFormat specifying the audio format of the stream. |
uint32_t | buffer_size_in_bytes | Requested size in bytes for each of the two stream buffers. |
MLAudioBufferCallback | callback | MLAudioBufferCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound input. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully created new sound input that provides a mic capture stream. |
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)
Creates a sound input and allocates a double-buffer for streaming audio data from it. The 'mic_capture_type' argument specifies the "flavor" of the microphone capture, and the MLAudioMicCaptureType enum lists the available buffering formats for each flavor. To stream data from the buffers call MLAudioGetInputBuffer to get a full buffer, then read the data from the buffer, then call MLAudioReleaseInputBuffer to indicate that the buffer is ready to re-use. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument specifies the format of the buffering which must agree with the selected 'mic_capture_type'. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, the input can be started by calling MLAudioStartInput.
API Level:
- 20
MLAudioCreateInputFromVirtualCapture
MLResult MLAudioCreateInputFromVirtualCapture(
const MLAudioBufferFormat * format,
uint32_t buffer_size,
MLAudioBufferCallback callback,
void * callback_context,
MLHandle * out_handle
)
Creates a new sound input that provides a "virtual capture" stream.
Parameters
const MLAudioBufferFormat * | format | MLAudioBufferFormat specifying the audio format of the stream. |
uint32_t | buffer_size | Requested size in bytes for each of the two stream buffers. |
MLAudioBufferCallback | callback | MLAudioBufferCallback function pointer. |
void * | callback_context | Generic data pointer passed back to callback. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound input. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully created new sound input that provides a "virtual capture" stream. |
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:
- None
Creates a sound input and allocates a double-buffer for streaming audio data from it. The "virtual capture" stream provides a stereo stream capturing the final audio output mix of all the sounds currently being played by the audio system. To stream data from the buffers call MLAudioGetInputBuffer to get a full buffer, then read the data from the buffer, then call MLAudioReleaseInputBuffer to indicate that the buffer is ready to re-use. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument specifies the format of which the following are supported: Two channels (stereo), 16 bit integer, a sampling rate of 48k. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, the input can be started by calling MLAudioStartInput.
API Level:
- 8
MLAudioCreateInputFromMixedCapture
MLResult MLAudioCreateInputFromMixedCapture(
const MLAudioBufferFormat * format,
uint32_t buffer_size,
MLAudioBufferCallback callback,
void * callback_context,
MLHandle * out_handle
)
Creates a new sound input that provides a "mixed capture" stream.
Parameters
const MLAudioBufferFormat * | format | MLAudioBufferFormat specifying the audio format of the stream. |
uint32_t | buffer_size | Requested size in bytes for each of the two stream buffers. |
MLAudioBufferCallback | callback | MLAudioBufferCallback function pointer. |
void * | callback_context | Generic data pointer passed back to callback. |
MLHandle * | out_handle | MLHandle used in subsequent calls for this sound input. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully created new sound input that provides a "mixed capture" stream. |
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:
- None
Creates a sound input and allocates a double-buffer for streaming audio data from it. The "mixed capture" stream provides a stereo stream capturing the final audio output mix of all the sounds currently being played by the audio system (same as "virtual capture"), plus the user's voice processed for communications (same as MLAudioMicCaptureType_VoiceComm). To stream data from the buffers call MLAudioGetInputBuffer to get a full buffer, then read the data from the buffer, then call MLAudioReleaseInputBuffer to indicate that the buffer is ready to re-use. This can be done either on a polling basis or within a callback set via the 'callback' argument. The 'format' argument supports a variety of audio formats, and the preferred format can be determined in advance by calling MLAudioGetBufferedInputDefaults. The 'buffer_size' argument will use the recommended size if 0 is passed in. After creation, the input can be started by calling MLAudioStartInput.
API Level:
- 8
MLAudioDestroyInput
MLResult MLAudioDestroyInput(
MLHandle handle
)
Destroys a previously created sound input.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
Returns
MLResult | MLResult_Ok | Successfully destroyed previously created 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 capture for a sound input.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
Returns
MLResult | MLResult_Ok | Successfully started capture for sound input. |
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
MLAudioStopInput
MLResult MLAudioStopInput(
MLHandle handle
)
Stops capture for a sound input.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
Returns
MLResult | MLResult_Ok | Successfully stopped capture for sound input. |
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
MLAudioGetInputState
MLResult MLAudioGetInputState(
MLHandle handle,
MLAudioState * out_state
)
Indicates the play state of a sound input.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
MLAudioState * | out_state | Indicates the current play state. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully indicated play state of 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
The MLAudioState indicates whether the sound input is stopped or playing.
MLAudioGetBufferedInputDefaults
MLResult MLAudioGetBufferedInputDefaults(
uint32_t channel_count,
uint32_t samples_per_second,
MLAudioBufferFormat * out_format,
uint32_t * out_recommended_size_in_bytes,
uint32_t * out_min_size_in_bytes
)
Returns the preferred (i.e. best performing) settings for buffered input.
Parameters
uint32_t | channel_count | Number of audio channels (e.g. 2 for stereo). |
uint32_t | samples_per_second | Sample rate for the buffered input. |
MLAudioBufferFormat * | out_format | Recommended Settings for MLAudioBufferFormat. |
uint32_t * | out_recommended_size_in_bytes | Recommended size for the buffers. |
uint32_t * | out_min_size_in_bytes | Minimum allowable size for the buffers. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned the preferred settings for buffered input. |
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
API Level:
- 7
MLAudioGetBufferedInputLatency
MLResult MLAudioGetBufferedInputLatency(
MLHandle handle,
float * out_latency_in_msec
)
Returns the latency for a sound input.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
float * | out_latency_in_msec | Indicates the latency in milliseconds. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned the latency for 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. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
This function returns the latency between the time a sound occurs in the real world and the time it becomes available via MLAudioGetInputBuffer.
API Level:
- 7
MLAudioGetInputBuffer
MLResult MLAudioGetInputBuffer(
MLHandle handle,
MLAudioBuffer * out_buf
)
Returns a full buffer containing captured audio data.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
MLAudioBuffer * | out_buf | MLAudioBuffer containing the buf to read from. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned full buffer containing captured audio data. |
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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
This function returns a buffer when one of the input buffers is full and needs to be read. It is possible to call this function in a polling fashion. However for greater efficiency it is recommended to provide a callback to the 'create' function (in which case this function may be called from within the callback).
API Level:
- 7
MLAudioReleaseInputBuffer
MLResult MLAudioReleaseInputBuffer(
MLHandle handle
)
Releases a buffer once it has been read.
Parameters
MLHandle | handle | MLHandle used to identify the sound input. |
Returns
MLResult | MLResult_Ok | Successfully released 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 configurations error. |
MLResult | MLAudioResult_NotImplemented | Failed because feature has not been implemented yet. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
After receiving a full buffer from MLAudioGetInputBuffer and reading the audio data from that buffer, call this function to indicate that the buffer has been read and can now be re-used.
API Level:
- 7
MLAudioSetMicMute
MLResult MLAudioSetMicMute(
bool is_muted
)
Mutes or un-mutes all microphone capture.
Parameters
bool | is_muted | Determines whether mic capture is muted or not. |
Returns
MLResult | MLResult_Ok | Successfully Successfully muted or unmuted microphone capture. |
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)
This mute control applies to all microphone capture in general (excluding "recognizer voice" which is always active). When mic capture is muted or unmuted by one app, it is muted or unmuted for all apps. Note: This setting is separate from any muting done by the audio policy manager (such as when the "reality button" is pressed).
MLAudioGetMicMute
MLResult MLAudioGetMicMute(
bool * out_is_muted
)
Returns whether all microphone capture is muted or not.
Parameters
bool * | out_is_muted | Indicates whether the mic capture is muted or not. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully indicated whether microphone is muted. |
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)
API Level:
- 20
MLAudioSetMicMuteCallback
MLResult MLAudioSetMicMuteCallback(
MLAudioMicMuteCallback callback,
void * context
)
Registers a callback for changes to the global mic mute.
Parameters
MLAudioMicMuteCallback | callback | MLAudioMicMuteCallback function pointer. |
void * | context | Generic data pointer passed back to callback. |
Returns
MLResult | MLResult_AllocFailed | Failed due to memory allocation failure. |
MLResult | MLResult_Ok | Successfully registered 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)
The callback will be called whenever the global mic mute gets changed (even if changed by the owner of the callback). The 'context' argument is passed back to the callback as its first argument, and the new mic mute setting is passed to the callback as its second argument.
MLAudioBeginTraitAnalysisFromMicCapture
MLResult MLAudioBeginTraitAnalysisFromMicCapture(
MLAudioTraitAnalysisTarget target,
MLAudioTraitAnalysisCallback callback,
void * callback_context,
MLHandle * out_handle
)
Creates a new analysis input for the specified target.
Parameters
MLAudioTraitAnalysisTarget | target | MLAudioTraitAnalysisTarget specifies the analysis target. |
MLAudioTraitAnalysisCallback | callback | MLAudioTraitAnalysisCallback function pointer. |
void * | callback_context | Generic data pointer passed back to callback. |
MLHandle * | out_handle | MLHandle used to identify this analysis in subsequent calls. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully set control frequencies. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
Required Permissions:
- None
Creates a trait analysis, initializes its connection to the device microphones as the audio data source, and returns a handle in the 'out_handle' argument. The 'target' argument specifies the type of trait analysis, which implies the type of audio content to be analyzed. Trait analysis results are returned as a single float, whose meaning is context dependent based on the target. Results may be acquired either on a polling basis by calling MLAudioGetTraitAnalysis, or via a callback set by the optional 'callback' argument of this function.
API Level:
- 20
MLAudioGetTraitAnalysis
MLResult MLAudioGetTraitAnalysis(
MLHandle handle,
float * out_value
)
Returns the current value of the trait analysis associated with the specified handle.
Parameters
MLHandle | handle | MLHandle used to identify the analysis. |
float * | out_value | Current value of analysis. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned control frequencies. |
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:
- 20
MLAudioEndTraitAnalysis
MLResult MLAudioEndTraitAnalysis(
MLHandle handle
)
Stops a previously started trait analysis.
Parameters
MLHandle | handle | MLHandle used to identify the analysis. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned empty buffe for writing more stream data. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
Required Permissions:
- None
Stops the analysis associated with the specified handle.
API Level:
- 20
MLAudioBeginSpectralAnalysisFromMicCapture
MLResult MLAudioBeginSpectralAnalysisFromMicCapture(
MLAudioSpectralAnalysisTarget target,
MLAudioSpectralAnalysisCallback callback,
void * callback_context,
MLHandle * out_handle
)
Starts a new spectral analysis that provides frequency spectrum energy derived from mic signals.
Parameters
MLAudioSpectralAnalysisTarget | target | MLAudioSpectralAnalysisTarget specifies the analysis target. |
MLAudioSpectralAnalysisCallback | callback | MLAudioSpectralAnalysisCallback function pointer. |
void * | callback_context | Generic data pointer passed back to callback. |
MLHandle * | out_handle | MLHandle used to identify this analysis in subsequent calls. |
Returns
MLResult | MLResult_OK | Successfully released buffer. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
Required Permissions:
- None
Creates a spectral analysis, initializes its connection to the device microphones as the audio data source, and returns a handle in the 'out_handle' argument. The 'target' argument specifies the type of spectral analysis, which implies the type of audio content to be analyzed. Spectral analysis results are returned in the MLAudioSpectralAnalysis struct, which contains a time window of spectral analysis values. Results may be acquired either on a polling basis by calling MLAudioGetSpectralAnalysis, or via a callback set by the optional 'callback' argument of this function, triggered whenever new values are available. Cleanup of MLAudioSpectralAnalysis passed in the optional callback is handled by the ml_audio library; the caller is not responsible for deallocating memory if the callback is used.
API Level:
- 20
MLAudioGetSpectralAnalysis
MLResult MLAudioGetSpectralAnalysis(
MLHandle handle,
MLAudioSpectralAnalysis * out_values
)
Returns the current value of the spectral analysis associated with the specified handle.
Parameters
MLHandle | handle | MLHandle used to identify the analysis. |
MLAudioSpectralAnalysis * | out_values | MLAudioSpectralAnalysis containing the current values of a spectral analysis. |
Returns
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_Ok | Successfully returned latency for sound input. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
MLResult | MLAudioResult_OperationUnavailable | Failed because operation is unavailable. |
Required Permissions:
- None
Allocates memory at out_values->values based on the MLAudioSpectralAnalysisTarget associated with the specified handle. The caller is responsible for deallocating this memory after each call to MLAudioGetSpectralAnalysis.
API Level:
- 20
MLAudioEndSpectralAnalysis
MLResult MLAudioEndSpectralAnalysis(
MLHandle handle
)
Stops a previously started spectral analysis.
Parameters
MLHandle | handle | MLHandle used to identify the analysis. |
Returns
MLResult | MLResult_OK | Successfully stopped spectral analysis. |
MLResult | MLResult_InvalidParam | Failed due to an invalid parameter. |
MLResult | MLResult_UnspecifiedFailure | Failed due to an unknown error. |
Required Permissions:
- None
Stops the analysis associated with the specified handle.
API Level:
- 20
Source code
// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2017 Magic Leap, Inc. All Rights Reserved.
// Use of this file is governed by the Software License Agreement,
// located here: https://www.magicleap.com/software-license-agreement-ml2
// Terms and conditions applicable to third-party materials accompanying
// this distribution may also be found in the top-level NOTICE file
// appearing herein.
// %COPYRIGHT_END%
// ---------------------------------------------------------------------
// %BANNER_END%
#pragma once
#include "ml_api.h"
#include "ml_types.h"
ML_EXTERN_C_BEGIN
typedef enum MLAudioState {
MLAudioState_Stopped,
MLAudioState_Playing,
MLAudioState_Paused,
MLAudioState_Ensure32Bits = 0x7FFFFFFF
} MLAudioState;
typedef enum MLAudioSoundEvent {
MLAudioSoundEvent_End,
MLAudioSoundEvent_Loop,
MLAudioSoundEvent_MutedBySystem,
MLAudioSoundEvent_UnmutedBySystem,
MLAudioSoundEvent_DuckedBySystem,
MLAudioSoundEvent_UnduckedBySystem,
MLAudioSoundEvent_ResourceDestroyed,
MLAudioSoundEvent_Ensure32Bits = 0x7FFFFFFF
} MLAudioSoundEvent;
typedef enum MLAudioMediaEvent {
MLAudioMediaEvent_Play,
MLAudioMediaEvent_Stop,
MLAudioMediaEvent_Pause,
MLAudioMediaEvent_NextTrack,
MLAudioMediaEvent_PrevTrack,
MLAudioMediaEvent_Ensure32Bits = 0x7FFFFFFF
} MLAudioMediaEvent;
typedef enum MLAudioOutputDevice {
MLAudioOutputDevice_Wearable,
MLAudioOutputDevice_USB,
MLAudioOutputDevice_Bluetooth,
MLAudioOutputDevice_HearingAid,
MLAudioOutputDevice_Ensure32Bits = 0x7FFFFFFF
} MLAudioOutputDevice;
typedef enum MLAudioMicCaptureType {
MLAudioMicCaptureType_VoiceComm,
MLAudioMicCaptureType_VoiceCapture,
MLAudioMicCaptureType_WorldCapture=4,
MLAudioMicCaptureType_RawMicsAndAECRef,
MLAudioMicCaptureType_Ensure32Bits=0x7FFFFFFF
} MLAudioMicCaptureType;
typedef struct MLAudioMultibandLevel {
float main;
float lf;
float mf;
float hf;
} MLAudioMultibandLevel;
typedef struct MLAudioDispersionProperties {
MLAudioMultibandLevel gain;
float pre_delay;
} MLAudioDispersionProperties;
typedef struct MLAudioReverbProperties {
MLAudioMultibandLevel gain;
float pre_delay;
float decay_time;
float decay_time_lf_ratio;
float decay_time_hf_ratio;
} MLAudioReverbProperties;
typedef struct MLAudioSpatialSoundDistanceProperties {
float min_distance;
float max_distance;
float rolloff_factor;
} MLAudioSpatialSoundDistanceProperties;
typedef struct MLAudioSpatialSoundRadiationProperties {
float inner_angle;
float outer_angle;
float outer_gain;
float outer_gain_lf;
float outer_gain_mf;
float outer_gain_hf;
} MLAudioSpatialSoundRadiationProperties;
typedef struct MLAudioRaycast {
MLVec3f eye_point;
MLVec3f end_point;
} MLAudioRaycast;
typedef struct MLAudioObstruction {
float factor;
MLVec3f hit_point;
} MLAudioObstruction;
typedef struct MLAudioRaycastRequest {
MLHandle source_id;
MLHandle image_id;
uint32_t leg_index;
MLAudioRaycast ray;
} MLAudioRaycastRequest;
typedef struct MLAudioRaycastResult {
MLHandle source_id;
MLHandle image_id;
uint32_t leg_index;
MLAudioRaycast ray;
MLAudioObstruction obstruction;
} MLAudioRaycastResult;
typedef enum MLAudioSampleFormat {
MLAudioSampleFormat_Int,
MLAudioSampleFormat_Float,
MLAudioSampleFormat_Ensure32Bits = 0x7FFFFFFF
} MLAudioSampleFormat;
typedef enum MLAudioChannelFormat {
MLAudioChannelFormat_Default,
MLAudioChannelFormat_AmbisonicAmbix,
MLAudioChannelFormat_Ensure32Bits = 0x7FFFFFFF,
} MLAudioChannelFormat;
typedef struct MLAudioBufferFormat {
uint32_t channel_count;
uint32_t samples_per_second;
uint32_t bits_per_sample;
uint32_t valid_bits_per_sample;
MLAudioSampleFormat sample_format;
MLAudioChannelFormat channel_format;
} MLAudioBufferFormat;
typedef struct MLAudioBuffer {
uint8_t *ptr;
uint32_t size;
} MLAudioBuffer;
typedef enum MLAudioTraitAnalysisTarget {
MLAudioTraitAnalysisTarget_AmbientSoundLevelDbfs,
MLAudioTraitAnalysisTarget_UserVoicePresence,
MLAudioTraitAnalysisTarget_UserVoiceLevelDbfs,
MLAudioTraitAnalysisTarget_UserVoicePitch,
MLAudioTraitAnalysisTarget_Ensure32Bits = 0x7FFFFFFF
} MLAudioTraitAnalysisTarget;
typedef enum MLAudioSpectralAnalysisTarget {
MLAudioSpectralAnalysisTarget_UserVoiceSpectrumMfcc,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumBark,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumMel,
MLAudioSpectralAnalysisTarget_AmbientSoundSpectrumThirdOctave,
MLAudioSpectralAnalysisTarget_Ensure32Bits = 0x7FFFFFFF
} MLAudioSpectralAnalysisTarget;
typedef struct MLAudioSpectralAnalysis {
float *values;
int32_t num_columns;
int32_t num_rows;
} MLAudioSpectralAnalysis;
enum {
MLResultAPIPrefix_Audio = MLRESULT_PREFIX(0x9e11)
};
typedef enum MLAudioResult {
MLAudioResult_NotImplemented = MLResultAPIPrefix_Audio,
MLAudioResult_HandleNotFound,
MLAudioResult_InvalidSampleRate,
MLAudioResult_InvalidBitsPerSample,
MLAudioResult_InvalidValidBits,
MLAudioResult_InvalidSampleFormat,
MLAudioResult_InvalidChannelCount,
MLAudioResult_InvalidBufferSize,
MLAudioResult_BufferNotReady,
MLAudioResult_FileNotFound,
MLAudioResult_FileNotRecognized,
MLAudioResult_ResourceNotFound,
MLAudioResult_ResourceDiscarded,
MLAudioResult_OperationUnavailable,
MLAudioResult_OperationNotReady,
MLAudioResult_InternalConfigError,
MLAudioResult_Ensure32Bits = 0x7FFFFFFF
} MLAudioResult;
ML_API const char* ML_CALL MLAudioGetResultString(MLResult result_code);
typedef void (*MLAudioSoundEventCallback)(MLHandle handle, MLAudioSoundEvent event, void *context);
typedef void (*MLAudioMediaEventCallback)(MLAudioMediaEvent event, void *context);
typedef void (*MLAudioBufferCallback)(MLHandle handle, void *context);
typedef void (*MLAudioResourceDiscardedCallback)(MLHandle resource, void *context);
typedef void (*MLAudioMasterVolumeChangedCallback)(float new_volume, void *context);
typedef void (*MLAudioOutputMuteChangedCallback)(bool is_muted, void *context);
typedef void (*MLAudioOutputDeviceChangedCallback)(MLAudioOutputDevice current_device, void *context);
typedef void (*MLAudioMicMuteCallback)(bool is_muted, void *context);
typedef void (*MLAudioTraitAnalysisCallback)(MLHandle handle, MLAudioTraitAnalysisTarget target, float value, void *context);
typedef void (*MLAudioSpectralAnalysisCallback)(MLHandle handle, MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysis values, void *context);
ML_API MLResult ML_CALL MLAudioCreateLoadedResource(int file, bool dynamic_decode, MLAudioResourceDiscardedCallback callback, void *context, MLHandle *out_resource);
ML_API MLResult ML_CALL MLAudioCreateStreamedResource(int file, MLAudioResourceDiscardedCallback callback, void *context, MLHandle *out_resource);
ML_API MLResult ML_CALL MLAudioCheckResource(MLHandle resource, bool *out_is_ready);
ML_API MLResult ML_CALL MLAudioGetResourceSize(MLHandle resource, uint32_t *out_size_in_bytes);
ML_API MLResult ML_CALL MLAudioRefreshResource(MLHandle resource, int file);
ML_API MLResult ML_CALL MLAudioDestroyResource(MLHandle resource);
ML_API MLResult ML_CALL MLAudioCreateSoundWithLoadedResource(MLHandle resource, bool auto_destroy, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioCreateSoundWithStreamedResource(MLHandle resource, bool auto_destroy, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioCreateSoundWithLoadedFile(int file, bool auto_destroy, bool dynamic_decode, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioCreateSoundWithStreamedFile(int file, bool auto_destroy, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioCreateSoundWithBufferedOutput(const MLAudioBufferFormat *format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void *context, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioDestroySound(MLHandle handle);
ML_API MLResult ML_CALL MLAudioStartSound(MLHandle handle);
ML_API MLResult ML_CALL MLAudioStopSound(MLHandle handle);
ML_API MLResult ML_CALL MLAudioPauseSound(MLHandle handle);
ML_API MLResult ML_CALL MLAudioResumeSound(MLHandle handle);
ML_API MLResult ML_CALL MLAudioGetSoundState(MLHandle handle, MLAudioState *out_state);
ML_API MLResult ML_CALL MLAudioGetSoundFormat(MLHandle handle, MLAudioBufferFormat *out_format);
ML_API MLResult ML_CALL MLAudioSetSoundEventCallback(MLHandle handle, MLAudioSoundEventCallback callback, void *context);
ML_API MLResult ML_CALL MLAudioSetMediaEventCallback(MLAudioMediaEventCallback callback, void *context);
ML_API MLResult ML_CALL MLAudioSetSoundVolumeLinear(MLHandle handle, float volume);
ML_API MLResult ML_CALL MLAudioGetSoundVolumeLinear(MLHandle handle, float *out_volume);
ML_API MLResult ML_CALL MLAudioSetSoundVolumeDb(MLHandle handle, float volume);
ML_API MLResult ML_CALL MLAudioGetSoundVolumeDb(MLHandle handle, float *out_volume);
ML_API MLResult ML_CALL MLAudioSetSoundPitch(MLHandle handle, float pitch);
ML_API MLResult ML_CALL MLAudioGetSoundPitch(MLHandle handle, float *out_pitch);
ML_API MLResult ML_CALL MLAudioSetSoundMute(MLHandle handle, bool is_muted);
ML_API MLResult ML_CALL MLAudioGetSoundMute(MLHandle handle, bool *out_is_muted);
ML_API MLResult ML_CALL MLAudioSetSoundBypassesMasterVolume(MLHandle handle, bool is_bypassing);
ML_API MLResult ML_CALL MLAudioGetSoundBypassesMasterVolume(MLHandle handle, bool *out_is_bypassing);
ML_API MLResult ML_CALL MLAudioSetSoundLooping(MLHandle handle, bool is_looping);
ML_API MLResult ML_CALL MLAudioGetSoundLooping(MLHandle handle, bool *out_is_looping);
ML_API MLResult ML_CALL MLAudioSetStreamedFileOffset(MLHandle handle, uint32_t offset_in_msec);
ML_API MLResult ML_CALL MLAudioGetStreamedFileOffset(MLHandle handle, uint32_t *out_offset_in_msec);
ML_API MLResult ML_CALL MLAudioGetOutputDevice(MLAudioOutputDevice *out_current_device);
ML_API MLResult ML_CALL MLAudioSetOutputDeviceCallback(MLAudioOutputDeviceChangedCallback callback, void *context);
ML_API MLResult ML_CALL MLAudioResetAcousticScene();
ML_API MLResult ML_CALL MLAudioBeginAcousticSceneUpdate();
ML_API MLResult ML_CALL MLAudioEndAcousticSceneUpdate();
ML_API MLResult ML_CALL MLAudioSetAcousticSceneMapEnable(bool is_enabled);
ML_API MLResult ML_CALL MLAudioGetAcousticSceneMapEnable(bool *out_is_enabled);
ML_API MLResult ML_CALL MLAudioSetAcousticSceneTransmissionDefault(const MLAudioMultibandLevel *transmission);
ML_API MLResult ML_CALL MLAudioGetAcousticSceneTransmissionDefault(MLAudioMultibandLevel *out_transmission);
ML_API MLResult ML_CALL MLAudioSetAcousticSceneDispersionDefault(const MLAudioDispersionProperties *properties);
ML_API MLResult ML_CALL MLAudioGetAcousticSceneDispersionDefault(MLAudioDispersionProperties *out_properties);
ML_API MLResult ML_CALL MLAudioSetAcousticSceneReverbDefault(const MLAudioReverbProperties *properties);
ML_API MLResult ML_CALL MLAudioGetAcousticSceneReverbDefault(MLAudioReverbProperties *out_properties);
ML_API MLResult ML_CALL MLAudioGetChangedAcousticMap(uint32_t prev_map_tag, uint8_t **out_map_data, uint32_t *out_map_size_in_bytes, uint32_t *out_map_tag);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundEnable(MLHandle handle, bool is_enabled);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundEnable(MLHandle handle, bool *out_is_enabled);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundPosition(MLHandle handle, uint32_t channel, const MLVec3f *position);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundPosition(MLHandle handle, uint32_t channel, MLVec3f *out_position);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundDirection(MLHandle handle, uint32_t channel, const MLQuaternionf *direction);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundDirection(MLHandle handle, uint32_t channel, MLQuaternionf *out_direction);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundBillboarding(MLHandle id, bool is_billboarding);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundBillboarding(MLHandle id, bool *out_is_billboarding);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundObstruction(MLHandle id, uint32_t channel, const MLAudioObstruction *left_ear, const MLAudioObstruction *right_ear);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundObstruction(MLHandle id, uint32_t channel, MLAudioObstruction *out_left_ear, MLAudioObstruction *out_right_ear);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundObstructionOverride(MLHandle id, const MLAudioMultibandLevel *override);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundObstructionOverride(MLHandle id, MLAudioMultibandLevel *out_override);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundDistanceProperties *properties);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundDistanceAttenuation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundDistanceProperties *out_properties);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundRadiation(MLHandle handle, uint32_t channel, const MLAudioSpatialSoundRadiationProperties *properties);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundRadiation(MLHandle handle, uint32_t channel, MLAudioSpatialSoundRadiationProperties *out_properties);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundDirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundIndirectLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundDispersionSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, const MLAudioMultibandLevel *level);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundReverbSendLevel(MLHandle handle, uint32_t channel, MLAudioMultibandLevel *out_level);
ML_API MLResult ML_CALL MLAudioSetSpatialSoundHeadRelative(MLHandle handle, bool is_head_relative);
ML_API MLResult ML_CALL MLAudioGetSpatialSoundHeadRelative(MLHandle handle, bool *out_is_head_relative);
ML_API MLResult ML_CALL MLAudioGetSpatialRaycastRequests(MLAudioRaycastRequest ** out_raycast_requests, uint32_t *out_request_count);
ML_API MLResult ML_CALL MLAudioSetSpatialRaycastResults(MLAudioRaycastResult * raycast_results, uint32_t result_count);
ML_API MLResult ML_CALL MLAudioGetBufferedOutputDefaults(uint32_t channel_count, uint32_t samples_per_second, float max_pitch_change, MLAudioBufferFormat *out_format, uint32_t *out_recommended_size_in_bytes, uint32_t *out_min_size_in_bytes);
ML_API MLResult ML_CALL MLAudioGetBufferedOutputLatency(MLHandle handle, float *out_latency_in_msec);
ML_API MLResult ML_CALL MLAudioGetBufferedOutputFramesPlayed(MLHandle handle, uint64_t *out_frames_played);
ML_API MLResult ML_CALL MLAudioGetOutputBuffer(MLHandle handle, MLAudioBuffer *out_buf);
ML_API MLResult ML_CALL MLAudioReleaseOutputBuffer(MLHandle handle);
ML_API MLResult ML_CALL MLAudioGetMasterVolume(float *out_volume);
ML_API MLResult ML_CALL MLAudioSetMasterVolumeCallback(MLAudioMasterVolumeChangedCallback callback, void *context);
ML_API MLResult ML_CALL MLAudioGetOutputMute(bool *out_is_muted);
ML_API MLResult ML_CALL MLAudioSetOutputMuteCallback(MLAudioOutputMuteChangedCallback callback, void *context);
ML_API MLResult ML_CALL MLAudioCreateInputFromMicCapture(MLAudioMicCaptureType mic_capture_type, const MLAudioBufferFormat *format, uint32_t buffer_size_in_bytes, MLAudioBufferCallback callback, void *context, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioCreateInputFromVirtualCapture(const MLAudioBufferFormat *format, uint32_t buffer_size, MLAudioBufferCallback callback, void *callback_context, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioCreateInputFromMixedCapture(const MLAudioBufferFormat *format, uint32_t buffer_size, MLAudioBufferCallback callback, void *callback_context, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioDestroyInput(MLHandle handle);
ML_API MLResult ML_CALL MLAudioStartInput(MLHandle handle);
ML_API MLResult ML_CALL MLAudioStopInput(MLHandle handle);
ML_API MLResult ML_CALL MLAudioGetInputState(MLHandle handle, MLAudioState *out_state);
ML_API MLResult ML_CALL MLAudioGetBufferedInputDefaults(uint32_t channel_count, uint32_t samples_per_second, MLAudioBufferFormat *out_format, uint32_t *out_recommended_size_in_bytes, uint32_t *out_min_size_in_bytes);
ML_API MLResult ML_CALL MLAudioGetBufferedInputLatency(MLHandle handle, float *out_latency_in_msec);
ML_API MLResult ML_CALL MLAudioGetInputBuffer(MLHandle handle, MLAudioBuffer *out_buf);
ML_API MLResult ML_CALL MLAudioReleaseInputBuffer(MLHandle handle);
ML_API MLResult ML_CALL MLAudioSetMicMute(bool is_muted);
ML_API MLResult ML_CALL MLAudioGetMicMute(bool *out_is_muted);
ML_API MLResult ML_CALL MLAudioSetMicMuteCallback(MLAudioMicMuteCallback callback, void *context);
ML_API MLResult ML_CALL MLAudioBeginTraitAnalysisFromMicCapture(MLAudioTraitAnalysisTarget target, MLAudioTraitAnalysisCallback callback, void *callback_context, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioGetTraitAnalysis(MLHandle handle, float *out_value);
ML_API MLResult ML_CALL MLAudioEndTraitAnalysis(MLHandle handle);
ML_API MLResult ML_CALL MLAudioBeginSpectralAnalysisFromMicCapture(MLAudioSpectralAnalysisTarget target, MLAudioSpectralAnalysisCallback callback, void *callback_context, MLHandle *out_handle);
ML_API MLResult ML_CALL MLAudioGetSpectralAnalysis(MLHandle handle, MLAudioSpectralAnalysis *out_values);
ML_API MLResult ML_CALL MLAudioEndSpectralAnalysis(MLHandle handle);
ML_EXTERN_C_END