Tizen Native API  5.5
Multi assistant

The Multi assistant provides functions for supporting users to use several assistants.

Required Header

#include <multi_assistant.h>

State Transitions

FUNCTION PRE-STATE POST-STATE SYNC TYPE
ma_initialize() None Initialized SYNC
ma_deinitialize() Initialized None SYNC
ma_prepare() Initialized Ready ASYNC
ma_unprepare() Ready Initialized SYNC

State Dependent Function Calls

The following table shows state-dependent function calls. It is forbidden to call functions listed below in wrong states. Violation of this rule may result in an unpredictable behavior.

FUNCTION VALID STATES DESCRIPTION
ma_initialize() None All functions must be called after ma_initialize()
ma_deinitialize() Initialized, Ready This function should be called when finished using multi-assistant
ma_prepare() Initialized This function works asynchronously. If service start is failed, application gets the error callback.
ma_unprepare() Ready
ma_get_state() Initialized, Ready
ma_get_current_language() Initialized, Ready
ma_get_recording_audio_format() Ready
ma_send_asr_result() Ready
ma_send_result() Ready
ma_send_recognition_result() Ready
ma_start_receiving_audio_streaming_data() Ready
ma_stop_receiving_audio_streaming_data() Ready
ma_update_voice_feedback_state() Ready
ma_send_assistant_specific_command() Ready
ma_assistant_info_foreach_assistants() Ready
ma_assistant_info_get_app_id() Ready
ma_assistant_info_get_enabled_status() Ready
ma_get_recording_audio_source_type() Ready
ma_set_background_volume() Ready
ma_set_preprocessing_allow_mode() Ready
ma_send_preprocessing_result() Ready
ma_set_wake_word_audio_require_flag() Ready
ma_set_state_changed_cb()
ma_unset_state_changed_cb()
ma_set_error_cb()
ma_unset_error_cb() ma_set_language_changed_cb()
ma_unset_language_changed_cb() ma_set_audio_streaming_cb()
ma_unset_audio_streaming_cb() ma_set_active_state_changed_cb()
ma_unset_active_state_changed_cb() ma_set_wakeup_engine_command_cb()
ma_unset_wakeup_engine_command_cb() ma_set_preprocessing_information_changed_cb()
ma_unset_preprocessing_information_changed_cb() ma_set_audio_streaming_data_section_changed_cb()
ma_unset_audio_streaming_data_section_changed_cb()
Initialized All callback function should be registered in Initialized state

Related Features

This API is related with the following features:

Typedefs

typedef void(* ma_state_changed_cb )(ma_state_e previous, ma_state_e current, void *user_data)
 Called when the client state is changed.
typedef void(* ma_error_cb )(ma_error_e reason, void *user_data)
 Called when the error is occurred.
typedef void(* ma_language_changed_cb )(const char *previous, const char *current, void *user_data)
 Called when the default language is changed.
typedef void(* ma_audio_streaming_cb )(ma_audio_streaming_event_e event, char *buffer, int len, void *user_data)
 Called when the multi-assistant service sends audio streaming.
typedef void(* ma_active_state_changed_cb )(ma_active_state_e previous, ma_active_state_e current, void *user_data)
 Called when the active state is changed.
typedef void(* ma_wakeup_engine_command_cb )(const char *command, void *user_data)
 Called when a wakeup engine specific command is retrieved.
typedef void * ma_assistant_info_h
 A handle to get assistant information.
typedef int(* ma_assistant_info_list_cb )(ma_assistant_info_h handle, void *user_data)
 Called whenever to get the assistant information of each installed assistant.
typedef void(* ma_preprocessing_information_changed_cb )(const char *app_id, void *user_data)
 Called when the preprocessing information is changed.
typedef void(* ma_audio_streaming_data_section_changed_cb )(ma_audio_streaming_data_section_e section, void *user_data)
 Called when the section of audio streaming data is changed.

Typedef Documentation

typedef void(* ma_active_state_changed_cb)(ma_active_state_e previous, ma_active_state_e current, void *user_data)

Called when the active state is changed.

Since :
5.5
Parameters:
[in]previousThe previous active state
[in]currentThe current active state
[in]user_dataThe user data passed from the callback registration function
typedef void* ma_assistant_info_h

A handle to get assistant information.

Since :
5.5
typedef int(* ma_assistant_info_list_cb)(ma_assistant_info_h handle, void *user_data)

Called whenever to get the assistant information of each installed assistant.

Since :
5.5
Remarks:
The handle should not be released.
The handle is managed by the platform and will be released when application exits.
Parameters:
[in]handleThe handle of the assistant
[in]user_dataThe user data passed from the callback registration function
typedef void(* ma_audio_streaming_cb)(ma_audio_streaming_event_e event, char *buffer, int len, void *user_data)

Called when the multi-assistant service sends audio streaming.

Since :
5.0
Remarks:
The buffer should not be released and can be used only in the callback. To use outside, make a copy.
Parameters:
[in]eventThe audio streaming event
[in]bufferThe audio streaming data
[in]lenThe length of the audio streaming data
[in]user_dataThe user data passed from the callback registration function
See also:
ma_set_audio_streaming_cb()
ma_unset_audio_streaming_cb()

Called when the section of audio streaming data is changed.

Since :
5.5
Parameters:
[in]sectionThe current section information of audio streaming data
[in]user_dataThe user data passed from the callback registration function
typedef void(* ma_error_cb)(ma_error_e reason, void *user_data)

Called when the error is occurred.

The following error codes can be received:
MA_ERROR_NONE: Success
MA_ERROR_OUT_OF_MEMORY: Out of Memory
MA_ERROR_IO_ERROR: I/O error
MA_ERROR_INVALID_PARAMETER: Invalid parameter
MA_ERROR_TIMED_OUT: No answer from service
MA_ERROR_RECORDER_BUSY: Busy recorder
MA_ERROR_PERMISSION_DENIED: Permission denied
MA_ERROR_NOT_SUPPORTED: Multi-assistant NOT supported
MA_ERROR_INVALID_STATE: Invalid state
MA_ERROR_INVALID_LANGUAGE: Invalid language
MA_ERROR_ENGINE_NOT_FOUND: No available engine
MA_ERROR_OPERATION_FAILED: Operation failed
MA_ERROR_SERVICE_RESET: Service daemon reset
MA_ERROR_NOT_SUPPORTED_FEATURE: Not supported feature of current engine

Since :
5.0
Parameters:
[in]reasonThe error reason
[in]user_dataThe user data passed from the callback registration function
typedef void(* ma_language_changed_cb)(const char *previous, const char *current, void *user_data)

Called when the default language is changed.

Since :
5.0
Remarks:
The previous can be used only in the callback. To use outside, make a copy. The current can be used only in the callback. To use outside, make a copy.
Parameters:
[in]previousThe previous language
[in]currentThe current language
[in]user_dataThe user data passed from the callback registration function
See also:
ma_set_language_changed_cb()
ma_unset_language_changed_cb()
typedef void(* ma_preprocessing_information_changed_cb)(const char *app_id, void *user_data)

Called when the preprocessing information is changed.

Since :
5.5
Remarks:
The app_id should not be released and can be used only in the callback. To use outside, make a copy.
If the app_id is NULL, it means there is no preprocessing voice assistant available.
Parameters:
[in]app_idThe application id of current preprocessing voice assistant
[in]user_dataThe user data passed from the callback registration function
typedef void(* ma_state_changed_cb)(ma_state_e previous, ma_state_e current, void *user_data)

Called when the client state is changed.

Since :
5.0
Parameters:
[in]previousThe previous state
[in]currentThe current state
[in]user_dataThe user data passed from the callback registration function
typedef void(* ma_wakeup_engine_command_cb)(const char *command, void *user_data)

Called when a wakeup engine specific command is retrieved.

Since :
5.5
Remarks:
The command should not be released and can be used only in the callback. To use outside, make a copy.
Parameters:
[in]commandThe wakeup engine specific command
[in]user_dataThe user data passed from the callback registration function

Enumeration Type Documentation

Enumerations for multi-assistant active state.

Since :
5.5
Enumerator:
MA_ACTIVE_STATE_INACTIVE 

'Inactive' state

MA_ACTIVE_STATE_ACTIVE 

'Active' state

MA_ACTIVE_STATE_PREPROCESSING 

'Preprocessing' state

Enumerations for ASR result events.

Since :
5.0
Enumerator:
MA_ASR_RESULT_EVENT_PARTIAL_RESULT 

ASR result event for partial result

MA_ASR_RESULT_EVENT_FINAL_RESULT 

ASR result event for final result

MA_ASR_RESULT_EVENT_ERROR 

ASR result event for error

Enumerations for audio channels.

Since :
5.0
Enumerator:
MA_AUDIO_CHANNEL_MONO 

1 channel, mono

MA_AUDIO_CHANNEL_STEREO 

2 channels, stereo

Enumerations for section information of audio streaming data.

Since :
5.5
Enumerator:
MA_AUDIO_STREAMING_DATA_SECTION_UTTERANCE 

Utterance section started

MA_AUDIO_STREAMING_DATA_SECTION_WAKE_WORD 

Wake word section started

Enumerations for speech data types.

Since :
5.5
Enumerator:
MA_AUDIO_STREAMING_DATA_TYPE_CURRENT_UTTERANCE 

Current utterance

MA_AUDIO_STREAMING_DATA_TYPE_PREVIOUS_UTTERANCE 

Previous utterance

MA_AUDIO_STREAMING_DATA_TYPE_FOLLOW_UP_SPEECH 

Follow-up speech

Enumerations for multi-assistant audio streaming events.

Since :
5.0
Enumerator:
MA_AUDIO_STREAMING_EVENT_FAIL 

Failed

MA_AUDIO_STREAMING_EVENT_START 

Start event

MA_AUDIO_STREAMING_EVENT_CONTINUE 

Continue event

MA_AUDIO_STREAMING_EVENT_FINISH 

Finish event

Enumerations for audio types.

Since :
5.0
Enumerator:
MA_AUDIO_TYPE_PCM_S16_LE 

Signed 16bit audio type, Little endian

MA_AUDIO_TYPE_PCM_U8 

Unsigned 8bit audio type

enum ma_error_e

Enumerations for multi-assistant error codes.

Since :
5.0
Enumerator:
MA_ERROR_NONE 

Successful

MA_ERROR_OUT_OF_MEMORY 

Out of Memory

MA_ERROR_IO_ERROR 

I/O error

MA_ERROR_INVALID_PARAMETER 

Invalid parameter

MA_ERROR_TIMED_OUT 

No answer from service

MA_ERROR_RECORDER_BUSY 

Busy recorder

MA_ERROR_PERMISSION_DENIED 

Permission denied

MA_ERROR_NOT_SUPPORTED 

Multi-assistant NOT supported

MA_ERROR_INVALID_STATE 

Invalid state

MA_ERROR_INVALID_LANGUAGE 

Invalid language

MA_ERROR_ENGINE_NOT_FOUND 

No available engine

MA_ERROR_OPERATION_FAILED 

Operation failed

MA_ERROR_SERVICE_RESET 

Service daemon reset

MA_ERROR_NOT_SUPPORTED_FEATURE 

Not supported feature of current engine

Enumerations for allowing preprocessing by other voice assistants.

Since :
5.5
Enumerator:
MA_PREPROCESSING_ALLOW_NONE 

No preprocessing allowed

MA_PREPROCESSING_ALLOW_UTTERANCE 

Preprocessing allowed for utterance audio only

MA_PREPROCESSING_ALLOW_FOLLOW_UP 

Preprocessing allowed for follow-up audio only

MA_PREPROCESSING_ALLOW_ALL 

Preprocessing allowed for all audio

Enumerations for recognition result events.

Since :
5.5
Enumerator:
MA_RECOGNITION_RESULT_EVENT_SUCCESS 

Recognition succeeded

MA_RECOGNITION_RESULT_EVENT_EMPTY_TEXT 

No text result recognized

MA_RECOGNITION_RESULT_EVENT_ERROR 

Unknown error occurred

MA_RECOGNITION_RESULT_EVENT_FALSE_TRIGGER 

Turned out to be a false trigger

enum ma_state_e

Enumerations for multi-assistant client state.

Since :
5.0
Enumerator:
MA_STATE_NONE 

'None' state

MA_STATE_INITIALIZED 

'Initialized' state

MA_STATE_READY 

'Ready' state

Enumerations for individual assistant's voice feedback state.

Since :
5.5
Enumerator:
MA_VOICE_FEEDBACK_STATE_NONE 

No voice feedback being provided

MA_VOICE_FEEDBACK_STATE_STARTED 

Voice feedback being provided