VoiceControl API

The VoiceControl API provides interfaces and methods for recognizing voice command.

Voice control API offers functionality to recognize the voice and to send the result as predefined command.

Since: 4.0

Summary of Interfaces and Methods

Interface Method
VoiceControlClientManagerObject
VoiceControlClientManager
VoiceControlClient
DOMString getCurrentLanguage ()
void removeResultListener (long id)
void release ()
VoiceControlCommand
VoiceControlLanguageChangeCallback
void onlanguagechanged (DOMString previous, DOMString current)
VoiceControlResultCallback
void onresult (VoiceControlResultEvent event, VoiceControlCommand[] list, DOMString results)

1. Type Definitions

1.1. VoiceControlResultEvent

Specifies the result event. 
    enum VoiceControlResultEvent {"SUCCESS", "FAILURE"};

Since: 4.0

The result events defined by this enumeration are:

  • SUCCESS - Successful result
  • FAILURE - Rejected result by voice control service

1.2. VoiceControlCommandType

Specifies command type. 
    enum VoiceControlCommandType {"FOREGROUND"};

Since: 4.0

The command type defined by this enumeration is:

  • FOREGROUND - command type used when application is foreground

2. Interfaces

2.1. VoiceControlClientManagerObject

The VoiceControlClientManagerObject interface defines what is instantiated in the Tizen object. 
    [NoInterfaceObject] interface VoiceControlClientManagerObject {
       readonly attribute VoiceControlClientManager voicecontrol;
    };
    Tizen implements VoiceControlClientManagerObject;

Since: 4.0

The tizen.voicecontrol object provides access to the functionality of the voice control API.

2.2. VoiceControlClientManager

Voice Control Client Manager 
    [NoInterfaceObject] interface VoiceControlClientManager {
       VoiceControlClient getVoiceControlClient() raises(WebAPIException);
    };

Since: 4.0

Methods

getVoiceControlClient
Requests voice control Client instance. 
VoiceControlClient getVoiceControlClient();

Since: 4.0

Privilege level: public

Privilege: http://tizen.org/privilege/recorder

Remark : This method always returns the static voice control client object. That is, if you call a method using one of voice control client objects, it affects other objects.

Return value:

VoiceControlClient The object to manage voice control

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 /* client1 and client2 refer the same object */
 var client1 = tizen.voicecontrol.getVoiceControlClient();
 var client2 = tizen.voicecontrol.getVoiceControlClient();

2.3. VoiceControlClient

Voice Control Client 
    [NoInterfaceObject] interface VoiceControlClient {

       DOMString getCurrentLanguage() raises(WebAPIException);

       void setCommandList(VoiceControlCommand[] list, optional VoiceControlCommandType? type) raises(WebAPIException);

       void unsetCommandList(optional VoiceControlCommandType? type) raises(WebAPIException);

       long addResultListener(VoiceControlResultCallback listener) raises(WebAPIException);

       void removeResultListener(long id) raises(WebAPIException);

       long addLanguageChangeListener(VoiceControlLanguageChangeCallback listener) raises(WebAPIException);

       void removeLanguageChangeListener(long id) raises(WebAPIException);

       void release() raises(WebAPIException);
    };

Since: 4.0

Methods

getCurrentLanguage
Gets current language. 
DOMString getCurrentLanguage();

Since: 4.0

A language is specified as an ISO 3166 alpha-2 two letter country-code followed by ISO 639-1 for the two-letter language code. For example, "ko_KR" for Korean, "en_US" for American English.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();
 var currentLanguage = client.getCurrentLanguage();

 console.log("Current language is: " + currentLanguage);

Output example:

 Current language is: en_US
setCommandList
Sets command list. 
void setCommandList(VoiceControlCommand[] list, optional VoiceControlCommandType? type);

Since: 4.0

Privilege level: public

Privilege: http://tizen.org/privilege/recorder

Parameters:

  • list: Command list handle
  • type [optional] [nullable]: Type of registered commands. The default value is "FOREGROUND"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();

 var commands = [
            new tizen.VoiceControlCommand("alpha"),
            new tizen.VoiceControlCommand("bravo"),
            new tizen.VoiceControlCommand("charlie")];
 client.setCommandList(commands, "FOREGROUND");
unsetCommandList
Unsets command list. 
void unsetCommandList(optional VoiceControlCommandType? type);

Since: 4.0

Privilege level: public

Privilege: http://tizen.org/privilege/recorder

Parameters:

  • type [optional] [nullable]: Type of commands that should be unset. The default value is "FOREGROUND"

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type SecurityError, if the application does not have the privilege to call this method.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();

 var commands = [
            new tizen.VoiceControlCommand("alpha"),
            new tizen.VoiceControlCommand("bravo"),
            new tizen.VoiceControlCommand("charlie")];
 client.setCommandList(commands, "FOREGROUND");

 client.unsetCommandList("FOREGROUND");
addResultListener
Registers a listener for getting recognition result. 
long addResultListener(VoiceControlResultCallback listener);

Since: 4.0

Parameters:

  • listener: Callback function to register

Return value:

long Identifier used to clear the watch subscription.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();

 var commands = [
            new tizen.VoiceControlCommand("alpha"),
            new tizen.VoiceControlCommand("bravo"),
            new tizen.VoiceControlCommand("charlie")];
 client.setCommandList(commands, "FOREGROUND");

 var resultListenerCallback = function(event, list, result)
 {
   console.log("Result callback - event: " + event + ", result: " + result);
 }

 var id = client.addResultListener(resultListenerCallback);
 console.log("Result listener[" + id + "] is created");

Output example:

 Result listener[1] is created

Output example:

 /* (When a user says "alpha") */
 Result callback - event: SUCCESS, result: alpha
removeResultListener
Unregisters the listener. 
void removeResultListener(long id);

Since: 4.0

Parameters:

  • id: Identifier used to clear the watch subscription

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();

 var commands = [
            new tizen.VoiceControlCommand("alpha"),
            new tizen.VoiceControlCommand("bravo"),
            new tizen.VoiceControlCommand("charlie")];
 client.setCommandList(commands, "FOREGROUND");

 var resultListenerCallback = function(event, list, result)
 {
   console.log("Result callback - event: " + event + ", result: " + result);
 }

 var id = client.addResultListener(resultListenerCallback);

 client.removeResultListener(id);
addLanguageChangeListener
Registers a callback function to be called when current language is changed. 
long addLanguageChangeListener(VoiceControlLanguageChangeCallback listener);

Since: 4.0

Parameters:

  • listener: Callback function to register

Return value:

long Identifier used to clear the watch subscription.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if the input parameter is not compatible with the expected type.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();

 var languageChangeListenerCallback = function(previous, current)
 {
   console.log("Language change callback " + previous + "->" + current);
 }

 var id = client.addLanguageChangeListener(languageChangeListenerCallback);
 console.log("Language change listener[" + id + "] is created");

Output example:

 Language change listener[1] is created

Output example:

 /* (When language is changed) */
 Language change callback en_US->ko_KR
removeLanguageChangeListener
Unregisters the callback function. 
void removeLanguageChangeListener(long id);

Since: 4.0

Parameters:

  • id: Identifier used to clear the watch subscription

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported.

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 var client = tizen.voicecontrol.getVoiceControlClient();

 var languageChangeListenerCallback = function(previous, current)
 {
   console.log("Language change callback " + previous + "->" + current);;
 }

 var id = client.addLanguageChangeListener(languageChangeListenerCallback);

 client.removeLanguageChangeListener(id);
release
Releases all resources. 
void release();

Since: 4.0

Releases listeners and disconnects voice control service. You should call this method when you do not want to use voice control client instance any more. It is necessary to create new voice control client instance, if you want to use more after release.

Remark : If you call this method, all other VoiceControlClient objects are also released.

Exceptions:

  • WebAPIException

    • with error type AbortError, if the operation cannot be finished properly.

Code example:

 /* Initialize the voice control client */
 var client = tizen.voicecontrol.getVoiceControlClient();

 var commands = [
            new tizen.VoiceControlCommand("alpha"),
            new tizen.VoiceControlCommand("bravo"),
            new tizen.VoiceControlCommand("charlie")];
 client.setCommandList(commands, "FOREGROUND");

 var resultListenerCallback = function(event, list, result)
 {
   console.log("Result callback - event: " + event + ", result: " + result);
 }

 var id = client.addResultListener(resultListenerCallback);

 /* Deinitialize the voice control client */
 client.removeResultListener(id);
 client.unsetCommandList("FOREGROUND");

 /* After release() voice control does not work */
 /* If you want to use voice control after release(), you should initialize the client again */
 client.release();

2.4. VoiceControlCommand

The VoiceControlCommand defines interface used to create command you want to be recognized. 
    [Constructor(DOMString command, optional VoiceControlCommandType? type)]
    interface VoiceControlCommand {

       attribute DOMString command;

       attribute VoiceControlCommandType type;
    };

Constructors

Command constructor 
VoiceControlCommand(DOMString command, optional VoiceControlCommandType? type);

Attributes

  • DOMString command
    The command text

    The command should be set as text you want to be recognized.

  • VoiceControlCommandType type
    The type of the command processing

    The default value is "FOREGROUND"

2.5. VoiceControlLanguageChangeCallback

Called when default language is changed. 
    [Callback=FunctionOnly, NoInterfaceObject] interface VoiceControlLanguageChangeCallback {
       void onlanguagechanged (DOMString previous, DOMString current);
    };

Since: 4.0

Methods

onlanguagechanged
Called when default language is changed. 
void onlanguagechanged(DOMString previous, DOMString current);

Since: 4.0

Parameters:

  • previous: Previous language
  • current: Current language

2.6. VoiceControlResultCallback

Called when client gets the recognition result. 
    [Callback=FunctionOnly, NoInterfaceObject] interface VoiceControlResultCallback {
       void onresult(VoiceControlResultEvent event, VoiceControlCommand[] list, DOMString results);
    };

Since: 4.0

Methods

onresult
Called when client gets the recognition result. 
void onresult(VoiceControlResultEvent event, VoiceControlCommand[] list, DOMString results);

Since: 4.0

Parameters:

  • event: The result event
  • list: The recognized command list
  • results: The spoken text (e.g. registered command text like "play", "stop", etc.)

3. Related Feature

You can check if this API is supported with tizen.systeminfo.getCapability() and decide enable/disable codes that need this API.

To guarantee that the voice control application runs on a device with speech control feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/speech.control

    • To guarantee that the voice control application runs on a device with microphone feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/microphone

    • For more information, see Application Filtering.

    4. Full WebIDL

    module VoiceControl {
    enum VoiceControlResultEvent {"SUCCESS", "FAILURE"};

    enum VoiceControlCommandType {"FOREGROUND"};

    [NoInterfaceObject] interface VoiceControlClientManagerObject {
       readonly attribute VoiceControlClientManager voicecontrol;
    };

    Tizen implements VoiceControlClientManagerObject;

    [NoInterfaceObject] interface VoiceControlClientManager {
       VoiceControlClient getVoiceControlClient() raises(WebAPIException);
    };

    [NoInterfaceObject] interface VoiceControlClient {

       DOMString getCurrentLanguage() raises(WebAPIException);

       void setCommandList(VoiceControlCommand[] list, optional VoiceControlCommandType? type) raises(WebAPIException);

       void unsetCommandList(optional VoiceControlCommandType? type) raises(WebAPIException);

       long addResultListener(VoiceControlResultCallback listener) raises(WebAPIException);

       void removeResultListener(long id) raises(WebAPIException);

       long addLanguageChangeListener(VoiceControlLanguageChangeCallback listener) raises(WebAPIException);

       void removeLanguageChangeListener(long id) raises(WebAPIException);

       void release() raises(WebAPIException);
    };

    [Constructor(DOMString command, optional VoiceControlCommandType? type)]
    interface VoiceControlCommand {

       attribute DOMString command;

       attribute VoiceControlCommandType type;
    };

    [Callback=FunctionOnly, NoInterfaceObject] interface VoiceControlLanguageChangeCallback {
       void onlanguagechanged (DOMString previous, DOMString current);
    };

    [Callback=FunctionOnly, NoInterfaceObject] interface VoiceControlResultCallback {
       void onresult(VoiceControlResultEvent event, VoiceControlCommand[] list, DOMString results);
    };
};