Pronouncing basketball names reliably in browser TTS

speechSynthesis.getVoices() may be empty during initial page load. Wait for voiceschanged, but keep the wait bounded.

TypeScript · voice loaderCopy
async function loadVoices(
  timeoutMs = 2_000
): Promise<SpeechSynthesisVoice[]> {
  const initial = speechSynthesis.getVoices();

  if (initial.length > 0) {
    return initial;
  }

  return new Promise(resolve => {
    let settled = false;

    const finish = () => {
      if (settled) return;
      settled = true;
      speechSynthesis.removeEventListener(
        "voiceschanged",
        onChange
      );
      resolve(speechSynthesis.getVoices());
    };

    const onChange = () => {
      if (speechSynthesis.getVoices().length > 0) {
        finish();
      }
    };

    speechSynthesis.addEventListener(
      "voiceschanged",
      onChange,
      { once: true }
    );

    window.setTimeout(finish, timeoutMs);
  });
}

Every call to speak() appends to a global queue. Choose whether new narration replaces, appends, or is ignored while speech is active.

TypeScript · replace policyCopy
async function speakLatest(
  text: string,
  voice?: SpeechSynthesisVoice
): Promise<void> {
  speechSynthesis.cancel();

  const utterance =
    new SpeechSynthesisUtterance(text);

  if (voice) {
    utterance.voice = voice;
    utterance.lang = voice.lang;
  }

  await new Promise<void>((resolve, reject) => {
    utterance.onend = () => resolve();

    utterance.onerror = event => {
      reject(
        new Error(
          `Speech synthesis failed: ${event.error}`
        )
      );
    };

    speechSynthesis.speak(utterance);
  });
}

The Web Speech API specification permits SSML documents, but browsers do not provide a dependable capability contract for phonemes or custom lexicons. Treat browser SSML as unavailable until the exact runtime is tested.

TypeScript · capability policyCopy
type TtsCapabilities = {
  engine:
    | "web-speech"
    | "cloud-ssml"
    | "native";
  verifiedSsml: boolean;
  verifiedPhonemes: boolean;
  verifiedLexicons: boolean;
};

const browserCapabilities: TtsCapabilities = {
  engine: "web-speech",
  verifiedSsml: false,
  verifiedPhonemes: false,
  verifiedLexicons: false
};

Pronunciation hints should not leak into visible content or accessibility labels. Explicit application narration can use a separate speech-only rendering.

TypeScript · three-channel contentCopy
type SpeechContent = {
  visualText: string;
  accessibleText: string;
  synthesizedText: string;
};

const example: SpeechContent = {
  visualText:
    "Nikola Jokić scored 32 points.",
  accessibleText:
    "Nikola Jokić scored 32 points.",
  synthesizedText:
    "Nee-koh-lah Yoh-kitch scored thirty-two points."
};