Skip to content

VoiceGuidance

Jump to bottom
LaCivita, Jeremy edited this page May 26, 2022 · 1 revision

Version The Firebolt JS Manage SDK [Alpha 4]

Overview

A module for managing voice-guidance Settings.

OpenRPC

Firebolt APIs are maintained in the rdkcentral/firebolt-manage-sdk.git GitHub repository.

You can see this API in the voiceguidance.json OpenRPC JSON-Schema document.

Table of Contents

Usage

To use the VoiceGuidance module, you can import it into your project from the Firebolt SDK:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

Methods

enabled

Whether or not voice-guidance is enabled.

To get the value, call the method with no parameters:

function enabled(): Promise<boolean>

Promise resolution:

Type Description
boolean

Examples

Default Example

JavaScript:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

VoiceGuidance.enabled()
    .then(enabled => {
        console.log(enabled)
    })

Value of enabled:

true
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voiceguidance.enabled",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

To set the value, pass in the new value as the only parameter:

function enabled(value: boolean): Promise<void>

Parameters:

Param Type Required Summary
value boolean true

Promise resolution:

Type Summary
void Promise resolves with no value when the operation is complete.

Examples

JavaScript:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

VoiceGuidance.enabled(true)
    .then(response => {
        // property value has been set
    })
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voiceguidance.setEnabled",
  "params": {
    "value": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function enabled(subscriber: (enabled: boolean) => void): Promise<boolean>

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for enabled changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with VoiceGuidance.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
enabled boolean Yes

Examples

Default Example

JavaScript:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

VoiceGuidance.enabled(enabled => {
  // property value was changed
  console.log(enabled)
}).then(listenerId => {
  // you can clear this listener w/ VoiceGuidance.clear(listenerId)
})

value of enabled:

true
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voiceguidance.onEnabledChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}

listen

Listen for events from this module.

To listen to a specific event pass the event name as the first parameter:

VoiceGuidance.listen(event: string, (data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. VoiceGuidance.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

VoiceGuidance.listen((event: string, data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. VoiceGuidance.clear(id)

See Listening for events for more information and examples.

once

Listen for only one occurance of an event from this module. The callback will be cleared after one event.

To listen to a specific event pass the event name as the first parameter:

VoiceGuidance.once(event: string, (data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. VoiceGuidance.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

VoiceGuidance.once((event: string, data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. VoiceGuidance.clear(id)

See Listening for events for more information and examples.

provide

Register to provide a capability from this module.

See Provider Interfaces, for more info.

function provide(provider: object | class): Promise<void>

Parameters:

Param Type Required Summary
provider `object class` true

Promise resolution:

void

speed

The speed at which voice guidance speech will be read back to the user.

To get the value, call the method with no parameters:

function speed(): Promise<VoiceSpeed>

Promise resolution:

Type Description
VoiceSpeed

Examples

Default Example

JavaScript:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

VoiceGuidance.speed()
    .then(speed => {
        console.log(speed)
    })

Value of speed:

1
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voiceguidance.speed",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 1
}

To set the value, pass in the new value as the only parameter:

function speed(value: VoiceSpeed): Promise<void>

Parameters:

Param Type Required Summary
value VoiceSpeed true

Promise resolution:

Type Summary
void Promise resolves with no value when the operation is complete.

Examples

JavaScript:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

VoiceGuidance.speed(1)
    .then(response => {
        // property value has been set
    })
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voiceguidance.setSpeed",
  "params": {
    "value": 1
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}

To subscribe to notifications when the value changes, pass a function as the only parameter:

function speed(subscriber: (speed: VoiceSpeed) => void): Promise<boolean>

Parameters:

Param Type Required Summary
subscriber Function Yes A callback that gets invoked when the value for speed changes

Promise resolution:

Type Summary
listenerId The id of the listener that can be used with VoiceGuidance.clear(listenerId) to unsubscribe

Callback parameters:

Param Type Required Summary
speed VoiceSpeed Yes

Examples

Default Example

JavaScript:

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

VoiceGuidance.speed(speed => {
  // property value was changed
  console.log(speed)
}).then(listenerId => {
  // you can clear this listener w/ VoiceGuidance.clear(listenerId)
})

value of speed:

1
JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "voiceguidance.onSpeedChanged",
  "params": {
    "listen": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 1
}

Additional methods

The following methods are documented as part of a related set of method APIs.

For more information, follow the links under the "Documentation" column.

JavaScript RPC Parameters Documentation
NA setEnabled (enabled?: boolean) enabled
NA setSpeed (speed?: VoiceSpeed) speed
NA settingsResponse (response: ProviderResponse) SettingsProvider

Events

Additional events

The following events are documented as part of a related set of method APIs.

For more information, follow the links under the "Documentation" column.

JavaScript RPC Payload Documentation
NA onRequestSettings object
enabledChanged onEnabledChanged boolean enabled
speedChanged onSpeedChanged VoiceSpeed speed

Provider Interfaces

Providers are interfaces that your app can implement in order to provide certain capabilties back to the platform.

To register a provider, use the provide() method.

Every provider interface method has the following signature:

(parameters: object | void, session: ProviderSession) => {}

ProviderSession has the following interface:

interface ProviderSession {
    correlationId(): string        // Returns the correlation id of the current provider session
}

SettingsProvider

The provider interface for the xrn:firebolt:capability:settings:voiceguidance capability.

interface SettingsProvider {
	settings(parameters?: void, session?: ProviderSession): Promise<VoiceGuidanceSettings>
}

Usage:

VoiceGuidance.provide('xrn:firebolt:capability:settings:voiceguidance', provider: SettingsProvider | object)

settings

Dispatches a request for the current voice-guidance settings to the voice-guidance settings provider.

function settings(parameters?: void, session?: ProviderSession): Promise<VoiceGuidanceSettings>

Provider methods always have two arguments:

Param Type Required Summary
parameters void false
session ProviderSession false

Promise resolution:

Type Description
VoiceGuidanceSettings

Examples

Register your app to provide the xrn:firebolt:capability:settings:voiceguidance capability.

import { VoiceGuidance } from '@firebolt-js/manage-sdk'

class MySettingsProvider {

    async settings(parameters, session) {
        return await Promise.resolve({
            "enabled": true,
            "speed": 2
        })
    }

}

VoiceGuidance.provide('xrn:firebolt:capability:settings:voiceguidance', new MySettingsProvider())
**JSON-RPC**

Register to recieve each provider API

Request:

{
    "id": 1,
    "method": "onRequestSettings",
    "params": {
        "listen": true
    }
}

Response:

{
    "id": 1,
    "result": {
        "listening": true,
        "event": "VoiceGuidance.onRequestSettings"
    }            
 
}

Asynchronous event to initiate settings()

Event Response:

{
    "id": 1,
    "result": {
        "correlationId": "xyz",
        "parameters": null
    }
}

App initiated response to event

Request:

{
    "id": 2,
    "method": "settingsResponse",
    "params": {
        "response": {
            "correlationId": "xyz",
            "result": {
                "enabled": true,
                "speed": 2
            }
        }
    }
}

Response:

{
    "id": 2,
    "result": true
}
Clone this wiki locally