Skip to content

Latest commit

 

History

History
1058 lines (812 loc) · 24.7 KB

TextToSpeechPlugin.md

File metadata and controls

1058 lines (812 loc) · 24.7 KB

TextToSpeech Plugin

A org.rdk.TextToSpeech plugin for Thunder framework.

Table of Contents

Abbreviation, Acronyms and Terms

[Refer to this link]

Description

The TextToSpeech plugin provides TTS functionality (Voice Guidance & Speech Synthesis) for the client application.

The plugin is designed to be loaded and executed within the Thunder framework. For more information about the framework refer to [Thunder].

Configuration

The table below lists configuration options of the plugin.

Name Type Description
callsign string Plugin instance name (default: org.rdk.TextToSpeech)
classname string Class name: org.rdk.TextToSpeech
locator string Library name: libWPEFrameworkTextToSpeech.so
autostart boolean Determines if the plugin shall be started automatically along with the framework

Methods

The following methods are provided by the org.rdk.TextToSpeech plugin:

TextToSpeech interface methods:

Method Description
cancel Cancels the speech
enabletts (For Resident App) Enables or disables the TTS conversion processing
getapiversion Gets the API Version
getspeechstate Returns the current state of the speech request
getttsconfiguration Gets the current TTS configuration
isspeaking Checks if speech is in progress
isttsenabled Returns whether the TTS engine is enabled or disabled
listvoices Lists the available voices for the specified language
pause Pauses the speech
resume Resumes the speech
setttsconfiguration Sets the TTS configuration
speak Converts the input text to speech when TTS is enabled
setACL Configures app to speak

cancel

Cancels the speech. Triggers the onspeechinterrupted

Events

Event Description
onspeechinterrupted Triggered when ongoing speech is cancelled. Event is not triggered: if TTS is not enabled; if ongoing Speech is completed

Parameters

Name Type Description
params object
params.speechid number The speech ID

Result

Name Type Description
result object
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.cancel",
    "params": {
        "speechid": 1
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "TTS_Status": 0,
        "success": true
    }
}

enabletts

(For Resident App) Enables or disables the TTS conversion processing. Triggered onttsstatechanged event when state changes and onspeechinterrupted event when disabling TTS while speech is in-progress.

Events

Event Description
onttsstatechanged state : true Triggered when TTS is enabled; state : false Triggered when TTS is disabled; otherwise No event When TTS enable or disable is in-progress
onspeechinterrupted Triggered when disabling TTS while speech is in-progress.

Parameters

Name Type Description
params object
params.enabletts boolean Enable or Disable TTS

Result

Name Type Description
result object
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.enabletts",
    "params": {
        "enabletts": true
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "TTS_Status": 0,
        "success": true
    }
}

getapiversion

Gets the API Version.

Events

No Events

Parameters

This method takes no parameters.

Result

Name Type Description
result object
result.version number Indicates the API Version
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.getapiversion"
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "version": 1,
        "success": true
    }
}

getspeechstate

Returns the current state of the speech request.

Events

No Events

Parameters

Name Type Description
params object
params.speechid number The speech ID

Result

Name Type Description
result object
result.speechstate string The speech state (must be one of the following: SPEECH_PENDING(0), SPEECH_IN_PROGRESS(1), SPEECH_PAUSED(2), SPEECH_NOT_FOUND(3))
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.getspeechstate",
    "params": {
        "speechid": 1
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "speechstate": "SPEECH_IN_PROGRESS",
        "TTS_Status": 0,
        "success": true
    }
}

getttsconfiguration

Gets the current TTS configuration.

Events

No Events

Parameters

This method takes no parameters.

Result

Name Type Description
result object
result.ttsendpoint string The TTS engine URL
result.ttsendpointsecured string The TTS engine secured URL
result.language string The TTS language
result.voice string The TTS Voice
result.volume string The TTS Volume
result.rate number The TTS Rate
result?.speechrate string (optional) TTS Rate for TTS2 endpoint
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.getttsconfiguration"
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "ttsendpoint": "http://url_for_the_text_to_speech_processing_unit",
        "ttsendpointsecured": "https://url_for_the_text_to_speech_processing_unit",
        "language": "en-US",
        "voice": "carol",
        "volume": "100.000000",
        "rate": 50,
        "speechrate": "medium",
        "TTS_Status": 0,
        "success": true
    }
}

isspeaking

Checks if speech is in progress.

Events

No Events

Parameters

Name Type Description
params object
params.speechid number The speech ID

Result

Name Type Description
result object
result.speaking boolean true if the passed speech is in progress (that is, audio was playing), false if speech is completed or speech ID not found
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.isspeaking",
    "params": {
        "speechid": 1
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "speaking": true,
        "TTS_Status": 0,
        "success": true
    }
}

isttsenabled

Returns whether the TTS engine is enabled or disabled. By default the TTS engine is disabled.

Events

No Events

Parameters

This method takes no parameters.

Result

Name Type Description
result object
result.isenabled boolean true if the TTS engine is enabled, otherwise false
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.isttsenabled"
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "isenabled": true,
        "TTS_Status": 0,
        "success": true
    }
}

listvoices

Lists the available voices for the specified language. For every language there is a set of pre-defined voices.

Events

No Events

Parameters

Name Type Description
params object
params.language string The TTS language

Result

Name Type Description
result object
result.voices string Array of available voice
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.listvoices",
    "params": {
        "language": "en-US"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "voices": "carol",
        "TTS_Status": 0,
        "success": true
    }
}

pause

Pauses the speech. Triggers the onspeechpause

Events

Event Description
onspeechpause Triggered when ongoing speech is paused. Event not triggered on following conditions: TTS is not enabled; Speech is already in pause; or Speech is completed

Parameters

Name Type Description
params object
params.speechid number The speech ID

Result

Name Type Description
result object
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.pause",
    "params": {
        "speechid": 1
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "TTS_Status": 0,
        "success": true
    }
}

resume

Resumes the speech. Triggers the onspeechresume

Events

Event Description
onspeechresume Triggered when speech is resumed and speech output is available. Event not triggered under following conditions: TTS is not enabled; Speech is resumed already; or Speech is completed

Parameters

Name Type Description
params object
params.speechid number The speech ID

Result

Name Type Description
result object
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.resume",
    "params": {
        "speechid": 1
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "TTS_Status": 0,
        "success": true
    }
}

setttsconfiguration

Sets the TTS configuration. Triggers the onvoicechanged

Events

Event Description
onvoicechanged Triggered only when the voice configuration is changed

Parameters

Name Type Description
params object
params?.ttsendpoint string (optional) The TTS engine URL
params?.ttsendpointsecured string (optional) The TTS engine secured URL
params?.language string (optional) The TTS language
params?.voice string (optional) The TTS Voice
params?.volume string (optional) The TTS Volume
params?.primvolduckpercent number (optional) The TTS Primary Volumeduckpercentage
params?.rate number (optional) The TTS Rate
params?.speechrate string (optional) TTS Rate for TTS2 endpoint
params?.fallbacktext object (optional)
params?.fallbacktext?.scenario string (optional) Describes the scenario where fallback text is to be used . At present, only offline is supported
params?.fallbacktext?.value string (optional) The Text which is to be spoken when the scenario is met
params?.authinfo object (optional)
params?.authinfo?.type string (optional) The type of authentication. At present, only apikey is supported
params?.authinfo?.value string (optional) x api key(secret key) required for GCD Endpoints

Result

Name Type Description
result object
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.setttsconfiguration",
    "params": {
        "ttsendpoint": "http://url_for_the_text_to_speech_processing_unit",
        "ttsendpointsecured": "https://url_for_the_text_to_speech_processing_unit",
        "language": "en-US",
        "voice": "carol",
        "volume": "100.000000",
        "primvolduckpercent": 25,
        "rate": 50,
        "speechrate": "medium",
        "fallbacktext": {
            "scenario": "offline",
            "value": "No Internet connection"
        },
        "authinfo": {
            "type": "apikey",
            "value": "XXXXXXXXXXXX"
        }
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "TTS_Status": 0,
        "success": true
    }
}

speak

Converts the input text to speech when TTS is enabled. Any ongoing speech is interrupted and the newly requested speech is processed. The clients of the previous speech is sent an onspeechinterrupted Upon success, this API returns an ID, which is used as input to other API methods for controlling the speech (for example, pause, resume, and cancel).

Events

Event Description
onwillspeak Triggered when speech conversion is about to start
onspeechstart Triggered when conversion of text to speech is started
onspeechinterrupted Current speech is interrupted either by a next speech request; by calling the cancel method; or by disabling TTS, when speech is in-progress
onspeechcomplete Triggered when conversion from text to speech is completed
onnetworkerror Triggered when failed to fetch audio from the endpoint
onplaybackerror Triggered when an error occurs during playback including pipeline failures; Triggered when speak is called during TTS disabled

Parameters

Name Type Description
params object
params.text string The text input
params?.callsign string (optional) Callsign of the application. This is mandatory when setACL is called prior to speak

Result

Name Type Description
result object
result.speechid number The speech ID
result.TTS_Status number (must be one of the following: TTS_OK(0), TTS_FAIL(1), TTS_NOT_ENABLED(2), TTS_INVALID_CONFIGURATION(3))
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.speak",
    "params": {
        "text": "speech_1",
        "callsign": "WebApp"
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "speechid": 1,
        "TTS_Status": 0,
        "success": true
    }
}

setACL

Configures app to speak. Allows the ResidentAPP to configure the particular app and provides access to speak If not configured any then gives access to all apps to speak. Configuration does not retained after reboot.

Events

No Events

Parameters

Name Type Description
params object
params.accesslist array
params.accesslist[#] object
params.accesslist[#].method string Method of TTS function to be performed
params.accesslist[#].apps array List of client application
params.accesslist[#].apps[#] string

Result

Name Type Description
result object
result.success boolean Whether the request succeeded

Example

Request

{
    "jsonrpc": "2.0",
    "id": 42,
    "method": "org.rdk.TextToSpeech.setACL",
    "params": {
        "accesslist": [
            {
                "method": "speak",
                "apps": [
                    "App1"
                ]
            }
        ]
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 42,
    "result": {
        "success": true
    }
}

Notifications

Notifications are autonomous events, triggered by the internals of the implementation, and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the org.rdk.TextToSpeech plugin:

TextToSpeech interface events:

Event Description
onnetworkerror Triggered when a network error occurs while fetching the audio from the endpoint
onplaybackerror Triggered when an error occurs during playback including pipeline failures
onspeechcomplete Triggered when the speech completes
onspeechinterrupted Triggered when the current speech is interrupted either by a next speech request, by calling cancel or by disabling TTS, when speech is in progress
onspeechpause Triggered when the ongoing speech pauses
onspeechresume Triggered when any paused speech resumes
onspeechstart Triggered when the speech start
onttsstatechanged Triggered when TTS is enabled or disabled
onvoicechanged Triggered when the configured voice changes
onwillspeak Triggered when the text to speech conversion is about to start

onnetworkerror

Triggered when a network error occurs while fetching the audio from the endpoint.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onnetworkerror",
    "params": {
        "speechid": 1
    }
}

onplaybackerror

Triggered when an error occurs during playback including pipeline failures.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onplaybackerror",
    "params": {
        "speechid": 1
    }
}

onspeechcomplete

Triggered when the speech completes.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onspeechcomplete",
    "params": {
        "speechid": 1
    }
}

onspeechinterrupted

Triggered when the current speech is interrupted either by a next speech request, by calling cancel or by disabling TTS, when speech is in progress.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onspeechinterrupted",
    "params": {
        "speechid": 1
    }
}

onspeechpause

Triggered when the ongoing speech pauses.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onspeechpause",
    "params": {
        "speechid": 1
    }
}

onspeechresume

Triggered when any paused speech resumes.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onspeechresume",
    "params": {
        "speechid": 1
    }
}

onspeechstart

Triggered when the speech start.

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onspeechstart",
    "params": {
        "speechid": 1
    }
}

onttsstatechanged

Triggered when TTS is enabled or disabled.

Parameters

Name Type Description
params object
params.state boolean True if TTS is enabled, otherwise False

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onttsstatechanged",
    "params": {
        "state": true
    }
}

onvoicechanged

Triggered when the configured voice changes.

Parameters

Name Type Description
params object
params.voice string The TTS Voice

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onvoicechanged",
    "params": {
        "voice": "carol"
    }
}

onwillspeak

Triggered when the text to speech conversion is about to start. It provides the speech ID, generated for the text input given in the speak

Parameters

Name Type Description
params object
params.speechid number The speech ID

Example

{
    "jsonrpc": "2.0",
    "method": "client.events.onwillspeak",
    "params": {
        "speechid": 1
    }
}