@lightningjs/sdk
Version:
The Lightning-SDK helps you build great Lightning-based TV apps!
101 lines (78 loc) • 7.11 kB
Markdown
# Announcer Library
The `Announcer` library allows for relevant information to be voiced along the focus path of the application. By passing the focus path to `Announcer.onFocusChange` the function traverses the `_focusPath` property collecting strings or promises of strings to announce to the user. The array of information is passed to a SpeechEngine which is responsible for converting the text to speech. By default we use the [speechSynthesis API](https://developer.mozilla.org/en-US/docs/Web/API/SpeechSynthesis), but you can replace this by overwriting `Announcer._textToSpeech`.
Note: The speechSynth api has some known problems:<br />
https://stackoverflow.com/questions/39391502/js-speechsynthesis-problems-with-the-cancel-method<br />
https://stackoverflow.com/questions/23483990/speechsynthesis-api-onend-callback-not-working<br />
This class does its best to work around these issues, but speech synth api can randomly fail.
## Usage
```js
import { Router, {Announcer} = Accessibility } from '@lightningjs/sdk';
export default class App extends Router.App {
...
_focusChange() {
Announcer.onFocusChange(this.application._focusPath);
}
}
```
Set `Announcer.debug = true` to see console tables of the output as shown below.
| Index | Component | Property | Value |
| ----- | ------------ | ---------- | ------------------------------------------------ |
| 0 | BrowsePage-1 | Title | Free to Me |
| 1 | Grid | Title | |
| 2 | Rows | Title | |
| 3 | Row | Title | Popular Movies - Free to Me |
| 4 | Items | Title | |
| 5 | TileItem | Title | Teenage Mutant Ninja Turtles: Out of the Shadows |
| 6 | Metadata | Announce | Promise |
| 7 | Metadata | No Context | |
| 8 | TileItem | Context | 1 of 5 |
| 9 | Items | No Context | |
| 10 | Row | No Context | |
| 11 | Rows | No Context | |
| 12 | Grid | No Context | |
| 13 | BrowsePage-1 | Context | PAUSE-2 Press LEFT or RIGHT to |
The `Announcer` will travel through the `_focusPath` looking for `component.announce` then `component.title` properties. After collecting those properties it reverses the `_focusPath` looking for `component.announceContext`.
### SpeechType
All of the properties may return values compatible with the following recursive type definition:
```
SpeechType = string | Array<SpeechType> | Promise<SpeechType> | () => SpeechType
```
At its simplest, you may return a string or an array of strings. Promises and functions that return SpeechType values may be used as necessary for advanced/asyncronous use cases.
#### Examples
```js
get announce() {
return [
'Despicable Me',
Promise.resolve([
['2020', 'Rated PG'],
Promise.resolve('Steve Carell, Miranda Cosgrove, Kristen Wiig, Pierre Coffin'),
() => 'A description of the movie'
])
];
}
get announceContext() {
return 'Press LEFT or RIGHT to review items';
}
```
## Inserting a pause
You may also use `PAUSE-#` to pause speech for # seconds before saying the next string.
```js
get announceContext() {
return ['PAUSE-2.5', 'Hello there!'];
}
```
## API
### Properties
| name | type | readonly | description |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enabled | boolean | false | default true - flag to turn on or off Announcer |
| announcerTimeout | number | false | By default the announcer only gets information about what changed between focus paths. The announcerTimeout resets the cache to announce the full focus path when the user has been inactive a certain amount of time. Default value is 5 minutes. |
### Methods
| name | args | description |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| speak | | Performs a manual announce |
| | `announcement` | See _SpeechType_ above |
| | `options` | Object containing one or more boolean flags: <br/><ul><li>append - Appends announcement to the currently announcing series.</li><li>notification - Speaks out notification and then performs $announcerRefresh.</li></ul> |
| clearPrevFocus | `depth` | Clears the last known focusPath - depth can trim known focusPath |
| cancel | none | Cancels current speaking |
| setupTimers | `options` | Object containing: <br/><ul><li>focusDebounce - default amount of time to wait after last input before focus change announcing will occur.</li><li>focusChangeTimeout - Amount of time with no input before full announce will occur on next focusChange</li></ul> |