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.

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.
Talk to us