Speech-to-text
On-device, streaming speech-to-text for the browser. Runs Moonshine or Voxtral Realtime on WebGPU (or WASM) in a Web Worker: no server, no API key, nothing leaves the device.
@kucukkanat/stt · source
- Live microphone transcription in three lines, with words appearing as you speak.
- One verb for every input: a microphone, a file, a URL, raw PCM, or any async stream of audio frames.
- Committed vs partial text: render the stable part solid and the still-changing tail dimmed.
- Awaitable, iterable, cancellable sessions and typed errors (
mic-permission-denied,busy, …).
bun add @kucukkanat/stt # or npm i / pnpm add
Quick start: the microphone
import { createSTT } from "@kucukkanat/stt";
const stt = createSTT();
const output = document.querySelector("#transcript");
document.querySelector("#start")?.addEventListener("click", async () => {
const session = stt.listen(); // loads the model on first use, then opens the microphone
session.on("update", ({ committed, partial }) => {
if (output) output.textContent = `${committed} ${partial}`;
});
document.querySelector("#stop")?.addEventListener("click", () => session.stop(), { once: true });
const { text } = await session; // resolves after stop(), with the final text
console.log("Final:", text);
});
listen() returns immediately; await session.ready resolves once audio is flowing — the moment to show “listening”.
The model downloads on first use (~158 MB for Moonshine) and is cached by the browser.
Transcribe a file, URL or recording
import { createSTT } from "@kucukkanat/stt";
const stt = createSTT();
const file = document.querySelector<HTMLInputElement>("input[type=file]")?.files?.[0];
if (file) {
const { text } = await stt.transcribe(file); // wav, mp3, ogg, webm, m4a… (anything the browser decodes)
console.log(text);
}
const fromUrl = await stt.transcribe("/recordings/interview.mp3");
console.log(fromUrl.text);
Finite inputs are decoded, resampled to 16 kHz and processed faster than real time.
Updates as a stream
Sessions are async iterables of transcript updates:
import { createSTT } from "@kucukkanat/stt";
const stt = createSTT();
for await (const { text } of stt.transcribe("/recordings/meeting.wav")) {
console.log(text); // grows as each utterance is recognised
}
Your own audio source
Pass any async iterable of mono Float32Array frames (16 kHz unless it has a sampleRate property), for example a
WebRTC track you process yourself:
import { createSTT } from "@kucukkanat/stt";
async function* frames(): AsyncGenerator<Float32Array> {
// yield 80 ms blocks of 16 kHz PCM as they arrive (any block size works)
yield new Float32Array(1280);
}
const stt = createSTT();
const session = stt.transcribe(frames());
session.on("update", ({ text }) => console.log(text));
console.log((await session).text);
Use openMicrophone() from @kucukkanat/speech-audio if you want the microphone frames for
something else as well — a Microphone is exactly such a stream.
Models
| Model | Size | Runs on | Streaming |
|---|---|---|---|
"moonshine-base" (default) |
~158 MB | WebGPU or WASM | re-transcribes the current utterance live; commits at pauses |
"voxtral-realtime" |
~2.85 GB | WebGPU only | native: words appear ~0.5 s after they’re said; 13 languages |
import { createSTT } from "@kucukkanat/stt";
const stt = createSTT({ model: "voxtral-realtime" }); // throws `webgpu-required` on load without WebGPU
await stt.load({ onProgress: (p) => console.log(`${Math.round(p.progress * 100)}%`) });
stt.switchModel(key) swaps models at runtime (the previous one is released); stt.status / stt.subscribe work
exactly like in @kucukkanat/tts.
Stopping and cancelling
session.stop()stops reading input, waits for the last words, and resolves the final transcript.- If the model takes longer than
stopTimeoutMs(default 15 s), it resolves withcomplete: falseand the text so far. - An
AbortSignal({ signal }) cancels outright: the session rejects with the signal’s reason. - One session runs at a time per engine; a second one rejects with
busy.
Errors
import { createSTT, isSpeechError } from "@kucukkanat/stt";
const stt = createSTT();
try {
await stt.listen().ready;
} catch (e) {
if (isSpeechError(e, "mic-permission-denied")) console.warn(e.message); // user-facing explanation
else if (isSpeechError(e, "webgpu-required")) console.warn("Pick Moonshine on this device.");
else throw e;
}
Codes you may see: mic-permission-denied, mic-not-found, mic-busy, mic-unsupported, mic-insecure-context,
busy, decode-failed, webgpu-required, model-download-failed, worker-crashed, disposed.
Bundlers and hosting
Same as the bundler guide: webpack 5, Next.js and Rspack pick the worker up automatically; Vite, esbuild and Bun
take speechSdk() from @kucukkanat/speech-core/vite, /esbuild or /bun. @kucukkanat/stt/worker is exported for
custom setups. The microphone needs a secure context (HTTPS or localhost); cross-origin isolation is optional.