Tizen Native API  6.0
Multi assistant

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

Required Header

#include <multi_assistant.h>

Client State Transitions

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

Client State Dependent Function Calls

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

FUNCTION VALID CLIENT 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 client 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 void(* ma_service_state_changed_cb )(ma_service_state_e previous, ma_service_state_e current, void *user_data)
 Called when the service state is changed.
typedef void(* ma_voice_key_status_changed_cb )(ma_voice_key_status_e status, void *user_data)
 Called when the multi-assistant service sends voice key status change event.

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_service_state_changed_cb)(ma_service_state_e previous, ma_service_state_e current, void *user_data)

Called when the service state is changed.

Since :
6.0
Parameters:
[in]previousThe previous service state
[in]currentThe new service state
[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_voice_key_status_changed_cb)(ma_voice_key_status_e status, void *user_data)

Called when the multi-assistant service sends voice key status change event.

Since :
6.0
Parameters:
[in]statusThe change of voice key status
[in]user_dataThe user data passed from the callback registration function
See also:
ma_set_voice_key_status_changed_cb()
ma_unset_voice_key_status_changed_cb()
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

Enumerations for multi-assistant service state.

Since :
6.0
Enumerator:
MA_SERVICE_STATE_INACTIVE 

'Inactive' state

MA_SERVICE_STATE_LISTENING 

'Listening' state

MA_SERVICE_STATE_UTTERANCE 

'Utterance' state

MA_SERVICE_STATE_PROCESSING 

'Processing' state

MA_SERVICE_STATE_VOICE_FEEDBACK 

'VoiceFeedback' state

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

Enumerations for voice key status change.

When the voice key is pressed, the "pressed" state is reported. If the voice key gets released within the timeout value for tap events, the voice key status value will be reported as "released after tap". Otherwise, "released after push" will be reported.

Since :
6.0
Enumerator:
MA_VOICE_KEY_STATUS_PRESSED 

'Pressed' state

MA_VOICE_KEY_STATUS_RELEASED_AFTER_PUSH 

'Released' state after push

MA_VOICE_KEY_STATUS_RELEASED_AFTER_TAP 

'Released' state after tap