Text Input

Text Input and Voice

The text input features introduce how you can provide customized keyboards, and define keyboard commands to trigger specific actions.

The text input and voice features introduce how you can provide customized keyboards and voice commands. You can also define keyboard commands to trigger specific actions and voice commands to allow the user to control the Web application with their voice.

You can use the following text input features in your Web applications:

You can use the following text input and voice features in your Web applications:

IME Application in wearable applications only @@ -43,6 +44,10 @@
Input Device in mobile and wearable applications only
You can manage input keys in the application. You can retrieve information about the available keys, and add custom actions to be performed when specific input keys are pressed.
Voice Control + +
You can register general voice commands and enable the user to control the Web application with their voice.

diff --git a/org.tizen.guides/html/web/text_input/voice_control_w.htm b/org.tizen.guides/html/web/text_input/voice_control_w.htm new file mode 100755 index 0000000..2faba91 --- /dev/null +++ b/org.tizen.guides/html/web/text_input/voice_control_w.htm @@ -0,0 +1,263 @@ + + + + + + + + + + + + + Voice Control + + + + + +

+ +

Voice Control

+ +

You can enable the user to control the device through their voice. You can register general voice commands, which trigger a listener when the user speaks them. The voice control service recognizes the sound data recorded by the user and sends the result as a predefined command.

+ +

The Voice Control API is mandatory for Tizen mobile, wearable, and TV profiles, which means that it is supported on all mobile, wearable, and TV devices. All mandatory APIs are supported on the Tizen Emulators.

+ +

The main features of the Voice Control API include:

Managing commands +
You can use the voice control service to register commands as foreground type. When the user speaks a registered command, the listener returns the recognition result.
+
Retrieving information +
You can get the current language. A command is valid only when the command language is the same as the current language. The current language can be changed with the voice control setting application or by changing the display language on the device.
+
You can get a notification of the language change in a listener. If the display language is changed to a non-supported one, the voice control language changes to English.
+

+ +

To use the voice control:

Set up the voice control and register listeners. +
The initialization allows the voice control to distinguish your application from any other applications also using voice control. The registered listeners allow you to receive notifications about changes in the language, recognition result, and about any errors.
+
Set commands. +
You can create a command list, and add or remove individual commands in the list. When creating an individual command, set the command text and type for each command handle. When all commands are created and added to the command list, set the command list to the voice control for recognition.
+
Get the recognition result. +
The recognition result is sent through a registered listener.
+
If the registered command is duplicated or the user speaks multiple commands, the recognition result can contain multiple results. If you set duplicated commands, the voice control service can reject the command. The rejection is shown in the result event.
+
When no longer needed, release the voice control instance. +
You must disconnect the voice control service and deinitialize the voice control using the release() function.
+

+ + +

Prerequisites

+ +

To enable your application to use the voice control functionality:

Initialize a voice control client instance using the getVoiceControlClient() function: +

+var initializeVoiceControlClient()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+}
+

When voice control is no longer needed, deinitialize the instance: +
```
+var releaseVoiceControlClient()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+
+    client.release();
+}
+
```
+ +
+ Note + Do not call the release() function in a listener. +
+

+ + +

Managing Listeners

+ +

To set and unset listeners to get notifications about recognition results and language changes:

Add the current language change listener to be invoked when the system or application language changes: +

+/* Listener */
+var languageChangeListenerCallback = function(previous, current)
+{
+    console.log("Language change callback " + previous + "->" + current);
+}
+
+/* Add */
+var addCurrentLanguageChanged()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+    var id = client.addLanguageChangeListener(languageChangeListenerCallback);
+}
+
+/* Remove */
+var removeCurrentLanguageChanged()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+    var id = client.addLanguageChangeListener(languageChangeListenerCallback);
+
+    client.removeLanguageChangeListener(id);
+}
+

Add the recognition result listener to be invoked when a voice command is recognized. +

+ Note + If the recognition result produces a reject event, the voice control service has rejected the recognized command. Make sure that the command does not conflict with other commands and there are no duplicated commands. +

+ +

To get the command, check the list parameter in the recognition result listener. The parameter is an array of recognized VoiceControlCommand instances. The result parameter contains the recognized text.

+ +

+/* Listener */
+var resultListenerCallback = function(event, list, result)
+{
+    console.log("Result callback - event: " + event + ", result: " + result);
+}
+
+/* Add */
+var addResultListener()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+    var id = client.addResultListener(resultListenerCallback);
+}
+
+/* Remove */
+var removeResultListener()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+    var id = client.addResultListener(resultListenerCallback);
+
+    client.removeResultListener(id);
+}
+

+ + +

Retrieving the Current Language

+ +

To get the current language, use the getCurrentLanguage() function. The voice control recognition works for the current (default) language. To be notified of language changes, use the language change listener.

+var getCurrentLang()
+{
+    var client = tizen.voicecontrol.getVoiceControlClient();
+    var currentLanguage = client.getCurrentLanguage();
+    console.log("Current language is: " + currentLanguage);
+
+    /*
+       Expected output:
+       Current language is: en_US
+    */
+}
+

+ + + +

Managing Commands

+ +

To create a command list and commands:

Create a command. +

Create a command with a command text and a command type. The command type is optional and the default command type is FOREGROUND.

+var createCommandList()
+{
+    var command1 = new tizen.VoiceControlCommand("alpha");
+    var command2 = new tizen.VoiceControlCommand("bravo", "FOREGROUND");
+    var command3 = new tizen.VoiceControlCommand("charlie")];
+

Create a command list. +
The command list can include many commands, each with their own command text and type. The list can have FOREGROUND type commands, which are valid when the application is in a visible state.
+
You can access the command list after you set it to the voice control and when you get the recognition result.
+ +
```
+    var commands = [command1, command2, command3];
+
```
+
Set and unset the command list. +
You can set the command list with commands using the setCommandList() function.
+
If you want to update the registered commands, set the command list again with the updated commands using the setCommandList() function.
+
```
+    client.setCommandList(commands, "FOREGROUND");
+
```
+
When no longer needed, unset the command list using the unsetCommandList() function:
+
```
+    if ("FOREGROUND" == type)
+        client.unsetCommandList("FOREGROUND");
+}
+
```
+

+ + + + +

+ +

+ + + + + + diff --git a/org.tizen.guides/index.xml b/org.tizen.guides/index.xml index cb0b63e..3c912ec 100644 --- a/org.tizen.guides/index.xml +++ b/org.tizen.guides/index.xml @@ -465,9 +465,10 @@ - + + diff --git a/org.tizen.web.apireference/html/device_api/mobile/index.html b/org.tizen.web.apireference/html/device_api/mobile/index.html index 52a4b83..4d71a20 100644 --- a/org.tizen.web.apireference/html/device_api/mobile/index.html +++ b/org.tizen.web.apireference/html/device_api/mobile/index.html @@ -367,6 +367,15 @@ Mandatory Yes +

UIX

+ + + + + + +

API	Description	Version (Since)	Mobile	Supported on Mobile Emulator
+ Voice Control	This API provides functions for users to set voice commands and to control the web application through their voices.	4.0	Mandatory	Yes

Cordova

API	Description	Version (Since)	Mobile	Supported on Mobile Emulator
diff --git a/org.tizen.web.apireference/html/device_api/mobile/tizen/voicecontrol.html b/org.tizen.web.apireference/html/device_api/mobile/tizen/voicecontrol.html new file mode 100644 index 0000000..d0341e8 --- /dev/null +++ b/org.tizen.web.apireference/html/device_api/mobile/tizen/voicecontrol.html @@ -0,0 +1,965 @@ + + + + + +VoiceControl API + + + + VoiceControl API + + The Voice Control 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 + + Table of Contents + + 1. Type Definitions + + 1.1. VoiceControlResultEvent + + + 1.2. VoiceControlCommandType + + + + 2. Interfaces + 2.1. VoiceControlClientManagerObject + + 2.2. VoiceControlClientManager + + 2.3. VoiceControlClient + + 2.4. VoiceControlCommand + + 2.5. VoiceControlLanguageChangeCallback + + 2.6. VoiceControlResultCallback + + + + 3. Related Feature + + 4. Full WebIDL + + + + 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); + }; +}; + + + + Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause. For details, see the Content License. + + + + + diff --git a/org.tizen.web.apireference/html/device_api/tv/index.html b/org.tizen.web.apireference/html/device_api/tv/index.html index 37575f8..31492d0 100755 --- a/org.tizen.web.apireference/html/device_api/tv/index.html +++ b/org.tizen.web.apireference/html/device_api/tv/index.html @@ -210,6 +210,19 @@

UIX

+ + + + + + + + + + +

API	Description	Version
+ Voice Control	This API provides functions for users to set voice commands and to control the web application through their voices.	4.0

Cordova

diff --git a/org.tizen.web.apireference/html/device_api/tv/tizen/voicecontrol.html b/org.tizen.web.apireference/html/device_api/tv/tizen/voicecontrol.html new file mode 100644 index 0000000..d0341e8 --- /dev/null +++ b/org.tizen.web.apireference/html/device_api/tv/tizen/voicecontrol.html @@ -0,0 +1,965 @@ + + + + + +VoiceControl API + + +

VoiceControl API

+ The Voice Control 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 +

1. Type Definitions
- + 1.1. VoiceControlResultEvent +
- + 1.2. VoiceControlCommandType +
+
2. Interfaces
- 2.1. VoiceControlClientManagerObject +
- 2.2. VoiceControlClientManager +
- 2.3. VoiceControlClient +
- 2.4. VoiceControlCommand +
- 2.5. VoiceControlLanguageChangeCallback +
- 2.6. VoiceControlResultCallback +
+
3. Related Feature +
4. Full WebIDL +

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: +

Text Input

Text Input and Voice

Voice Control

Prerequisites

Managing Listeners

Retrieving the Current Language

Managing Commands

UIX

Cordova

VoiceControl API

Table of Contents

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

UIX

Cordova

VoiceControl API

Table of Contents

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

UIX

Cordova

VoiceControl API

Table of Contents

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