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