Voice-Control-Engine

Voice-Control-Engine (VCE) is an engine to recognize sound data. The user records this data and sends the result as a predefined command.

VCE developers can provide VCE service users, to apply VCE with functions that is necessary to operate the engine.

The main features of the VCE API include:

  • Preparing the VCE service for use

    You can connect the VCE service application. Basic VCE Processes and Prerequisites are defined.

  • VCE Parameters

    You can set information, which includes language and state.

  • VCE Retrieval information

    You can get information, which includes command count and audio type.

  • VCE Control Recording

    You can control VCE recording to the engine service user. VCE Control Recording, is defined.

  • VCE Send results

    You can send the results to the engine service user. VCE Send Results, is defined.

Prerequisites

To enable your application to use the VCE functionality:

  1. To use the VCE API (in mobile and wearable applications), the application has to request permission by adding the following privileges to the tizen-manifest.xml file:

    <privileges>
   <privilege>http://tizen.org/privilege/recorder</privilege>
   <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
   <privilege>http://tizen.org/privilege/datasharing</privilege>
</privileges>

  2. To use the functions and data types of the VCE API (in mobile and wearable applications), include the <vce.h> header file in your application:

    #include <vce.h>

  3. Create a structure vce_request_callback_s:

    vce_request_callback_s callback = {0,};

  4. Register callback functions using vce_main() function (The registered callback functions will be invoked when the VCE service users request the VCE services).

    vce_main(argc, argv, &callback);

VCE Basic Processes

Using VCE, you can:

  1. Create a structure using the vce_request_callback_s function.

  2. Implement callback functions.

    Add Event Callbacks, sets language, sets command, starts recognition and, so on by registered callback functions.

  3. Register callback functions using vce_main() function.

Add Event Callbacks

To register and define event callbacks for the VCE service application:

  1. The VCE developer must register the initialize(), deinitialize(), get_info(), get_recording_format(), foreach_langs(), is_lang_supported(), set_language(), set_commands(), unset_commands(), start(), set_recording(), stop(), cancel(), set_audio_type(), set_domain(), process_text(), process_list_event(), process_haptic_event() callbacks.

    • Add the callbacks to the vce_request_callback_s structure (in mobile and wearable applications), and pass the structure as a parameter to the vce_main() function:

       static int initialize(void);
 static int deinitialize(void);
 static int get_info(char** engine_uuid, char** engine_name, char** engine_settings_app_id, bool* use_network);
 static int get_recording_format(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels);
 static int foreach_langs(vce_supported_language_cb callback, void* user_data);
 static bool is_lang_supported(const char* lang);
 static int set_language(const char* language);
 static int set_commands(vce_cmd_h vc_command);
 static int unset_commands(void);
 static int start(bool stop_by_silence);
 static int set_recording(const void* data, unsigned int length, vce_speech_detect_e* silence_detected);
 static int stop(void);
 static int cancel(void);
 static int set_audio_type(const char* audio_type);
 static int set_domain(const char* domain);
 static int process_text(const char* text);
 static int process_list_event(const char* event);
 static int process_haptic_event(const char* event);

 void
 int main(int argc, char* argv[])
 {
     vce_request_callback_s callback = {0,};

     callback.version = 1;

     callback.initialize	= initialize;
     callback.deinitialize	= deinitialize;

     callback.get_info	= get_info;
     callback.get_recording_format	= get_recording_format;
     callback.foreach_langs	= foreach_langs;
     callback.is_lang_supported	= is_lang_supported;

     callback.set_language	= set_language;
     callback.set_commands	= set_commands;
     callback.unset_commands	= unset_commands;

     callback.start		= start;
     callback.set_recording	= set_recording;
     callback.stop		= stop;
     callback.cancel		= cancel;

     callback.set_audio_type	= set_audio_type;
     callback.set_domain	= set_domain;
     callback.process_text	= process_text;
     callback.process_list_event	= process_list_event;
     callback.process_haptic_event	= process_haptic_event;

     vce_main(argc, argv, &callback);
 }

  2. Define the callbacks:

     static int
 initialize(void)
 {
     /* Your code */
     return 0;	/* initialize succeed */
 }

 static int
 deinitialize(void)
 {
     /* Your code */
     return 0;	/* deinitialize succeed */
 }

 static int
 get_info(char** engine_uuid, char** engine_name, char** engine_settings_app_id, bool* use_network)
 {
     /* Your code */
     *engine_uuid = strdup("engine_uuid");
     *engine_name = strdup("engine_name");
     *engine_setting = strdup("engine_settings_app_id");	/* the engine settings application (the UI application) */
     *use_network = true;	/* Need network */

     *use_network = false;	/* Not to need network */
     return 0;
 }

 static int
 get_recording_format(const char* audio_id, vce_audio_type_e* types, int* rate, int* channels)
 {
     /* Your code */
     return 0;	/* supported langs */
 }

 static int
 foreach_langs(vce_supported_language_cb callback, void* user_data)
 {
     /* Your code */
     return 0;	/* supported langs */
 }

 static bool
 is_lang_supported(const char* lang)
 {
     /* Your code */
     return true;	/* supported language */

     return false;	/* Not supported language */
 }

 static int
 set_language(const char* language)
 {
     /* Your code */
     return 0;	/* set_language succeed */
 }

 static int
 set_commands(vce_cmd_h vc_command)
 {
     /* Your code */
     return 0;	/* set_commands succeed */
 }

 static int
 unset_commands(void)
 {
     /* Your code */
     return 0;	/* unset_commands succeed */
 }

 static int
 start(bool stop_by_silence)
 {
     /* Your code */
     return 0;	/* start succeed */
 }

 static int
 set_recording(const void* data, unsigned int length, vce_speech_detect_e* silence_detected)
 {
     /* Your code */
     return 0;	/* set_recording succeed */
 }

 static int
 stop(void)
 {
     /* Your code */
     return 0;	/* stop succeed */
 }

 static int
 cancel(void)
 {
     /* Your code */
     return 0;	/* cancel succeed */
 }

 static int
 set_audio_type(const char* audio_type)
 {
     /* Your code */
     return 0;	/* set_audio_type succeed */
 }

 static int
 set_domain(const char* domain)
 {
     /* Your code */
     return 0;	/* set_domain succeed */
 }

 static int
 process_text(const char* text)
 {
     /* Your code */
     return 0;	/* process_text succeed */
 }

 static int
 process_list_event(const char* event)
 {
     /* Your code */
     return 0;	/* process_list_event succeed */
 }

 static int
 process_haptic_event(const char* event)
 {
     /* Your code */
     return 0;	/* process_haptic_event succeed */
 }

  3. Implement the optional callbacks, as needed:

    • You can register optional callbacks with the vce_set_private_data_set_cb(), vce_set_private_data_requested_cb(), vce_set_nlu_base_info_requested_cb() functions:

       static int private_data_set_cb(const char* key, const char* data);
 static int private_data_requested_cb(const char* key, char** data);
 static int nlu_base_info_requested_cb(const char* key, char** value);

 void
 int main(int argc, char* argv[])
 {
     vce_request_callback_s callback = {
         /* Add the mandatory callbacks */
     };

     vce_set_private_data_set_cb(private_data_set_cb);
     vce_set_private_data_requested_cb(private_data_requested_cb);
     vce_set_nlu_base_info_requested_cb(nlu_base_info_requested_cb);

     vce_main(argc, argv, &callback);
 }

  4. Define the optional callbacks:

     static int
 private_data_set_cb(const char* key, const char* data)
 {
     return 0;	/* private data save succeed */
 }

 static int
 private_data_requested_cb(const char* key, char** data)
 {
     /* found key */
     *data = strdup("data");
     return 0;	/* private data set succeed */
 }

 static int
 nlu_base_info_requested_cb(const char* key, char** value)
 {
     /* found key */
     *value = strdup("value");
     return 0;	/* nlu base info value set succeed */
 }

VCE Parameters

You can set the following parameters about the VCE:

  • Send the current state using the vce_send_error() function and send the error to a engine service user.

      void
  send_error(void)
  {
      int ret = VCE_ERROR_NONE;

      ret = vce_send_error(VCE_ERROR_NONE, "msg", NULL);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

  • Send the current state using the vce_set_private_data() function. Set private data to a engine service user.

      void
  set_private_data(void)
  {
      int ret = VCE_ERROR_NONE;

      ret = vce_set_private_data("key", "data");
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

VCE Information Retrieval

You can get the following information about the VCE:

  • Get all commands using the vce_get_foreach_command() function.

      bool
  command_cb(int id, int type, int format, const char* command, const char* param, int domain, void* user_data)
  {
      /* Callback command data */
      /* Your code */
  }

  void
  get_foreach_command(void)
  {
      int ret = VCE_ERROR_NONE;
      int g_vce_command;

      ret = vce_get_foreach_command(g_vce_command, command_cb, NULL);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

  • Get command length using the vce_get_command_count() function. Get g_vce_command data from set_commands() function.

      void
  get_command_count(void)
  {
      int ret = VCE_ERROR_NONE;
      int count = 0;

      ret = vce_get_command_count(g_vce_command, &count);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

  • Get current audio type using the vce_get_audio_type() function.

      void
  get_audio_type(void)
  {
      int ret = VCE_ERROR_NONE;
      char *audio_type = NULL;

      ret = vce_get_audio_type(&audio_type);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
      if(NULL != audio_type) {
          /* Memory release */
          free(audio_type);
          audio_type = NULL;
      }
  }

  • Get private data from a voice manager client using the vce_get_private_data() function.

      void
  get_private_data(void)
  {
      int ret = VCE_ERROR_NONE;
      char *data = NULL;

      ret = vce_get_private_data("key", &data);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
      if(NULL != data) {
          /* Memory release */
          free(data);
          data = NULL;
      }
  }

VCE Control Recording

You can control recording of the following information about the VCE:

  • Start recording voice using the vce_start_recording() function. If the function call is successful, you can receive recording data from set_recording function.

      void
  start_recording(void)
  {
      int ret = VCE_ERROR_NONE;

      ret = vce_start_recording();
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

  • Stop recording voice using the vce_stop_recording() function. If the function call is successful, you can not receive recording data from set_recording function.

      void
  stop_recording(void)
  {
      int ret = VCE_ERROR_NONE;

      ret = vce_stop_recording();
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

VCE Send Results

You can send the following result information about the VCE:

  • Send the command result to the engine service user using the vce_send_result() function.

      void
  send_result(void)
  {
      int ret = VCE_ERROR_NONE;
      int is_consumed;

      ret = vce_send_result(VCE_RESULT_EVENT_SUCCESS, NULL, 0, "text", NULL, NULL, VC_RESULT_MESSAGE_NONE, &is_consumed, NULL);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

  • Send the Automatic Speech Recognition (ASR) result to the engine service user using the vce_send_asr_result() function.

      void
  send_asr_result(void)
  {
      int ret = VCE_ERROR_NONE;
      ret = vce_send_asr_result(VCE_ASR_RESULT_EVENT_FINAL_RESULT, "asr_result", NULL);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }

  • Send the Natural Language Generation (NLG) result to the engine service user using the vce_send_nlg_result() function.

      void
  send_nlg_result(void)
  {
      int ret = VCE_ERROR_NONE;
      ret = vce_send_nlg_result("nlg_result", NULL);
      if(VCE_ERROR_NONE != ret)
          /* Error handling */
  }
  • Dependencies
    • Tizen 5.0 and Higher for Mobile
    • Tizen 5.0 and Higher for Wearable
Edit this page