com.webos.service.tts

API Summary

The TTS (Text-to-Speech) service 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 Google Cloud Account.
Go to 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

speak

Description

Reads out an input text in the language of your choice.

It generates a series of audio and outputs sound until the complete speech signal for the input text is synthesized.

Parameters

Name	Required	Type	Description
text	Required	String	Text to be converted. 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 value: false
subscribe	Optional	Boolean	Subscribe for notifications. Possible values are: true - Get notifications. false - Notifications are not required. Default value: false
language	Optional	String	Language in which the input text is read out. Default language is English (en-US). Note: To get the list supported languages, use the getAvailableLanguages() method.
appID	Optional	String	Application ID (e.g. 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 value: false

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	Unique identifier representing the input text. Contains 12 characters. This value is returned only if feedback is set to true.
language	Optional	String	Language in which the input text is processed.

Subscription Returns

Name	Required	Type	Description
msgStatus	Optional	String	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	Unique identifier representing the input text. Contains 12 characters. This value is returned only if feedback is set to true.
returnValue	Required	Boolean	Indicates the status of 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 1:

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

Response:

{
"returnValue":true
}

Example 2:

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

Response:

{
"returnValue":true
}

Example 3:

# 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
}

stop

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, you can 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 will consider only the msgID and stop the service based on this value.

Parameters

Name	Required	Type	Description
appID	Optional	String	Application ID passed in the speak() method.
msgID	Optional	String	Unique identifier representing the 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 value: true

Name

Required

Type

Description

appID

Optional

String

Application ID passed in the speak() method.

msgID

Optional

String

Unique identifier representing the 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 value: true

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 1: With no parameters

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

Response:

{
"returnValue":true
}

Example 2: Using appID

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

Response:

{
"returnValue":true
}

Example 3: Using msgID

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

Response:

{
"returnValue":true
}

Example 4: To stop messages from a particular app, when multiple app IDs 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 5: To stop a particular message, when multiple msg IDs 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
}

getAvailableLanguages

Description

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

Parameters

None

Call Returns

Name	Required	Type	Description
languages	Required	String array	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

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

Response:

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

getStatus

Description

Gets the current state of the service.

Parameters

None

Call Returns

Name	Required	Type	Description
status	Required	Object: status	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

# 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
}

Objects

status

Object to depict the current state of the service.

Name	Required	Type	Description
pitch	Optional	Number (float)	Pitch value of the audio.
status	Required	String	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)	Speaking rate value of the audio.
ttsCurrLang	Required	String	Language currently set/playing. Obtained from the speak() API.
ttsMainLang	Required	String	Language set as the menu language. Obtained from the Settings service.
volume	Required	Number	Volume value 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.