---
title: "Core"
description: "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."
icon: cpu
---

`@kucukkanat/speech-core` · [source](https://github.com/kucukkanat/speech/tree/main/packages/speech-core)

```sh
bun add @kucukkanat/speech-core
```

## Vite plugin

```ts no-check
// 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`):

```ts
// 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()],
});
```

```ts
// 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`:

```ts
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

```ts
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).

```ts no-check
// 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"
```
