com.webos.service.tts

Note
This API has been available since API level 11.

API Summary

Converts plain language text into speech output. The synthesized speech can be used by applications such as voice assistants.

Overview of the API

Before using the service, you need to enable Google Cloud Text-to-speech API on the device.

Log in to the Google Cloud Account.
Go to the Google Cloud Console and perform the following steps:
1. Create a new project.
  Note: You can also use an existing project to configure the API.
2. Enable Cloud Text-to-Speech API. (See instructions.)
3. Create the credentials file.
  1. From the APIs and Services page, click Credentials.
  2. Click Create Credentials, and select Service account key.
  3. Select a Service account and key type as JSON.
  4. Click Create. The JSON file containing the credentials is downloaded to your system.
  5. Rename the file to google_tts_credentials.json.
Copy the credentials.json file to the target device.
1. From the device terminal, run the following command:
  - mkdir /etc/google
2. Copy the credentials file to /etc/google/google_tts_credentials.json.

Methods

getAvailableLanguages

ACG: tts.operation

Added: API level 11

Description

Gets the list of languages that are supported by the TTS provider.

Parameters

Name	Required	Type	Description
displayId	Optional	Number	Indicates the unique identifier for the displays. Possible values are: 0: display 1 1: display 2 Default: 0

Name

Required

Type

Description

displayId

Optional

Number

Indicates the unique identifier for the displays.

Possible values are:

0: display 1
1: display 2

Default: 0

Call Returns

Name	Required	Type	Description
languages	Required	String array	Indicates the list of supported languages.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/getAvailableLanguages '{}'

Response:

{
   "Languages":[
      "ko-KR",
      "en-US"
   ],
   "returnValue":true
}

Example: With displayId

# luna-send -n 1 -f luna://com.webos.service.tts/getAvailableLanguages '{
"displayId":1
}'

Response:

{
"returnValue": true,
"Languages": [
"de-DE",
"en-GB",
"en-IN",
"hi-IN",
"id-ID",
"ar-XA",
"cmn-CN",
"cmn-TW",
"cs-CZ",
"da-DK",
"el-GR",
"en-AU",
"en-US",
"fi-FI",
"fil-PH",
"fr-CA",
"fr-FR",
"hu-HU",
"it-IT",
"ja-JP",
"ko-KR",
"nb-NO",
"nl-NL",
"pl-PL",
"pt-BR",
"pt-PT",
"ru-RU",
"sk-SK",
"sv-SE",
"tr-TR",
"uk-UA",
"vi-VN",
"es-ES",
"yue-HK",
"th-TH",
"bn-IN",
"gu-IN",
"kn-IN",
"ml-IN",
"ta-IN",
"te-IN"
]
}

getStatus

ACG: tts.operation

Added: API level 11

Description

Gets the current state of the service.

Parameters

Name	Required	Type	Description
displayId	Optional	Number	Indicates the unique identifier for the displays. Possible values are: 0: display 1 1: display 2 Default: 0

Name

Required

Type

Description

displayId

Optional

Number

Indicates the unique identifier for the displays.

Possible values are:

0: display 1
1: display 2

Default: 0

Call Returns

Name	Required	Type	Description
status	Required	Object: status	Indicates the current state of the service.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/getStatus '{}'

Response:

{
   "status":{
      "pitch":0,
      "status":"TTS Task is Ready",
      "speechRate":0,
      "ttsCurrLang":"en-US",
      "ttsMainLang":"en-US",
      "volume":75
   },
   "returnValue":true
}

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/getStatus '{
"displayId":1
}'

Response:

{
"status": {
"pitch": 0,
"status": "TTS task is not ready",
"ttsMenuLang": "eng",
"ttsCurrLang": "en-US",
"speech rate": 0,
"volume": 100
},
"returnValue": true
}

speak

ACG: tts.operation

Added: API level 11

Description

Reads out an input text in the language chosen by the user.

Note: It generates a series of audio as output sounds until the complete speech signal for the input text is synthesized.

Parameters

Name	Required	Type	Description
text	Required	String	Indicates the text to be converted. Note: The expected character encoding is platform-endian UTF-8.
clear	Optional	Boolean	Indicates if the current text is to be cleared. Possible values are: true: Stops processing the current text, and processes the next one. false: Processes the next text only after completing the current one. Default: false
subscribe	Optional	Boolean	Indicates if subscribed to get the notifications. Possible values are: true: Subscribe for notifications. false: (default) Not subscribed.
language	Optional	String	Indicates the language used to read the input text. Note: To get the list supported languages, use the getAvailableLanguages() method. The default language is English (en-US).
appID	Optional	String	Indicates the Application ID. Example: com.webos.app.voice
feedback	Optional	Boolean	Indicates if a unique identifier is to be returned for the input text. Possible values are: true: Provides msgIDs for texts. false: Does not provide identifiers for texts. Default: false
displayId	Optional	Number	Indicates the unique identifier for the displays. Possible values are: 0: display 1 1: display 2 Default: 0

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.
msgID	Optional	String	Indicates the unique identifier containing 12 characters that represent the input text. Note: The value is returned only if the feedback is set to true.
language	Optional	String	Indicates the language used to process the input text.

Subscription Returns

Name	Required	Type	Description
msgStatus	Optional	String	Indicates the status of the message (input text). Possible values are: done: Processing of the message is completed. stopped: Message being played is interrupted by another message. canceled: Canceled by another message before the voice output of the current message began. error: Internal error.
msgID	Optional	String	Indicates the unique identifier containing 12 characters that represent the input text. Note: The value is returned only if the feedback is set to true.
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
"text":"text to speech test",
"clear":true
}'

Response:

{
"returnValue":true
}

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
"text":"English. TTS API test.",
"language":"en-US"
}'

Response:

{
"returnValue":true
}

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"English. TTS API test.",
   "clear":true,
   "feedback":true
}'

Response:

{
   "msgID":"47709fc00000",
   "returnValue":true
}

Example scenario

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"English. TTS API test.",
   "feedback":true,
   "displayId":1
}'

Response:

{
"subscribed": false,
"returnValue": true,
"msgID": "qMihfwEXu6Az",
"language": "en-US"
}

stop

ACG: tts.operation

Added: API level 11

Description

Stops the text-to-speech processing immediately and ignores the pending text on the buffer.

Note:

There could be some noise in the output when the service is stopped abruptly. To avoid this, set the fadeOut parameter to true. This will gradually reduce the output sound to zero without any noise.
If both appID and msgID are passed in the API call, it considers only the msgID and stops the service based on the value provided by the msgID.

Parameters

Name	Required	Type	Description
appID	Optional	String	Indicates the Application ID passed in the speak() method.
msgID	Optional	String	Indicates the unique identifier containing 12 characters that represent the input text.
fadeOut	Optional	Boolean	Reduces the output sound without any noise. Possible values are: true: Gradually reduces the output sound to zero. false: Immediately stops the speech processing. This can result in unwanted noise. Default: true
displayId	Optional	Number	Indicates the unique identifier for the displays. Possible values are: 0: display 1 1: display 2 Default: 0

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of the operation. Possible values are: true: Indicates that the operation was successful. false: Indicates that the operation failed. Check the errorCode and errorText fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of the operation.

Possible values are:

true: Indicates that the operation was successful.
false: Indicates that the operation failed. Check the errorCode and errorText fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation. See the "API Error Codes Reference" section for details.

Example

Example code

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{}'

Response:

{
"returnValue":true
}

Example: Using appID

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{
"appID":"com.webos.app.tts",
"fadeOut":true
}'

Response:

{
"returnValue":true
}

Example: Using msgID

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{
"msgID":"2a487d800032",
"fadeOut":true
}'

Response:

{
"returnValue":true
}

Example: To stop messages from a particular app, when multiple appIDs are passed

Consider that the following commands were entered previously:

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"First test message.",
   "clear":false,
   "appID":"TestEven"
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"Second test message.",
   "clear":false,
   "appID":"TestOdd"
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"Third test message.",
   "clear":false,
   "appID":"TestEven"
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"Fourth test message.",
   "clear":false,
   "appID":"TestOdd"
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"Fifth test message",
   "clear":false,
   "appID":"TestEven"
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"Sixth test message.",
   "clear":false,
   "appID":"TestOdd"
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"Seventh test message.",
   "clear":false,
   "appID":"TestEven"
}'

Now, to stop messages from appID, "TestOdd", use the command:

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{
"appID":"TestOdd",
"fadeOut":true
}'

Response:

{
"returnValue":true
}

Example: To stop a particular message, when multiple msgIDs are passed

Consider that the following commands were entered previously and that they returned msgIDs for each command:

# luna-send -n 2 -f luna://com.webos.service.tts/speak '{
   "text":"It's the twelve test message.",
   "clear":false,
   "appID":"TestOdd",
   "subscribe":true
}'

# luna-send -n 1 -f luna://com.webos.service.tts/speak '{
   "text":"It's the thirteenth test message.",
   "clear":false,
   "appID":"TestEven"
}'

Now, to stop the service using the returned msgID, use the command:

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{
"msgID":"2a487d800032",
"fadeOut":true
}'

Response:

{
"returnValue":true
}

Example: With displayId

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{
"displayId":1
}'

Response:

{
"returnValue":true
}

Example: To stop particular msgId from a display

# luna-send -n 1 -f luna://com.webos.service.tts/stop '{
"msgID":"vSU2XwvwDODF",
"displayId":1
}'

Response:

{
"returnValue":true
}

Objects

status

Indicates the current state of the service.

Name	Required	Type	Description
pitch	Optional	Number (float)	Indicates the pitch value of the audio.
status	Required	String	Indicates the status of the TTS task instance. Possible values are: TTS Task is Ready TTS Task is Not Ready TTS Task is Done Error: TTS task is not running
speechRate	Optional	Number (float)	Indicates the speech rate value of the audio.
ttsCurrLang	Required	String	Indicates the language currently set/playing as obtained from the speak() API.
ttsMainLang	Required	String	Indicates the language set as the menu language as obtained from the settings service.
volume	Required	Number	Indicates the volume of the audio.

API Error Codes Reference

Error Code	Error Text	Error Description
8000	Unknown error	Unknown error.
8001	Service is not ready	TTS service is not ready.
8002	Initialize error	TTS service initialization error.
8003	Invalid parameter	Invalid parameter.
8004	Internal error	Internal interface function call error.
8005	Required parameter is missing	Parameter missing.
8006	Not supported language	Language is not supported.
8007	Not supported country	Country is not supported.
8008	Play error	Playback error.
8009	Audio resource is not available	Audio playback is not possible.
8010	Speech data creating error	TTS internal engine error.
8011	Finalize error	TTS service termination error.
8012	Service is already running	TTS service is already running.