Version: 21 Aug 2024

ml_voice.h

Classes

	Name
struct	MLInputVoiceAppIntentSlot A structure containing voice app-intent slot in voice event.
struct	MLVoiceIntentEvent A structure containing voice intent event.
struct	MLVoiceIntentCallbacks A structure containing callbacks for voice intent events.
struct	MLVoiceIntentSettings A structure containing settings for voice app intent.

Types

	Name
typedef struct MLInputVoiceAppIntentSlot	MLInputVoiceAppIntentSlot A structure containing voice app-intent slot in voice event.
typedef struct MLVoiceIntentEvent	MLVoiceIntentEvent A structure containing voice intent event.
typedef struct MLVoiceIntentCallbacks	MLVoiceIntentCallbacks A structure containing callbacks for voice intent events.
typedef struct MLVoiceIntentSettings	MLVoiceIntentSettings A structure containing settings for voice app intent.

Enums

	Name
enum	Anonymous Enum 30 { MLResultAPIPrefix_Voice = ( 0xbe7a << 16) }
enum	MLVoiceResult { MLVoiceResult_IntentDisabled = MLResultAPIPrefix_Voice, MLVoiceResult_Ensure32Bits = 0x7FFFFFFF } Return values for Voice API calls.
enum	MLVoiceState { MLVoiceState_IntentHotwordDetected = 0, MLVoiceState_IntentSessionEnded = 1, MLVoiceState_IntentSessionEndedAborted = 2, MLVoiceState_IntentSessionEndedNoIntent = 3, MLVoiceState_IntentSessionEndedTimeout = 4, MLVoiceState_IntentSessionEndedError = 5, MLVoiceState_IntentReady = 6, MLVoiceState_IntentNotAvailable = 7, MLVoiceState_IntentInvalidAppIntent = 8, MLVoiceState_Ensure32Bits = 0x7FFFFFFF } Voice state in voice event.
enum	MLVoiceIntentNoIntentReason { MLVoiceIntentNoIntentReason_NoReason = 0, MLVoiceIntentNoIntentReason_Silence = 1, MLVoiceIntentNoIntentReason_NoMatch = 2, MLVoiceIntentNoIntentReason_Ensure32Bits = 0x7FFFFFFF } No intent reason code in voice event.

Functions

	Name
void	MLVoiceIntentCallbacksInit(MLVoiceIntentCallbacks * inout_callbacks) Initializes default values for MLVoiceIntentCallbacks.
void	MLVoiceIntentSettingsInit(MLVoiceIntentSettings * inout_settings) Initializes default values for MLVoiceIntentSettings.
MLResult	MLVoiceIntentCreate(MLHandle * out_handle) Creates a voice intent client.
MLResult	MLVoiceIntentDestroy(MLHandle handle) Destroys a voice intent client.
MLResult	MLVoiceIntentConfigureSettings(MLHandle handle, const MLVoiceIntentSettings * voice_settings) Sets the settings for voice intent events.
MLResult	MLVoiceIntentSetCallbacks(MLHandle handle, const MLVoiceIntentCallbacks voice_callbacks, void user_data) Sets the callbacks for voice intent events.
MLResult	MLVoiceIntentStartProcessing(MLHandle handle) Starts voice intent processing.
MLResult	MLVoiceIntentStopProcessing(MLHandle handle) Stops voice intent processing.
MLResult	MLVoiceIntentIsEnabled(MLHandle handle, bool * out_is_enabled) Checks voice intent feature is enabled in the system.
const char *	MLVoiceGetResultString(MLResult result) Returns an ASCII string for MLVoiceResult and MLResult codes.

Enums Documentation

Anonymous Enum 30

Enumerator	Value	Description
MLResultAPIPrefix_Voice	( 0xbe7a << 16)	Defines the prefix for MLVoiceResult codes.

MLVoiceResult

Enumerator	Value	Description
MLVoiceResult_IntentDisabled	MLResultAPIPrefix_Voice	Operation failed because a required voice intent feature is disabled in system settings.
MLVoiceResult_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Return values for Voice API calls.

API Level:

MLVoiceState

Enumerator	Value	Description
MLVoiceState_IntentHotwordDetected	0	Intent hotword detected, Automatic Speech Recognition (ASR) session is going to start.
MLVoiceState_IntentSessionEnded	1	Voice UI is stopped, ASR session is going to stop.
MLVoiceState_IntentSessionEndedAborted	2	ASR session is stopped due to abort.
MLVoiceState_IntentSessionEndedNoIntent	3	ASR session is stopped without detecting an intent.
MLVoiceState_IntentSessionEndedTimeout	4	ASR session is stopped due to timeout.
MLVoiceState_IntentSessionEndedError	5	ASR session is stopped due to error.
MLVoiceState_IntentReady	6	Intent mode is started and ready.
MLVoiceState_IntentNotAvailable	7	Intent mode is stopped and not available.
MLVoiceState_IntentInvalidAppIntent	8	Invalid app intent, double check content of JSON submitted with MLVoiceIntentConfigureSettings(). Please refer to Voice Intent Development Toolkit from Magic Leap Hub to generate app intent content.
MLVoiceState_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

Voice state in voice event.

API Level:

MLVoiceIntentNoIntentReason

Enumerator	Value	Description
MLVoiceIntentNoIntentReason_NoReason	0	In case of success.
MLVoiceIntentNoIntentReason_Silence	1	When the MLVoiceState in MLVoiceIntentEvent is either MLVoiceState_IntentSessionEndedTimeout or MLVoiceState_IntentSessionEndedError.
MLVoiceIntentNoIntentReason_NoMatch	2	When the MLVoiceState in MLVoiceIntentEvent is MLVoiceState_IntentSessionEndedNoIntent.
MLVoiceIntentNoIntentReason_Ensure32Bits	0x7FFFFFFF	Ensure enum is represented as 32 bits.

No intent reason code in voice event.

API Level:

Types Documentation

MLInputVoiceAppIntentSlot

typedef struct MLInputVoiceAppIntentSlot MLInputVoiceAppIntentSlot;

A structure containing voice app-intent slot in voice event.

More Info

API Level:

MLVoiceIntentEvent

typedef struct MLVoiceIntentEvent MLVoiceIntentEvent;

A structure containing voice intent event.

More Info

API Level:

MLVoiceIntentCallbacks

typedef struct MLVoiceIntentCallbacks MLVoiceIntentCallbacks;

A structure containing callbacks for voice intent events.

The final parameter to all the callbacks is a void *, which will point to whatever payload data the user provides in MLVoiceIntentSetCallbacks. Individual callbacks which are not required by the client can be NULL.

This structure must be initialized by calling MLVoiceIntentCallbacksInit() before use.

More Info

API Level:

MLVoiceIntentSettings

typedef struct MLVoiceIntentSettings MLVoiceIntentSettings;

A structure containing settings for voice app intent.

This structure must be initialized by calling MLVoiceIntentSettingsInit() before use.

More Info

API Level:

Functions Documentation

MLVoiceIntentCallbacksInit

static inline void MLVoiceIntentCallbacksInit(
    MLVoiceIntentCallbacks * inout_callbacks
)

Initializes default values for MLVoiceIntentCallbacks.

Parameters


MLVoiceIntentCallbacks *	inout_callbacks	The object to initialize with default settings.

Required Permissions:

None

API Level:

MLVoiceIntentSettingsInit

static inline void MLVoiceIntentSettingsInit(
    MLVoiceIntentSettings * inout_settings
)

Initializes default values for MLVoiceIntentSettings.

Parameters


MLVoiceIntentSettings *	inout_settings	The object to initialize with default settings.

Required Permissions:

None

API Level:

MLVoiceIntentCreate

MLResult MLVoiceIntentCreate(
    MLHandle * out_handle
)

Creates a voice intent client.

Parameters


MLHandle *	out_handle	A handle to the created voice intent client. Only valid if the return value is MLResult_Ok.

Returns


MLResult	MLResult_InvalidParam	Failed to create the voice intent client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully created the voice intent client.
MLResult	MLResult_PermissionDenied	Failed to create client due to missing permission.

Required Permissions:

com.magicleap.permission.VOICE_INPUT (protection level: dangerous)

API Level:

MLVoiceIntentDestroy

MLResult MLVoiceIntentDestroy(
    MLHandle handle
)

Destroys a voice intent client.

Parameters


MLHandle	handle	MLHandle to the voice intent client to destroy.

Returns


MLResult	MLResult_InvalidParam	Failed to destroy the voice intent client due to an invalid input parameter.
MLResult	MLResult_Ok	Successfully destroyed the voice intent client.

Required Permissions:

None

MLVoiceIntentConfigureSettings

MLResult MLVoiceIntentConfigureSettings(
    MLHandle handle,
    const MLVoiceIntentSettings * voice_settings
)

Sets the settings for voice intent events.

Parameters


MLHandle	handle	Handle to the voice intent client.
const MLVoiceIntentSettings *	voice_settings	Pointer to MLVoiceIntentSettings structure.

Returns


MLResult	MLResult_InvalidParam	Failed to set settings for voice intent events due to an invalid param.
MLResult	MLResult_Ok	Successfully set settings for voice intent events.
MLResult	MLVoiceResult_IntentDisabled	Failed to set the settings because required voice intent feature is disabled.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

App needs to call MLVoiceIntentConfigureSettings at least once before it calls MLVoiceIntentStartProcessing. App can call MLVoiceIntentConfigureSettings anytime it needs to update the voice intents. But such call will trigger updating intent grammar inside speech engine, which may result in a short delay (could be a few seconds depending on the device's workload). So it is not recommended to call the function frequently.

API Level:

MLVoiceIntentSetCallbacks

MLResult MLVoiceIntentSetCallbacks(
    MLHandle handle,
    const MLVoiceIntentCallbacks * voice_callbacks,
    void * user_data
)

Sets the callbacks for voice intent events.

Parameters


MLHandle	handle	Handle to the voice intent client.
const MLVoiceIntentCallbacks *	voice_callbacks	Pointer to MLVoiceIntentCallbacks structure. Set this to NULL to unregister callbacks.
void *	user_data	Pointer to user payload data (can be NULL).

Returns


MLResult	MLResult_InvalidParam	Failed to set callbacks for voice intent events due to an invalid param.
MLResult	MLResult_Ok	Successfully set callbacks for voice intent events.
MLResult	MLVoiceResult_IntentDisabled	Failed to set the callbacks because required voice intent feature is disabled in system settings.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

API Level:

MLVoiceIntentStartProcessing

MLResult MLVoiceIntentStartProcessing(
    MLHandle handle
)

Starts voice intent processing.

Parameters


MLHandle	handle	Handle to the voice intent client.

Returns


MLResult	MLResult_InvalidParam	Failed to start processing due to an invalid parameter.
MLResult	MLResult_Ok	Successfully start intent processing.
MLResult	MLVoiceResult_IntentDisabled	Failed to start intent processing because required voice intent feature is disabled in system settings.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

This API call affects the system voice service.

NOTE: If your application is processing voice intents make sure to call MLVoiceIntentStopProcessing when application loses focus and MLVoiceIntentStartProcessing when application gains focus to allow for uninterrupted processing of the voice intents.

API Level:

MLVoiceIntentStopProcessing

MLResult MLVoiceIntentStopProcessing(
    MLHandle handle
)

Stops voice intent processing.

Parameters


MLHandle	handle	Handle to the voice intent client.

Returns


MLResult	MLResult_InvalidParam	Failed to stop processing due to an invalid parameter.
MLResult	MLResult_Ok	Successfully stop intent processing.
MLResult	MLVoiceResult_IntentDisabled	Failed to stop intent processing because required voice intent feature is disabled in system settings.
MLResult	MLResult_UnspecifiedFailure	The operation failed with an unspecified error.

Required Permissions:

None

This API call affects the system voice service.

API Level:

MLVoiceIntentIsEnabled

MLResult MLVoiceIntentIsEnabled(
    MLHandle handle,
    bool * out_is_enabled
)

Checks voice intent feature is enabled in the system.

Parameters


MLHandle	handle	Handle to the voice intent client.
bool *	out_is_enabled	Returns status whether voice intent feature is enabled in system settings.

Returns


MLResult	MLResult_InvalidParam	Failed to check due to an invalid parameter.
MLResult	MLResult_Ok	The API call completed successfuly.

Required Permissions:

None

API Level:

MLVoiceGetResultString

const char * MLVoiceGetResultString(
    MLResult result
)

Returns an ASCII string for MLVoiceResult and MLResult codes.

Parameters


MLResult	result	The input MLResult enum from MLVoice functions.

Required Permissions:

None

Return: ASCII string containing readable version of result code.

API Level:

Source code

// %BANNER_BEGIN%
// ---------------------------------------------------------------------
// %COPYRIGHT_BEGIN%
// Copyright (c) 2022 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>

ML_EXTERN_C_BEGIN

enum {
  MLResultAPIPrefix_Voice = MLRESULT_PREFIX(0xbe7a)
};

typedef enum MLVoiceResult {
  MLVoiceResult_IntentDisabled = MLResultAPIPrefix_Voice,
  MLVoiceResult_Ensure32Bits = 0x7FFFFFFF
} MLVoiceResult;

typedef enum MLVoiceState {
  MLVoiceState_IntentHotwordDetected = 0,
  MLVoiceState_IntentSessionEnded = 1,
  MLVoiceState_IntentSessionEndedAborted = 2,
  MLVoiceState_IntentSessionEndedNoIntent = 3,
  MLVoiceState_IntentSessionEndedTimeout = 4,
  MLVoiceState_IntentSessionEndedError = 5,
  MLVoiceState_IntentReady = 6,
  MLVoiceState_IntentNotAvailable = 7,
  MLVoiceState_IntentInvalidAppIntent = 8,

  MLVoiceState_Ensure32Bits = 0x7FFFFFFF
} MLVoiceState;


typedef enum MLVoiceIntentNoIntentReason {
  MLVoiceIntentNoIntentReason_NoReason = 0,
  MLVoiceIntentNoIntentReason_Silence = 1,
  MLVoiceIntentNoIntentReason_NoMatch = 2,

  MLVoiceIntentNoIntentReason_Ensure32Bits = 0x7FFFFFFF
} MLVoiceIntentNoIntentReason;

typedef struct MLInputVoiceAppIntentSlot {
  const char* slot_name;
  const char* slot_value;
} MLInputVoiceAppIntentSlot;

typedef struct MLVoiceIntentEvent {
  bool is_success;
  MLVoiceState state;
  MLVoiceIntentNoIntentReason no_intent_reason;
  const char* text;
  uint32_t intent_id;
  MLInputVoiceAppIntentSlot* app_intent_slots;
  uint32_t app_intent_slot_count;
} MLVoiceIntentEvent;

typedef struct MLVoiceIntentCallbacks {
  uint32_t version;
  void (*on_voice_event)(const MLVoiceIntentEvent* event, void* data);
} MLVoiceIntentCallbacks;

ML_STATIC_INLINE void MLVoiceIntentCallbacksInit(MLVoiceIntentCallbacks* inout_callbacks) {
  if (inout_callbacks) {
    inout_callbacks->version = 2u;
    inout_callbacks->on_voice_event = NULL;
  }
}

typedef struct MLVoiceIntentSettings {
  uint32_t version;
  const char* app_intent;
} MLVoiceIntentSettings;

ML_STATIC_INLINE void MLVoiceIntentSettingsInit(MLVoiceIntentSettings* inout_settings) {
  if (inout_settings) {
    inout_settings->version = 1u;
    inout_settings->app_intent = NULL;
  }
}

ML_API MLResult ML_CALL MLVoiceIntentCreate(MLHandle *out_handle);

ML_API MLResult ML_CALL MLVoiceIntentDestroy(MLHandle handle);

ML_API MLResult ML_CALL MLVoiceIntentConfigureSettings(MLHandle handle, const MLVoiceIntentSettings* voice_settings);

ML_API MLResult ML_CALL MLVoiceIntentSetCallbacks(MLHandle handle, const MLVoiceIntentCallbacks* voice_callbacks, void* user_data);

ML_API MLResult ML_CALL MLVoiceIntentStartProcessing(MLHandle handle);

ML_API MLResult ML_CALL MLVoiceIntentStopProcessing(MLHandle handle);

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

ML_API const char *ML_CALL MLVoiceGetResultString(MLResult result);
ML_EXTERN_C_END

ml_voice.h

Classes​

Types​

Enums​

Functions​

Enums Documentation​

Anonymous Enum 30​

MLVoiceResult​

MLVoiceState​

MLVoiceIntentNoIntentReason​

Types Documentation​

MLInputVoiceAppIntentSlot​

MLVoiceIntentEvent​

MLVoiceIntentCallbacks​

MLVoiceIntentSettings​

Functions Documentation​

MLVoiceIntentCallbacksInit​

MLVoiceIntentSettingsInit​

MLVoiceIntentCreate​

MLVoiceIntentDestroy​

MLVoiceIntentConfigureSettings​

MLVoiceIntentSetCallbacks​

MLVoiceIntentStartProcessing​

MLVoiceIntentStopProcessing​

MLVoiceIntentIsEnabled​

MLVoiceGetResultString​

Source code​

Classes

Types

Enums

Functions

Enums Documentation

Anonymous Enum 30

MLVoiceResult

MLVoiceState

MLVoiceIntentNoIntentReason

Types Documentation

MLInputVoiceAppIntentSlot

MLVoiceIntentEvent

MLVoiceIntentCallbacks

MLVoiceIntentSettings

Functions Documentation

MLVoiceIntentCallbacksInit

MLVoiceIntentSettingsInit

MLVoiceIntentCreate

MLVoiceIntentDestroy

MLVoiceIntentConfigureSettings

MLVoiceIntentSetCallbacks

MLVoiceIntentStartProcessing

MLVoiceIntentStopProcessing

MLVoiceIntentIsEnabled

MLVoiceGetResultString

Source code