Samsung TVs allow developers to use voice commands such as Navigation, Search, Selection and Media Control to control their application.
The Voice Assistant in the TV can be Bixby or other assistants. Regardless of which assistant is used, the application will interact with it via the Voice Interaction APIs.
For best results, we recommend the application to be implemented with all the features that are described in this document.
The VoiceInteractionManagerObject interface defines what is instantiated by the WebAPIs object from the Tizen Platform.
There will be a webapis.voiceinteraction object that allows access to the functionality of the Voice Interaction API.
To use the Voice Interaction API, the following privileges must be declared in the manifest file of the application.
If they are not declared, all usage of these APIs are blocked, and security exceptions are thrown. To use these privileges, the minimum ‘required_version’ is 6.0.
readonlyVoiceInteractionManagervoiceinteraction
This attribute defines the namespace for voiceinteraction APIs.
2.2 VoiceInteractionCallback
Every voice interaction application should implement a callback function, so that the Assistant can operate the controls.
Your application can interact with voice assistant by passing the callbacks in webapis.voiceinteraction.setCallback and calling webapis.voiceinteraction.listen.
Except onupdatestate, onsearchcollection callbacks, the return value for the callback is the boolean flag for support or not.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Developers must specify the current application status to the onupdatestate function to get a proper voice control from the Voice Assistant.
This function is called right before processing every utterance, so that the Voice Assistant can be aware of the application status dynamically.
Depending on the status, the callback function called could be different. Therefore, it is important to return the real status of the application.
optional VoiceApplicationState : the status of the current application status.
"None" : Application is in its default status. Same as "Player" status.
"List" : The application is showing something in list.
During this status, the utterances "Play this" or "Play" will call onselection(0).
The utterance "Previous" will call onnavigation ("NAV_PREVIOUS").
"Player" : The application is playing a piece of content.
During this status, the utterance "Play this" will call onplay().
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "List";
}
});
onnavigation
To support navigation controls via voice, the application should have the following callbacks. Otherwise, the Key Event will be generated.
voiceNavigation : The navigation enumeration via Voice.
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "List";
},
onnavigation : function (voiceNavigation) {
var bSupport = true;
console.log("onnavigation : " + voiceNavigation);
switch(voiceNavigation) {
case "NAV_PREVIOUS ":
// "Previous page"
break;
case "NAV_NEXT":
// "Next page"
break;
case "NAV_LEFT":
// "Go to left"
break;
case "NAV_RIGHT":
// "Move to right"
break;
case "NAV_UP":
// "Move up"
break;
case "NAV_DOWN":
// "Go down"
break;
// If there is no callback implementation for these enums,
// TV will Generate Remote Control Key Events: "ArrowRight", "ArrowLeft", "ArrowUp", "ArrowDown".
case "NAV_SHOW_MORE":
// "Show me more"
break;
default:
bSupport = false;
break;
}
return bSupport;
}
});
onsearch
For a contents search provided by the application, it can receive a search utterance to show the search results.
In order to support the search via voice, the application must be registered to Samsung TV's companion search application and have the following callbacks.
The OnSearch parameter has a specific format. To learn more about it, please refer to the getDataFromSearchTerm.
Some callbacks are not called by default such as onsearch.
To receive all the callback signals on the development stage, request a key from Samsung and apply the key to the Manifest of your Tizen Application.
The following example shows how to add the "http://developer.samsung.com/tizen/metadata/support-vif-devfeature" key to the manifest file.
voiceSearchTerm : The Object contains the information via Voice.
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" tizen="http://tizen.org/ns/widgets" id="http://yourdomain/VoiceInteractionWebSample" version="1.0.0" viewmodes="maximized">
<access origin="" subdomains="true"></access>
< application id="AbCDEfgHrJ.VoiceInteractionWebSample" package="AbCDEfgHrJ" required_version="6.0"/>
<content src="index.html"/>
<feature name="http://tizen.org/feature/screen.size.normal.1080.1920"/>
<icon src="icon.png"/>
< metadata key="http://developer.samsung.com/tizen/metadata/support-vif-dev-feature" value="true"/>
<name>VoiceInteractionWebSample</name>
< privilege name="http://developer.samsung.com/privilege/voicecontrol"/>
< privilege name="http://developer.samsung.com/privilege/microphone"/>
< profile name="tv-samsung"/>
</widget>
@endcode
@param voiceSearchTerm The Object contains the information via Voice.
@see getDataFromSearchTerm
@throw None N/A
@return boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
@code
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Home";
},
onsearch : function (voiceSearchTerm) {
console.log("OnSearch : " + JSON.stringify(voiceSearchTerm));
var title = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_TITLE");
var genre = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_GENRE");
console.log("Request to search " + title + ", " + genre);
return true;
}
});
onplay
Supports the media control to handle playback(Play).
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Player";
},
onplay : function () {
// TV Default Action: Generates the Remote Control Key, "MediaPlay".
console.log("OnPlay called");
return true;
}
});
onstop
Supports the media control to handle playback(Stop).
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Player";
},
onstop : function () {
// TV Default Action: Generates the Remote Control Key, "MediaStop".
console.log("OnStop called");
return true;
}
});
onpause
Supports the media control to handle playback(Pause).
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Player";
},
onpause : function () {
// TV Default Action: Generates the Remote Control Key, "MediaPlayPause".
console.log("OnPause called");
return true;
}
});
onexit
Supports the media control to handle playback(Exit).
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Player";
},
onexit : function () {
// TV Default Action: Generates the Remote Control Key, "Exit".
console.log("OnExit called");
return true;
}
});
onselection
To support selection controls via voice, the application should have the following callbacks.
This callback supports the ordinal, relative selection control.
voiceSelection : The relative index via voice, (ex. the last item is -1, the current item is 0, the first item is 1).
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "List";
},
onselection : function (voiceSelection) {
var bSupport = true;
console.log("onselection : " + voiceSelection);
switch(voiceSelection) {
case -1 :
// "Select the last one"
break;
case 0 :
// "Select this"
break;
default:
{
if(voiceSelection >= 1)
// "Select the first one"
{
// Select the (voiceSelection)th item
// index of the first item is 1
console.log("For Ordinal : " + voiceSelection);
}
else
{
bSupport = false;
}
}
break;
}
return bSupport;
}
});
ontitleselection
Title selection refers to an utterance in the format "Select {Title Name}".
To support the title selection via voice, the following two callbacks are required : onrequestcontentcontext and ontitleselection.
The onrequestcontentcontext callback provides the information regarding the content of the screen (such as title and position) to the Samsung TV.
This method will be invoked at the beginning of every utterance. The response consists of positionX(int), positionY(int), title(string), alias(string array) and bFocused(bool).
The title property is used for ASR conversion and the other properties are used to set the priority of each title.
The OnTitleSelection callback receives the title name from the utterance.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "List";
},
onrequestcontentcontext : function () {
console.log("onrequestcontentcontext ");
var result = [];
try {
var item = {
"positionX" : 0,
"positionY" : 0,
"title" : "Title Text1",
"alias" : ["Title1", "My Text1"],
"bFocused" : true
};
result.push(item);
var item2 = {
"positionX" : 1,
"positionY" : 0,
"title" : "Title Text2",
"alias" : ["Title2", "My Text2"],
"bFocused" : false
};
result.push(item2);
result.push(webapis.voiceinteraction.buildVoiceInteractionContentContextItem(2,0,"Title Text3", ["Title3", "My Text3"], false));
} catch (e) {
console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
}
return webapis.voiceinteraction.buildVoiceInteractionContentContextResponse(result);
},
ontitleselection : function (title) {
console.log("ontitleselection" + title);
return true;
}
});
onfastforward
Supports the media control to handle playback(FF).
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Player";
},
onfastforward : function () {
// TV Default Action: Generates the Remote Control Key, "MediaFastForward".
console.log("onfastforward called");
return true;
}
});
onrewind
Supports the media control to handle playback(Rewind).
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "Player";
},
onrewind : function () {
// TV Default Action: Generates the Remote Control Key, "MediaRewind".
console.log("onrewind called");
return true;
}
});
onsearchcollection
Supports the search utterance appending to the default search application. The value of the result for the search term.
voiceSearchTerm : The Object contains the information via Voice.
Return Value :
optional DOMString : the formatted value of the result for the search term.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "None";
},
onsearchcollection : function (voiceSearchTerm) {
Log("onsearchcollection : " + JSON.stringify(voiceSearchTerm));
var result = [];
//appName and appId are of the UI Application to get the payload on launch.
result.push(webapis.voiceinteraction.buildCollectionDeeplinkData("a1b2c3d4ef.myTizenAppId", "myTizenApp", "page_id=123456&method=voice"));
return JSON.stringify(result);
}
});
onchangeappstate
To support the utterance of shortcut commands, the application must have the onchangeappstate callback.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "None";
},
onchangeappstate: function (state) {
// TV Default Action: Launches the Samsung TV FirstScreen, Menu or Search application. Depending on the input parameter.
// "Go to Home", "Go to Settings", "Go to Search".
console.log("onchangeappstate : " + state);
var bSupport = true;
switch (state) {
case "Home":
// Go to App's Home
break;
default:
bSupport = false;
break;
}
return bSupport;
}
});
onchangeprevioustrack
In order to handle requests to move to the previous track via voice, the application should override the onchangeprevioustrack callback.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
onchangeprevioustrack : function () {
console.log("onchangeprevioustrack");
return true;
}
});
onchangenexttrack
In order to handle requests to move to the next track via voice, the application should override the onchangenexttrack callback.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
onchangenexttrack : function () {
console.log("onchangenexttrack");
return true;
}
});
onrestart
In order to handle requests to restart to this track via voice, the application should override the onrestart callback.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
onrestart : function () {
console.log("onrestart");
return true;
}
});
onskipbackward
In order to handle requests to skip backward via voice, the application should override the onskipbackward callback.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
zoom : MEDIA_ZOOM_IN : zoom in / MEDIA_ZOOM_OUT : zoom out
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
direction : MEDIA_ROTATE_LEFT : rotate left / MEDIA_ROTATE_RIGHT : rotate right
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
mode : MEDIA_FUNCTION_ON : Turning On / MEDIA_FUNCTION_OFF : Turning Off
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
mode : MEDIA_REPEAT_OFF : repeat mode off / MEDIA_REPEAT_ONE : repeat this track / MEDIA_REPEAT_ALL : repeat all tracks
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
onchangerepeatmode : function (mode) {
console.log("onchangerepeatmode");
switch(mode) {
case "MEDIA_REPEAT_ONE" :
console.log("ONE");
break;
case "MEDIA_REPEAT_ALL" :
console.log("ALL");
break;
default :
console.log("OFF");
break;
}
return true;
}
});
oncontinuewatching
In order to handle requests to launch the application with playing the history track via voice, the application should override the oncontinuewatching callback to play the history track.
This callback will be called after launching the application.
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung device may perform its basic function.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
oncontinuewatching : function () {
console.log("oncontinuewatching");
return true;
}
});
jsonObjectString : the string stringified json object.
Return Value :
optional boolean : boolean value of whether the app supports this feature.
Voice Assistant Action will get the response "{"result_code":"SUCCESS"}" for true, "{"result_code":"FAILURE"}" for false/undefined.
Since : 6.0
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
console.log("Assistant tries to get app state");
return "List";
},
oncustom : function (jsonObjectString) {
console.log("oncustom : " + jsonObjectString);
try {
var customObject = JSON.parse(jsonObjectString);
for (var key in customObject) {
if(customObject.hasOwnProperty(key)) {
console.log("Key : " + key + ", Value : " + customObject[key]);
}
}
} catch (e) {
console.log("exception [" + e.code + "] name: " + e.name + " message: " + e.message);
return false;
}
return true;
}
});
onrequestcontentcontext
In order to support the voice title selection via voice, the application should override the onrequestcontentcontext callback, return the JsonObject string for the current content context list showing.
list : LIST_BOOKMARKS : bookmarks / LIST_WATCH_LATER : watch later
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.
Since : 6.5
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
onadditiontolist : function (list) {
console.log("onadditiontolist");
switch(list) {
case "LIST_BOOKMARKS" :
console.log("Add this context to Bookmarks");
break;
case "LIST_WATCH_LATER" :
console.log("Add this context to Watch later");
break;
default :
break;
}
return true;
}
});
onremovalfromlist
In order to handle requests to remove this context from list via voice, the application should override the onremovalfromlist callback.
list : LIST_BOOKMARKS : bookmarks / LIST_WATCH_LATER : watch later
Return Value :
optional boolean : boolean value of whether the app supports this feature.
If a callback returns the false/undefined value, or there is no callback implementation for the utterance, Samsung TV may perform its basic function.
Since : 6.5
Code Example :
webapis.voiceinteraction.setCallback({
onupdatestate : function () {
return "List";
},
onremovalfromlist : function (list) {
console.log("onremovalfromlist");
switch(list) {
case "LIST_BOOKMARKS" :
console.log("Remove this context from Bookmarks");
break;
case "LIST_WATCH_LATER" :
console.log("Remove this context from Watch later");
break;
default :
break;
}
return true;
}
});
2.3 VoiceSearchTerm
This interface represents information about the voice search term.
readonlyDOMStringutterance[nullable]
The field for the full utterance.
readonlyDOMStringtitle[nullable]
The field for the title.
readonlyDOMStringgenre[nullable]
The field for the genre.
readonlyDOMStringcast[nullable]
The field for the cast.
readonlyDOMStringcontentType[nullable]
The field for the content type (movie/tvshow).
readonlyDOMStringfrom[nullable]
The field for the start date time(ISO 8601).
readonlyDOMStringto[nullable]
The field for the end date time(ISO 8601).
2.4 VoiceInteractionContentContext
This interface represents information about the content context for an item.
[NoInterfaceObject] interface VoiceInteractionContentContext {
attribute long positionX;
attribute long positionY;
attribute DOMString title;
attribute boolean bFocused;
};
Attributes
longpositionX
The field for x-axis position of the item.
longpositionY
The field for y-axis position of the item.
DOMStringtitle
The field for the title of the item.
booleanbFocused
The field for whether this item has a focus.
2.5 VoiceInteractionManager
The VoiceInteractionManager interface is the top-level interface for the VoiceInteractionManager API that provides access to the module functionalities.
voiceSearchTerm : The VoiceSearchTerm from samsung side as search term.
field : The field enum to get the value.
Return Value :
DOMString : The result string formatted.
Exceptions :
WebAPIException
with error type UnknownError in any other error case.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type InvalidValuesError, if any input parameter contains an invalid value.
with error type TypeMismatchError, if an input parameter is not compatible with its expected type.
Since : 6.0
Code Example :
var title = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_TITLE");
var genre = webapis.voiceinteraction.getDataFromSearchTerm(voiceSearchTerm, "SEARCH_TERM_GENRE");
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
.samsungdeveloperconference.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
LinkedIn
.ads.linkedin.com, .linkedin.com
Advertising Cookies
These cookies gather information about your browser habits. They remember that
you've visited our website and share this information with other organizations such
as advertisers.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Preferences Submitted
You have successfully updated your cookie preferences.