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 getVoiceControlClient ()
VoiceControlClient	DOMString getCurrentLanguage () void setCommandList (VoiceControlCommand[] list, optional VoiceControlCommandType? type) void unsetCommandList (optional VoiceControlCommandType? type) long addResultListener (VoiceControlResultCallback listener) void removeResultListener (long id) long addLanguageChangeListener (VoiceControlLanguageChangeCallback listener) void removeLanguageChangeListener (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.)

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);
  };
};

VoiceControl API

Summary of Interfaces and Methods

1. Type Definitions

1.1. VoiceControlResultEvent

1.2. VoiceControlCommandType

2. Interfaces

2.1. VoiceControlClientManagerObject

2.2. VoiceControlClientManager

Methods

2.3. VoiceControlClient

Methods

2.4. VoiceControlCommand

Constructors

Attributes

2.5. VoiceControlLanguageChangeCallback

Methods

2.6. VoiceControlResultCallback

Methods

3. Related Feature

4. Full WebIDL