VoiceGuidance Module

Version 0.1.0-alpha.4

A module for managing voice-guidance Settings.

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.

• Overview

• OpenRPC

• Usage

• Methods

  • enabled
  • listen
  • once
  • provide
  • speed
  • Additional Methods

• Events

  • Additional Events

• Provider Interfaces

  • SettingsProvider

• Schemas

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

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

Whether or not voice-guidance is enabled.

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

function enabled(): Promise<boolean>

Promise resolution:

Examples

Default Example

JavaScript:

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

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

Value of enabled:

true

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

{
  "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:

Promise resolution:

Examples

JavaScript:

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

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

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

{
  "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:

Promise resolution:

Callback parameters:

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

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

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

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

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:

Promise resolution:

Callback parameters:

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:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

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:

Promise resolution:

Callback parameters:

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:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

Register to provide a capability from this module.

See Provider Interfaces, for more info.

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

Parameters:

Promise resolution:

void

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:

Examples

Default Example

JavaScript:

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

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

Value of speed:

1

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

{
  "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:

Promise resolution:

Examples

JavaScript:

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

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

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

{
  "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:

Promise resolution:

Callback parameters:

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

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

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

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

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

For more information, follow the links under the “Documentation” column.

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

For more information, follow the links under the “Documentation” column.

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
}

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)

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:

Promise resolution:

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

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

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

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

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

{
    "id": 2,
    "result": true
}