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

(click to expand)

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

  1. Log in to Google Cloud Account
  2. 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.
  3. 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.

Open All


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

textRequiredString

Text to be converted.

The expected character encoding is platform-endian UTF-8.

clearOptionalBoolean

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

subscribeOptionalBoolean

Subscribe for notifications. Possible values are:

  • true - Get notifications.
  • false - Notifications are not required.

Default value: false

languageOptionalString

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. 

appIDOptionalString

Application ID (e.g. com.webos.app.voice).

feedbackOptionalBoolean

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

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

msgIDOptionalString

Unique identifier representing the input text. Contains 12 characters.

This value is returned only if feedback is set to true.

languageOptionalString

Language in which the input text is processed.

Subscription Returns

Name

Required

Type

Description

msgStatusOptionalString

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.
msgIDOptionalString

Unique identifier representing the input text. Contains 12 characters.

This value is returned only if feedback is set to true.

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

appIDOptionalString

Application ID passed in the speak() method. 

msgIDOptionalString

Unique identifier representing the text.

fadeOutOptionalBoolean

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

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

languagesRequiredString array

List of supported languages.

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

statusRequiredObject: status

Current state of the service.

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

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

pitchOptionalNumber (float)

Pitch value of the audio.

statusRequiredString

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
speechRateOptionalNumber (float)

Speaking rate value of the audio.

ttsCurrLangRequiredString

Language currently set/playing. Obtained from the speak() API. 

ttsMainLangRequiredString

Language set as the menu language. Obtained from the Settings service. 

volumeRequiredNumber

Volume value of the audio.


API Error Codes Reference

Error Code

Error Text

Error Description

8000Unknown error

Unknown error.

8001Service is not ready

TTS service is not ready.

8002Initialize error

TTS service initialization error.

8003Invalid parameter

Invalid parameter.

8004Internal error

Internal interface function call error.

8005Required parameter is missing

Parameter missing.

8006Not supported language

Language is not supported.

8007Not supported country

Country is not supported.

8008Play error

Playback error.

8009Audio resource is not available

Audio playback is not possible.

8010Speech data creating error

TTS internal engine error.

8011Finalize error

TTS service termination error.

8012Service is already running

TTS service is already running.


Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.