@speak-tts/core

Framework-agnostic text-to-speech controller powered by the Web Speech API. Use it from plain JavaScript or as the foundation for the React (@speak-tts/react) and Angular (@speak-tts/angular) adapters.

Live demo & docs: https://speak-tts.vercel.app/ — try the interactive demo or read the vanilla JS guide.

Install

npm install @speak-tts/core

Usage

import { createSpeech } from "@speak-tts/core";

const speech = createSpeech({
  text: "Hello from vanilla JavaScript!",
  rate: 1.05,
});

speech.on("statuschange", (status) => console.log("status:", status));
speech.on("activeword", (offset) => console.log("active char:", offset));
speech.on("end", () => console.log("done"));

speech.start();

Tear down

speech.destroy(); // cancels speech and removes all listeners

Update mid-speech

speech.setOptions({ rate: 1.5, voiceURI: "Google UK English Female" });
speech.setText("New text replaces the queue.");

API

const speech = createSpeech(options: SpeechOptions): SpeechController;

interface SpeechController {
  start(): void;
  pause(): void;
  resume(): void;
  stop(): void;
  destroy(): void;

  getStatus(): "started" | "paused" | "stopped" | "queued";
  getActiveOffset(): number;
  getText(): string;

  setText(text: string): void;
  setOptions(opts: Partial<SpeechOptions>): void;

  on<K extends SpeechEventName>(event: K, listener: ...): () => void;
  off<K extends SpeechEventName>(event: K, listener: ...): void;
}

Events: start, pause, resume, stop, end, boundary, error, statuschange, activeword.

Bonus utilities

• chunkText(text, max) — sentence/word-aware splitter for long text
• tokenizeWords(text) — returns offset-aware word tokens
• loadVoices() — async voice loader (handles Chrome's voiceschanged race)
• BCP47_LANGUAGES — curated list of 67 language tags
• recordSpeech(options) — captures synthesized audio as a Blob
• downloadBlob(blob, fileName) — triggers a browser download

Browser support

Requires the Web Speech API, available in all modern browsers (Chrome, Edge, Safari, Firefox 49+ with the flag, all Chromium-based mobile browsers). Audio download additionally requires getDisplayMedia and MediaRecorder (Chromium-based browsers, served over HTTPS or localhost).

@speak-tts/core is SSR-safe — every window access is guarded, so it can be imported in Next.js, Remix, SvelteKit, Angular Universal, etc., without throwing.

Related packages

• @speak-tts/react — React hook + component on top of this core.
• @speak-tts/angular — Angular standalone component + signal-based service on top of this core.

License

MIT