|
Tizen Native API
4.0
|
The Voice control engine APIs provide functions to operate Voice-Control Engine.
Required Header
#include <vce.h>
Overview
Voice-Control-Engine (below VCE) is an engine for recognize the sound data recorded by the user and send the result as a predefined command. Using the Voice control engine APIs, VCE developers can provide VCE service users, who want to apply VCE, with functions necessary to operate the engine. According to the indispensability of VCE services, there are two ways to provide them to the users.
A. Required VCE services
These services are indispensable to operate VCE. Therefore, the VCE developers MUST implement callback functions corresponding to the required VCE services. The following is a list of the callback functions.
| vce_get_info_cb() | Called when the engine service user requests the basic information of VCE. |
| vce_get_recording_format_cb() | Called when the engine service user requests the recording format of VCE. |
| vce_foreach_supported_languages_cb() | Called when the engine service user retrieves all supported languages of VC engine. |
| vce_is_language_supported_cb() | Called when the engine service user retrieves all supported languages of VCE. |
| vce_initialize_cb() | Called when the engine service user initializes VCE. |
| vce_deinitialize_cb() | Called when the engine service user deinitializes VCE. |
| vce_set_language_cb() | Called when the engine service user sets language. |
| vce_set_commands_cb() | Called when the engine service user sets command list before recognition. |
| vce_unset_commands_cb() | Called when the engine service user unsets command list for reset. |
| vce_start_cb() | Called when the engine service user starts recognition. |
| vce_set_recording_data_cb() | Called when the engine service user sets recording data for speech recognition from recorder. |
| vce_stop_cb() | Called when the engine service user stops to get the result of recognition. |
| vce_cancel_cb() | Called when the engine service user cancels the recognition process. |
| vce_set_audio_type_cb() | Called when the engine service user sets audio recording type. |
| vce_set_server_dialog_cb() | Called when the engine service user sets app id which is want to ask server dialog. |
| vce_set_domain_cb() | Called when the engine service user sets domain (agent or device type). |
| vce_process_text_cb() | Called when the engine service user requests process text. |
| vce_process_list_event_cb() | Called when the engine service user requests list event. |
| vce_process_haptic_event_cb() | Called when the engine service user requests haptic event. |
The VCE developers can register the above callback functions at a time with using a structure 'vce_request_callback_s' and an API 'vce_main()'. To operate VCE, the following steps should be used:
1. Create a structure 'vce_request_callback_s' 2. Implement callback functions. (NOTE that the callback functions should return appropriate values in accordance with the instruction. If the callback function returns an unstated value, VCE framework will handle it as #VCE_ERROR_OPERATION_FAILED.)
3. Register callback functions using 'vce_main()'. (The registered callback functions will be invoked when the VCE service users request the VCE services.)
4. Use 'service_app_main()' for working VCE.
B. Optional VCE services
Unlike the required VCE services, these services are optional to operate VCE. The followings are optional VCE services.
- receive/provide the private data
If the VCE developers want to provide the above services, use the following APIs and implement the corresponding callback functions:
| FUNCTION | DESCRIPTION | CORRESPONDING CALLBACK |
|---|---|---|
| vce_set_private_data_set_cb() | Sets a callback function for setting the private data to the engine service. | vce_private_data_set_cb() |
| vce_set_private_data_requested_cb() | Sets a callback function for requesting the private data to the engine service. | vce_private_data_requested_cb() |
| vce_set_nlu_base_info_requested_cb() | Sets a callback function for requesting the NLU base information to the engine service. | vce_nlu_base_info_requested_cb() |
Using the above APIs, the VCE developers can register the optional callback functions respectively. (For normal operation, put those APIs before 'service_app_main()' starts.)
Unlike callback functions, the following APIs are functions for getting and sending data. The VCE developers can use these APIs when they implement VCE services:
| FUNCTION | DESCRIPTION |
|---|---|
| vce_send_result() | Sends the results to the engine service user. |
| vce_send_asr_result() | Sends the ASR result to the engine service user. |
| vce_send_nlg_result() | Sends the NLG (Natural Language Generation) result to the engine service user. |
| vce_send_error() | Sends the error to the engine service user. |
| vce_get_foreach_command() | Retrieves all commands using callback function. |
| vce_get_command_count() | Gets command length. |
| vce_get_audio_type() | Gets current audio type. |
| vce_set_private_data() | Sets private data to a voice manager client. |
| vce_get_private_data() | Gets private data from a voice manager client. |
| vce_start_recording() | Starts recording voice. |
| vce_stop_recording() | Stops recording voice. |
Related Features
This API is related with the following features:
- http://tizen.org/feature/microphone
- http://tizen.org/feature/speech.control
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.