Handling errors
Every SDK failure is a SpeechError with a stable code and a message you can show to users.
Errors are part of the API: each one is a SpeechError whose code you can branch on and whose message is written
for end users. Cancelling is not an error you need to special-case beyond isAbortError.
import { isAbortError, isSpeechError, SpeechError } from "@kucukkanat/speech-core";
function describe(e: unknown): string {
if (isAbortError(e)) return "Cancelled.";
if (isSpeechError(e, "mic-permission-denied")) return "Please allow the microphone.";
if (e instanceof SpeechError) return `${e.code}: ${e.message}`;
return "Something unexpected went wrong.";
}
console.log(describe(new SpeechError("busy", "One session at a time.")));
isSpeechError(e, code) narrows the type, so the code is autocompleted and typos are compile errors. The engine
packages re-export it, so import { isSpeechError } from "@kucukkanat/tts" works too.
Codes
| Area | Codes |
|---|---|
| Engines | worker-crashed, disposed, internal, unsupported-environment, insecure-context |
| Models | model-download-failed, model-init-failed, model-not-loaded, webgpu-required, unknown-model |
| Speech | empty-text, invalid-voice, unsupported-option, generation-failed, autoplay-blocked |
| Transcription | busy, decode-failed |
| Microphone | mic-permission-denied, mic-not-found, mic-busy, mic-unsupported, mic-insecure-context, mic-unknown |
| Voice library | voice-not-found, built-in-read-only, db-blocked, quota-exceeded |
Where errors show up
- Promises (
speak(),transcribe(),load(),voices.create(), …) reject with the error. - Engine status: a failed load also moves
statusto{ state: "error", error }, so a status-driven UI (oruseEngine) shows it without atry. - React hooks keep the last failure in
error(useSpeak,useTranscription,useVoices). - Stopping is not failing:
speech.stop()resolves withstopped: true;session.stop()resolves the final transcript. Only anAbortSignalrejects, with the signal’s reason.
Common cases
| Code | Why | What to do |
|---|---|---|
webgpu-required |
Chatterbox and Voxtral need WebGPU in browsers | Check detectCapabilities() first; offer Moonshine for speech-to-text |
autoplay-blocked |
Audio started without a user gesture | Call speak() from a click or key press the first time |
mic-permission-denied |
The user or browser blocked the microphone | Show e.message; it explains how to re-enable it |
busy |
A second transcription on the same engine | Stop the running session, or create another engine |
db-blocked |
Another tab holds an older voice database open | Ask the user to close other tabs; snapshot.error clears afterwards |