Menu

Reference

com.webos.service.tts

API Summary

Converts the 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. 

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

Methods

speak

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

textRequiredString

Indicates the text to be converted.

Note: 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: false

subscribeOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribe for notifications
  • false: Not subscribed

Default: false

languageOptionalString

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).
appIDOptionalString

Indicates the Application ID.

Example: 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: false

displayIdOptionalNumber

Indicates the unique identifier for the displays.

Possible values are: 

  • 0: display 1
  • 1: display 2

Default: 0

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

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.

languageOptionalString

Indicates the language used to process the input text.

Subscription Returns

Name

Required

Type

Description

msgStatusOptionalString

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

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.

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/speak '{
   "text":"text to speech test",
   "clear":true
}'

Response:

{  
   "returnValue":true
}

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

Response:

{  
   "returnValue":true
}

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

# 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

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

appIDOptionalString

Indicates the Application ID passed in the speak() method. 

msgIDOptionalString

Indicates the unique identifier containing 12 characters that represent the input 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: true

displayIdOptionalNumber

Indicates the unique identifier for the displays.

Possible values are: 

  • 0: display 1
  • 1: display 2

Default: 0

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

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

Response:

{  
   "returnValue":true
}

Using appID

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

Response:

{  
   "returnValue":true
}

Using msgID

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

Response:

{  
   "returnValue":true
}

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
}

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
}

With displayId

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

Response:

{  
   "returnValue":true
}

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
}

getAvailableLanguages

Description

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

Parameters

Name

Required

Type

Description

displayIdOptionalNumber

Indicates the unique identifier for the displays.

Possible values are: 

  • 0: display 1
  • 1: display 2

Default: 0

Call Returns

Name

Required

Type

Description

languagesRequiredString array

Indicates the 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
}

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

Description

Gets the current state of the service. 

Parameters

Name

Required

Type

Description

displayIdOptionalNumber

Indicates the unique identifier for the displays.

Possible values are: 

  • 0: display 1
  • 1: display 2

Default: 0

Call Returns

Name

Required

Type

Description

statusRequiredObject: status

Indicates the 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
}

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

Objects

status

Indicates the current state of the service.

Name

Required

Type

Description

pitchOptionalNumber (float)

Indicates the pitch value of the audio.

statusRequiredString

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

Indicates the speech rate value of the audio.

ttsCurrLangRequiredString

Indicates the language currently set/playing as obtained from the speak() API. 

ttsMainLangRequiredString

Indicates the language set as the menu language as obtained from the settings service. 

volumeRequiredNumber

Indicates the volume 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 otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 and sample code is licensed under the Apache License 2.0.

Contents