Minimal helper around the Web Speech API’s speechSynthesis voices. Provide hints like "French Woman" or "pt-BR Man" and let the helper pick the best available voice on the device with graceful fallbacks. Learn more about Questionwell at questionwell.org.

📢 Browser-only: this package no-ops during SSR and must be triggered from a user gesture in some browsers.

Installation

npm install @questionwell/browser-tts

Usage

import { TTS } from "@questionwell/browser-tts";

await TTS.speak("Bonjour tout le monde", "French Woman");

// Optional helpers
TTS.stop();
const isSpeaking = TTS.isSpeaking();
const voices = await TTS.getVoices();

// Extend metadata for edge-case voices
TTS.registerVoiceMetadata([
  { name: "Custom Voice", lang: "en-US", gender: "female", priority: 10 },
]);

API

TTS.speak(message, speakerHint, options?)

Speaks message using the best matching SpeechSynthesisVoice for speakerHint. Returns a Promise<void> that resolves when all utterances finish.

• message – Full text to speak (long strings are split into bite-size utterances).
• speakerHint – Natural language description such as "English Woman" or "pt-BR Man". Language keywords, gender hints, and a few regional aliases are supported out of the box.
• options – Optional SpeakOptions.

The method silently no-ops during SSR or when window.speechSynthesis is unavailable, so it is safe to call from shared code.

SpeakOptions

| Option | Type | Default | Description | | ------------ | ----------- | ------- | ----------- | | rate | number | 1.0 | Playback rate (0.1–10). | | pitch | number | 1.0 | Pitch adjustment (0–2). | | volume | number | 1.0 | Volume (0–1). | | onBoundary | (event) => void | – | Fired for each boundary event (word/char) emitted by the underlying utterance. | | onEnd | () => void | – | Called after the final utterance finishes. | | onError | (err) => void | – | Receives SpeechSynthesisErrorEvent or Error instances. |

TTS.stop()

Cancels any speech in progress and clears internal state. Safe to call even when nothing is speaking.

TTS.isSpeaking()

Returns true while the browser speech synthesizer is mid-utterance. Always returns false on the server.

TTS.getVoices()

Resolves with the cached SpeechSynthesisVoice[] after ensuring voices are loaded. Useful for building custom pickers or debugging voice availability.

TTS.registerVoiceMetadata(extraMetadata)

Accepts an array of metadata objects:

type VoiceMetadata = {
  name: string;
  lang?: string;
  gender?: "female" | "male" | "neutral";
  aliases?: string[];
  priority?: number;
};

Metadata entries extend the internal voice lookup table at runtime, making it easy to alias vendor-specific names or bump priorities for voices your product prefers. See inline docs in src/tts.ts for additional guidance.

License

Released under the GNU Affero General Public License v3.0. You must comply with the AGPL when distributing or hosting derivative works.