Skip to main content

Inclusion and the Audio Guide

Hosanna's audio-guide pipeline speaks an optional IAudioGuideItem when focus moves to a view. On web, launch with ?textToSpeech=true to exercise speech during development.

This API covers spoken focus feedback. Keyboard access, focus order, contrast, captions, localization, touch target size, and reduced-motion behavior still need explicit product testing.

Built-in spoken output​

BaseView speaks nothing unless audioGuideItem is set or the component overrides getAudioGuideItem().

Current built-in behavior includes:

  • Label, SimpleLabel, and VerticalText: their displayed text;
  • Button: Button:, its text, and audioGuideHint;
  • CheckBox: its text, checked state, and hint;
  • ComboBox: its selected value, open/closed state, and hint; and
  • TextInput: its text-entry state and hint.

Image and generic containers have no automatic ID-based fallback.

Supply a custom item​

Use a string for the common case:

Button({
  text: 'Rent',
  audioGuideItem: 'Rent this movie',
})

configureAudioGuideItem() converts a string to an item with priority 10, dontRepeat: true, and flushPrevious: true, and sets its origin to the view.

Use an object for queue control:

Button({
  text: 'Retry',
  audioGuideItem: {
    text: 'Retry download',
    priority: 5,
    flushPrevious: true,
    dontRepeat: true,
    type: IAudioGuideItemType.Information,
  },
})

An IAudioGuideItem supports text, priority, type, flushPrevious, origin, and dontRepeat.

For a custom component, override getAudioGuideItem():

override getAudioGuideItem(): IAudioGuideItem | undefined {
  if (!this.visibleTitle) {
    return undefined;
  }
  return this.configureAudioGuideItem(
    `Episode ${this.episodeNumber}: ${this.visibleTitle}`,
  );
}

Queue and priority behavior​

Focus asks the text-to-speech manager to speak immediately after onFocus(); there is no built-in 250–400 ms focus delay.

Priority defaults to 10. In the current queue implementation, smaller numbers are retained ahead of larger ones. When flushPrevious is omitted or true, flush(incomingPriority) removes queued items with an equal or numerically larger priority and interrupts a current item in that same range.

Use priorities sparingly and consistently. For ordinary focus announcements, the defaults are usually sufficient.

Programmatic output is available through:

HosannaAppUtils.sayText(
  'Download complete',
  10,
  this,
  false,
);

The manager also exposes clearQueue(), flush(), and silenceBackground(duration). pause() and resume() are implemented for web and are no-ops with warnings on platforms that do not support them.

Samsung Voice Guide and LG Audio Guidance​

The application path remains the same on TVs:

BaseView.audioGuideItem → FocusManager → TextToSpeechManager → roAudioGuide

Tizen and webOS own a retained focusable ARIA proxy, so platform behavior is not scattered through views. Tizen observes the TV Info Voice Guide setting; webOS declares accessibility.supportsAudioGuidance and observes the Settings service audioGuidance value. Enabling guidance after launch must update IsAudioGuideEnabled, emit the existing device-info change event, recreate and refocus the proxy, and continue queued announcements.

These adapters provide the production TV audio-guide path. For each application release, run audible checks for enable-before-launch, enable-after-launch, focus movement, setting changes, and queue timing on representative target models.

Neither television API provides a reliable arbitrary-utterance completion callback equivalent to browser speech synthesis. Hosanna uses a bounded timing estimate only to keep the queue from deadlocking. Treat announcement completion timing as a documented vendor limitation and validate it audibly on hardware.

Test the experience​

  • Traverse every interactive path with only directional, OK, and Back input.
  • Confirm focus is visible and never becomes trapped or lost.
  • Listen for repeated, stale, missing, or overly long announcements.
  • Ensure button text plus hints describe the result, not just the gesture.
  • Check dynamic errors and completion messages with speech enabled.
  • Verify captions/subtitles and non-audio equivalents independently of the audio guide.
  • Test each supported expression and platform; native speech behavior can differ from browser synthesis.
  • Start each TV once with guidance already enabled and once with it enabled after launch. Verify capability changes, queue/flush/priority, suspend/resume, and repeated focus movement without clipped, overlapping, or deadlocked speech.
Talk to us