Voice Guidance Implementation

Voice Guidance is the Entertainment OS text-to-speech feature that gives blind and sight-impaired users the freedom to independently explore the full catalog of programs and experiences on their device.

Overview

Voice Guidance reads on-screen elements aloud as users move through your app. Users have the options to turn the feature on, enable or disable navigation hints, and choose how fast it speaks. Your app is responsible for honoring all 3 settings.

To support Voice Guidance in your app:

1. Set up your app so the platform can voice its content. Refer to Voice Guidance methods.
2. Read the user's Voice Guidance settings when your app starts. Refer to Reading device settings.
3. Listen for changes to those settings while your app runs. Refer to Adapting to real-time changes.

Voice Guidance methods

How you enable Voice Guidance depends on how you build your app:

• HTML5 apps work with Voice Guidance when you follow proper markup structure and labeling conventions.
• Lightning apps voice the strings along your app's focus path when you enable the Announcer mixin.

Entertainment OS supports 2 methods for voicing content: WebSpeech and Aria.

WebSpeech

WebSpeech offers a wide range of customization, but it has a lower accessibility standard than Aria.

Entertainment OS supports the following WebSpeech APIs:

• speak
• cancel
• onStart
• onEnd

Your app can listen for the onStart and onEnd event notifications through WebSpeech.

Aria

Aria reads content more directly than WebSpeech and meets a higher accessibility standard.

For examples of how the core Entertainment OS UI uses these methods, refer to the Voice guidance scripting examples.

Voice Guidance settings

Voice Guidance has 3 settings, detailed below. The enabled setting is the primary one. The navigationHints and rate settings let users customize their experience.

Navigation hints

Navigation hints give users extra context about the screen they're on and how to navigate it. Users can turn them off to make Voice Guidance less verbose. For examples of hints, refer to the Voice guidance scripting examples.

Speech rate

The rate value controls how quickly or slowly Voice Guidance reads on-screen elements. The numeric value maps to 5 user-facing settings on Entertainment OS devices. The default is Medium.

Reading device settings

To read the user's Voice Guidance settings, call the Accessibility.voiceGuidanceSettings() method:

import { Accessibility } from '@firebolt-js/sdk'

const vgSettings = await Accessibility.voiceGuidanceSettings()

if (vgSettings.enabled) {
  // the user has voice guidance enabled
}

Your app must also respect the user's navigation hints and rate preferences. Continuing from the previous example, you can access the navigationHints and rate properties:

console.log(vgSettings.navigationHints)
console.log(vgSettings.rate)

The following example shows the settings that Accessibility.voiceGuidanceSettings() returns:

{
  "enabled": true,
  "navigationHints": false,
  "rate": 1.19
}

Adapting to real-time changes

Users can change their Voice Guidance settings while your app is running or playing content. Your app must respond promptly by listening for all voiceGuidanceSettingsChanged events:

import { Accessibility } from '@firebolt-js/sdk'

Accessibility.listen('voiceGuidanceSettingsChanged', vgSettings => {
  // vgSettings is the same structure returned from `voiceGuidanceSettings()`
  if (vgSettings.enabled) {
    // update your app's voice guidance rate and navigation hints
    console.log(vgSettings.rate)
    console.log(vgSettings.navigationHints)
  }
  else {
    // turn off your app's voice guidance
  }
})

Recommended user journeys implementations

The following example user journeys are recommended implementations based on the Entertainment OS Voice Guidance framework. They give users a seamless Voice Guidance experience from the Entertainment OS UI, through your app, and to content playback.

Commonly used terms

• Press: Used for navigational instructions, or where an action might need multiple presses (e.g., recording a program or adjusting the volume).
• Select: Used for an action that uses the D-pad (e.g., "Select to choose").

Abbreviations

Voice Guidance reads some abbreviations in full and others as they appear on screen. The following abbreviations apply in the UK and the Republic of Ireland:

Voice Guidance on Sky rails

Users can select your app's content from several places in the Entertainment OS UI. Voice Guidance supports them all the way to playback in your app.

When a user selects a show from your app in the Entertainment OS UI:

1. The user selects a show from your app from one of the following places:
   • Merchandising
   • A voice or text search journey
   • A Show page
2. Voice Guidance supports the user through to playback in your app's full-screen experience

Voice Guidance on Continue Watching rails

Voice Guidance provides a seamless experience between the Entertainment OS UI and your app when users resume content.

When a user selects a show from your app in a Continue Watching rail:

1. The user selects a show from your app in an Entertainment OS Continue Watching rail
2. Voice Guidance supports the user through to playback in your app's full-screen experience

Voice Guidance on the Show page hero zone

When a user navigates to a Show page, Voice Guidance reads the following in order:

1. The name of the program (e.g., "The Office")
2. The label for the action item in focus (e.g., "Start download")
3. A navigation hint: "Press down for categories"
4. The metadata for the program asset in focus:
   • Title of the program or episode
   • Channel or provider (if required in apps with multiple providers)
   • Duration
   • Classification (e.g., "12"), if any
   • Quality (e.g., "UHD")
   • Accessibility services, read in full rather than abbreviated (e.g., "AD" is read as "Audio Description")
   • Synopsis
   • Playlist or watchlist status, if any
5. A navigation hint for the focused item: "x of n; Select to choose"

Voice Guidance for app launch points

When a user launches your app from the Entertainment OS UI:

1. The user launches your app from one of the following places:
   • The Switcher
   • An apps rail
   • A voice command
2. Voice Guidance supports the user through their journey to playback in your app's full-screen experience

Voice Guidance on content rails

When a user presses Select or Right on their remote to move from a menu screen into a section with rails, Voice Guidance reads the following in order:

1. A container hint when the user enters a new page in the UI (e.g., "Home"), not repeated for later rails in the same section
2. A navigation hint: "Press Up, Down, Left or Right"
3. The title of the rail in focus (e.g., "Today's Picks")
4. A navigation hint: "Press left or right to navigate through content"
5. The metadata for the asset in focus:
   • Title of the asset
   • Channel or provider, if any
   • Duration, if any
   • Classification (e.g., "12"), if any
   • Quality, if any
   • Accessibility services, if any
   • Synopsis
6. A navigation hint for the focused item: "x of n; Select to choose"

Voice Guidance on app navigation rails

When a user lands on a rail used for navigation, Voice Guidance reads the following in order:

1. Where the user is in the UI, using the rail's container hint or title (refer to the following table)
2. A navigation hint: "Press left or right to navigate"
3. The name of the tile in focus: "[Tile name]"
4. The user's location in the rail: "x of n"
5. A navigation hint for the focused item: "Select to choose"

Use the following container hints or titles for each type of navigation rail:

Haptic sounds

Haptic sounds let users know that there are no further items available.

The user hears a haptic sound when they try to move further after reaching:

• The last item in a rail, to the left or right
• The top or bottom of a column in a grid of items
• The right-hand end of a row in a grid of items

Grid of items

When a user is in a grid of items (e.g., video-on-demand assets in a genre), Voice Guidance reads the following in order:

1. The title of the grid (e.g., "Featured")
2. A navigation hint: "Grid of items; Press Up, Down, Left or Right to navigate"
3. The metadata for the program asset in focus:
   • Title of the asset or program
   • Channel or provider, if any
   • Duration, if any
   • Classification (e.g., "12"), if any
   • Quality, if any
   • Accessibility services, if any
   • Synopsis
4. A navigation hint for the focused item: "x of n; Row y; Select to choose"

Notifications

When the UI shows a dialog or notification message with a binary choice of actions, Voice Guidance reads the following in order:

1. A notification announcement: "Notification"
2. The message as it appears on screen (e.g., "Are you sure you want to delete this?")
3. A navigation hint: "Press left or right for options"
4. The action item in focus (e.g., "Cancel")
5. A navigation hint: "x of n; Select to choose"

When the UI shows a banner notification, Voice Guidance reads the following in order:

1. A notification announcement: "Notification"
2. The message as it appears on screen (e.g., "Because of a technical issue...")

Some notifications prompt the user to press Help on their remote. If the user presses Help, Voice Guidance reads a further navigation hint: "Voice guidance not available."

PIN entry

When the UI shows a parental PIN entry screen, Voice Guidance reads the following in order:

1. The notification as it appears on screen: "[Program name]. This is a PIN protected program"
2. A PIN entry prompt: "Please enter your PIN"
3. The number of the focused item: "1 of 4"
4. The number of each focused item in turn as the user enters their PIN (i.e., "2 of 4" through "4 of 4")