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

Core

Shared foundations of the @kucukkanat speech SDKs. As an app developer you'll mostly use three things from here: the bundler plugins (Vite, esbuild, Bun), typed errors, and capability detection. The rest (typed worker RPC, engine lifecycle) is for building engines of your own.

@kucukkanat/speech-core · source

bun add @kucukkanat/speech-core

Vite plugin

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

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

It keeps @kucukkanat/tts, @kucukkanat/stt, @kucukkanat/speech-audio and transformers.js out of dependency pre-bundling (so their Web Workers stay detectable), emits ES-module workers, and — with isolation: true — serves dev and preview cross-origin isolated (COOP: same-origin, COEP: credentialless), which enables multi-threaded WASM.

esbuild and Bun plugin

esbuild and Bun.build share a plugin API, so one plugin serves both (import it from /esbuild or /bun):

// 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", // the engines use import.meta.url
  outdir: "dist",
  plugins: [speechSdk()],
});
// build.ts (run with `bun build.ts`)
import { speechSdk } from "@kucukkanat/speech-core/bun";

const result = await Bun.build({ entrypoints: ["src/main.ts"], outdir: "dist", target: "browser", plugins: [speechSdk()] });
if (!result.success) throw new AggregateError(result.logs, "Build failed");

Neither bundler follows new Worker(new URL("./x.worker.js", import.meta.url)) inside dependencies, so without the plugin the engines’ workers and the demo voices would 404. The plugin bundles each worker (with transformers.js) into its own file and emits the demo voices, next to your bundle with hashed names. Serve the output directory as static files; ONNX Runtime’s WebAssembly still loads from jsDelivr unless you set transformers.wasmPaths.

Errors

Every SDK failure is a SpeechError with a stable code and a user-presentable message:

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.")));
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

Capabilities

import { detectCapabilities } from "@kucukkanat/speech-core";

const caps = await detectCapabilities(); // never throws; everything is false during SSR
if (!caps.webgpu) console.warn("No WebGPU: models will run on the CPU and be much slower.");
if (!caps.secureContext) console.warn("The microphone needs HTTPS or localhost.");
console.log(caps); // { webgpu, shaderF16, secureContext, crossOriginIsolated, microphone }

Building your own engine

createRpcClient / exposeRpc give you typed request/response calls to a Web Worker with streamed events, transferable buffers, AbortSignal cancellation (the worker gets its own signal), typed error round-trips and crash recovery. createEngineCore adds the model lifecycle (status store, deduplicated loading with progress, switching).

// protocol.ts — shared by both sides
export interface EchoProtocol {
  shout: { arg: string; result: string; event: number }; // arg → result, streaming `event`s meanwhile
}

// echo.worker.ts
import { exposeRpc } from "@kucukkanat/speech-core";
exposeRpc<EchoProtocol>({
  shout: async (text, { emit, signal }) => {
    for (let i = 3; i > 0 && !signal.aborted; i--) emit(i);
    return text.toUpperCase();
  },
});

// main thread — keep `new Worker(new URL(...))` literal so bundlers find the worker
import { createRpcClient } from "@kucukkanat/speech-core";
const rpc = createRpcClient<EchoProtocol>(() => new Worker(new URL("./echo.worker.js", import.meta.url), { type: "module" }));
const loud = await rpc.call("shout", "hello", { onEvent: (n) => console.log(n) }); // 3, 2, 1, then "HELLO"

Was this page helpful?