Skip to content
Speech SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Text-to-speech

On-device, voice-cloning text-to-speech for the browser. Runs Chatterbox on WebGPU in a Web Worker: no server, no API key, nothing leaves the device.

@kucukkanat/tts · source

  • One line to speak: await tts.speak("Hello!") — the model downloads on first use and is cached.
  • Clone any voice from a 5–15 s recording: a URL, a File, a microphone recording, raw PCM.
  • Streams while it generates: audio starts after ~0.6 s of speech is ready, with a jitter buffer so it never stutters.
  • Follow along: sentence events fire on the audio clock, for karaoke-style highlighting.
  • Typed everything: per-model options are checked at compile time; every failure is a SpeechError with a code.
bun add @kucukkanat/tts   # or npm i / pnpm add

Quick start

import { createTTS } from "@kucukkanat/tts";

const tts = createTTS();

// Call from a click handler the first time: browsers only allow audio after a user gesture.
document.querySelector("button")?.addEventListener("click", async () => {
  await tts.speak("Hello! This voice is generated entirely inside your browser.");
});

With no voice, the model’s reference speaker is used. The first call downloads the model (~725 MB for Turbo) and caches it in the browser; later page loads start in seconds, offline.

Clone a voice

voice accepts anything that holds a recording of the speaker:

import { createTTS } from "@kucukkanat/tts";

const tts = createTTS();
const fileInput = document.querySelector<HTMLInputElement>("input[type=file]");

// A URL (same-origin or CORS-enabled)…
await tts.speak("Nice to meet you.", { voice: "/voices/me.wav" });

// …a File or Blob (wav, mp3, ogg, webm, m4a…)…
const file = fileInput?.files?.[0];
if (file) await tts.speak("This is my own voice.", { voice: file });

// …or raw mono PCM.
const pcm = new Float32Array(24_000 * 6); // 6 s of audio you captured yourself
await tts.speak("From raw samples.", { voice: { pcm, sampleRate: 24_000 } });

Record a voice from the microphone

Record the speaker with startRecording() from @kucukkanat/speech-audio (installed with this package), then pass the recording as the voice:

import { startRecording } from "@kucukkanat/speech-audio";
import { createTTS } from "@kucukkanat/tts";

const tts = createTTS();
let voice: Blob | null = null;

// Start from a click: the browser asks for microphone permission the first time.
document.querySelector("#record")?.addEventListener("click", async () => {
  const recording = await startRecording({ maxSeconds: 15 }); // stops by itself after 15 s
  recording.on("time", (seconds) => console.log(`recording… ${seconds.toFixed(0)} s`));
  document.querySelector("#stop")?.addEventListener("click", () => recording.stop(), { once: true });
  voice = await recording.done; // the recorded clip (webm/opus, mp4 or ogg, depending on the browser)
});

// Then speak anything in the recorded voice.
document.querySelector("#speak")?.addEventListener("click", async () => {
  if (voice) await tts.speak("This is a clone of the voice you just recorded.", { voice });
});

Aim for 5–10 seconds of one person reading naturally in a quiet room: the model copies the voice and the recording’s character (echo, microphone tone). The recording is used as-is; to crop it to its best stretch automatically and keep it across reloads, save it with voices.create({ name, audio: voice, meta: {} }) from @kucukkanat/voices and speak with the saved record.

Try it: record yourself, then press speak.

Learning a voice (“encoding”) takes about a second the first time and is cached, so later calls with the same voice start immediately. To keep voices across reloads, pass a persistent cache — or use @kucukkanat/voices, a ready-made voice library:

import { createTTS } from "@kucukkanat/tts";
import { createVoiceStore } from "@kucukkanat/voices";

const voices = createVoiceStore();
const tts = createTTS({ cache: voices.conditioningCache });

const [aria] = await voices.list(); // bundled demo voices, plus the ones you create
if (aria) await tts.speak("Hi, I'm Aria.", { voice: aria });

Follow along while it speaks

speak() returns a Speech: await it, listen to it, or stop it.

import { createTTS } from "@kucukkanat/tts";

const tts = createTTS();
const speech = tts.speak("First sentence. Second sentence. Third one.");

speech.on("state", (state) => console.log(state)); // loading → encoding → generating → buffering → playing → ended
speech.on("sentence", ({ index, count, text }) => console.log(`${index + 1}/${count}: ${text}`)); // when it becomes audible
speech.on("stats", ({ ttfaMs, audioSeconds }) => console.log(ttfaMs, audioSeconds));

document.querySelector("#stop")?.addEventListener("click", () => speech.stop());

const { clip, stats, stopped } = await speech;
console.log(`${clip.duration.toFixed(1)} s, first audio after ${stats.ttfaMs?.toFixed(0)} ms`, stopped ? "(stopped)" : "");
  • speech.analyser is a live AnalyserNode for waveforms and level meters.
  • stop() resolves the speech with stopped: true (and the audio generated so far) — it is not an error.
  • Pass { signal } to cancel with an AbortSignal; the speech then rejects with the signal’s reason.
  • Returning a Speech from an async function awaits it (it’s thenable). Return { speech } if you need the handle.

Save, replay, or post-process

import { createTTS } from "@kucukkanat/tts";

const tts = createTTS();

// The whole text as one clip (no playback).
const clip = await tts.synthesize("Saved for later.");
const url = URL.createObjectURL(clip.toWav()); // 16-bit mono WAV
document.querySelector<HTMLAudioElement>("audio")?.setAttribute("src", url);

// Replay with the same events as speak(): clip.play()
await clip.play();

// Or stream raw PCM blocks as they're generated, e.g. into your own audio graph.
for await (const chunk of tts.stream("Streaming sentence one. And two.")) {
  console.log(chunk.sentence.index, chunk.pcm.length, chunk.sampleRate, chunk.final);
  // `break` here cancels the rest of the generation.
}

Models

Both run on WebGPU in browsers (their quantized graphs use an operator ONNX Runtime’s WASM backend lacks; without WebGPU, load() rejects with webgpu-required). Under Node or Bun they run on the CPU.

Model Size Speed Extras
"chatterbox-turbo" (default) ~725 MB ~2× faster than real time; streams within a sentence [laugh], [sigh]… tags
"chatterbox" ~1.5 GB slower than real time; buffers before playing exaggeration (emotion)

Options only some models accept are typed per model:

import { createTTS } from "@kucukkanat/tts";

const expressive = createTTS({ model: "chatterbox" });
await expressive.speak("This is so exciting!", { exaggeration: 1.2 }); // 0.25 flat … 2 dramatic, 0.5 neutral

const turbo = createTTS(); // Turbo: exaggeration would be a compile error here
await turbo.speak("That's hilarious [laugh] okay.");

When the model is picked at runtime (a settings screen), use the full union and check tts.model.supports:

import { createTTS, type TtsModelKey } from "@kucukkanat/tts";

const tts = createTTS<TtsModelKey>();
await tts.switchModel("chatterbox"); // releases the previous model's GPU memory
const intensity = 0.8;
await tts.speak("Hello.", tts.model.supports.exaggeration ? { exaggeration: intensity } : {});

Tune the delivery

Speech is sampled token by token. Each model ships with the reference implementation’s settings (tts.model.sampling); override any of them per call:

import { createTTS, SAMPLING_RANGES } from "@kucukkanat/tts";

const tts = createTTS();
console.log(tts.model.sampling); // { temperature: 0.8, topK: 1000, topP: 0.95, minP: 0, repetitionPenalty: 1.2 }

// Steadier and more predictable, e.g. for narration:
await tts.speak("Chapter one. The storm had passed.", { sampling: { temperature: 0.5, repetitionPenalty: 1.4 } });

// Livelier, with more variation between takes:
await tts.speak("Wait, you did what?", { sampling: { temperature: 1.1, topP: 1 } });

console.log(SAMPLING_RANGES.temperature); // { min: 0.05, max: 2 }
Option Effect Range
temperature Randomness: lower is steadier and flatter, higher is livelier but may slur or ramble 0.05–2
topK Only the k most likely tokens (0 = no limit) 0–8192, whole
topP Only the most likely tokens that together reach this probability (1 = off) 0.05–1
minP Drop tokens less than minP × as likely as the best one (0 = off) 0–1
repetitionPenalty Above 1, discourages repeated sounds: fewer stutters and loops (1 = off) 1–3

Out-of-range values reject with unsupported-option before anything runs. sampling works with speak(), stream() and synthesize(), on every model.

Loading and status

Every method loads the model on first use. To show progress up front, load explicitly and subscribe to status (a stable snapshot, so it plugs straight into React’s useSyncExternalStore — or use @kucukkanat/speech-react):

import { createTTS } from "@kucukkanat/tts";

const tts = createTTS();
tts.subscribe((status) => {
  if (status.state === "loading") console.log(`${Math.round(status.progress.progress * 100)}% ${status.progress.label}`);
  if (status.state === "ready") console.log(`ready on ${status.device}`);
  if (status.state === "error") console.error(status.error.code, status.error.message);
});
await tts.load();
await tts.prepare("/voices/me.wav"); // optional: learn a voice ahead of time

Errors

Every failure is a SpeechError with a stable code and a message you can show to users:

import { createTTS, isSpeechError } from "@kucukkanat/tts";

const tts = createTTS();
try {
  await tts.speak("Hello.", { voice: "/missing.wav" });
} catch (e) {
  if (isSpeechError(e, "autoplay-blocked")) console.warn("Call speak() from a click or key press.");
  else if (isSpeechError(e, "decode-failed")) console.warn(e.message); // e.g. "/missing.wav returned an HTML page…"
  else throw e;
}

Codes you may see: webgpu-required, empty-text, invalid-voice, decode-failed, unsupported-option, autoplay-blocked, generation-failed, model-download-failed, model-init-failed, worker-crashed, disposed.

Bundlers

The model runs in a Web Worker shipped with this package and created with new Worker(new URL("./tts.worker.js", import.meta.url), { type: "module" }). webpack 5, Next.js and Rspack bundle it automatically; Vite, esbuild and Bun take one plugin from @kucukkanat/speech-core:

Vite: keeps the worker out of dependency pre-bundling (and can serve the dev server cross-origin isolated):

// vite.config.ts
import { speechSdk } from "@kucukkanat/speech-core/vite";
import { defineConfig } from "vite";

export default defineConfig({ plugins: [speechSdk({ isolation: true })] });

esbuild and Bun: bundles the worker (with transformers.js) and the demo voices as files next to your bundle:

// build.ts
import { speechSdk } from "@kucukkanat/speech-core/esbuild";
import * as esbuild from "esbuild";

await esbuild.build({ entryPoints: ["src/main.ts"], bundle: true, format: "esm", outdir: "dist", plugins: [speechSdk()] });
// build.ts (run with `bun build.ts`)
import { speechSdk } from "@kucukkanat/speech-core/bun";

await Bun.build({ entrypoints: ["src/main.ts"], outdir: "dist", target: "browser", plugins: [speechSdk()] });

Anything else: bundle the worker entry (@kucukkanat/tts/worker) with your bundler’s worker syntax and pass a factory. With Vite’s ?worker import, for example:

import TtsWorker from "@kucukkanat/tts/worker?worker";
const tts = createTTS({ worker: () => new TtsWorker() });

Step-by-step setups, including webpack and Next.js, are in the bundler guide.

Next.js: use it from client components only ("use client"); it needs browser APIs.

Hosting

  • WebGPU is required in browsers (recent Chrome/Edge, Safari 26+). Check up front with detectCapabilities() from @kucukkanat/speech-core, or handle the webgpu-required error.
  • Cross-origin isolation is optional but makes the WASM fallback multi-threaded. Serve pages with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: credentialless (not require-corp, which would block model downloads from Hugging Face).
  • Self-hosting / strict CSP / offline: models come from Hugging Face and ONNX Runtime’s WASM files from jsDelivr by default. Point them elsewhere with createTTS({ transformers: { remoteHost, wasmPaths } }).

Was this page helpful?