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:

• http://tizen.org/feature/microphone
  
• http://tizen.org/feature/multi_assistant
  It is recommended to use features in your application for reliability.
  You can check if the device supports the related features for this API by using System Information, and control your application's actions accordingly.
  To ensure your application is running only on devices with specific features, please define the features in your manifest file using the manifest editor in the SDK.
  More details on using features in your application can be found in the feature element description.

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]	previous	The previous active state
[in]	current	The current active state
[in]	user_data	The 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]	handle	The handle of the assistant
[in]	user_data	The 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]	event	The audio streaming event
[in]	buffer	The audio streaming data
[in]	len	The length of the audio streaming data
[in]	user_data	The user data passed from the callback registration function

See also:

ma_set_audio_streaming_cb()

ma_unset_audio_streaming_cb()

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.

Since :

5.5

Parameters:

[in]	section	The current section information of audio streaming data
[in]	user_data	The 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]	reason	The error reason
[in]	user_data	The 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]	previous	The previous language
[in]	current	The current language
[in]	user_data	The 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_id	The application id of current preprocessing voice assistant
[in]	user_data	The 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]	previous	The previous state
[in]	current	The current state
[in]	user_data	The 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]	command	The wakeup engine specific command
[in]	user_data	The user data passed from the callback registration function

---

Enumeration Type Documentation

enum ma_active_state_e

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

enum ma_asr_result_event_e

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

enum ma_audio_channel_e

Enumerations for audio channels.

Since :

5.0

Enumerator:

MA_AUDIO_CHANNEL_MONO	1 channel, mono
MA_AUDIO_CHANNEL_STEREO	2 channels, stereo

enum ma_audio_streaming_data_section_e

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

enum ma_audio_streaming_data_type_e

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

enum ma_audio_streaming_event_e

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

enum ma_audio_type_e

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

enum ma_preprocessing_allow_mode_e

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

enum ma_recognition_result_event_e

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

enum ma_voice_feedback_state_e

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