@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/src/services/voice/kokoro/__tests__/kokoro-engine-discovery.test.ts

@@ -0,0 +1,277 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveStateDir } from "@elizaos/core";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+	isKokoroGgufFile,
+	kokoroEngineModelDir,
+	resolveKokoroEngineConfig,
+} from "../kokoro-engine-discovery";
+import {
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_FALLBACK_VOICE_ID,
+} from "../voice-presets";
+
+function makeStaged(opts: { modelFile?: string; voices?: string[] }): {
+	root: string;
+	cleanup: () => void;
+} {
+	const root = mkdtempSync(path.join(os.tmpdir(), "kokoro-engine-test-"));
+	if (opts.modelFile) {
+		writeFileSync(path.join(root, opts.modelFile), Buffer.alloc(4));
+	}
+	if (opts.voices && opts.voices.length > 0) {
+		mkdirSync(path.join(root, "voices"), { recursive: true });
+		for (const v of opts.voices) {
+			writeFileSync(path.join(root, "voices", v), Buffer.alloc(1024));
+		}
+	}
+	return {
+		root,
+		cleanup: () => rmSync(root, { recursive: true, force: true }),
+	};
+}
+
+describe("resolveKokoroEngineConfig", () => {
+	let cleanups: Array<() => void>;
+	let origEnv: Record<string, string | undefined>;
+	beforeEach(() => {
+		cleanups = [];
+		origEnv = {
+			ELIZA_KOKORO_MODEL_DIR: process.env.ELIZA_KOKORO_MODEL_DIR,
+			ELIZA_KOKORO_MODEL_FILE: process.env.ELIZA_KOKORO_MODEL_FILE,
+			ELIZA_KOKORO_DEFAULT_VOICE_ID: process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID,
+		};
+		delete process.env.ELIZA_KOKORO_MODEL_DIR;
+		delete process.env.ELIZA_KOKORO_MODEL_FILE;
+		delete process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID;
+	});
+	afterEach(() => {
+		for (const c of cleanups) c();
+		for (const [k, v] of Object.entries(origEnv)) {
+			if (v === undefined) delete process.env[k];
+			else process.env[k] = v;
+		}
+	});
+
+	it("returns null when the model dir does not exist", () => {
+		process.env.ELIZA_KOKORO_MODEL_DIR = path.join(
+			os.tmpdir(),
+			`definitely-not-here-${Date.now()}`,
+		);
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("returns null when the model dir exists but no GGUF is staged", () => {
+		const fx = makeStaged({ voices: ["af_bella.bin"] });
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("returns null when no voice .bin is staged", () => {
+		const fx = makeStaged({ modelFile: "kokoro-82m-v1_0.gguf" });
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("returns the canonical Samantha default when staged", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_same.bin", "af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.defaultVoiceId).toBe(KOKORO_DEFAULT_VOICE_ID);
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0.gguf");
+		expect(cfg?.layout.sampleRate).toBe(24_000);
+		expect(cfg?.layout.root).toBe(fx.root);
+		expect(cfg?.layout.voicesDir).toBe(path.join(fx.root, "voices"));
+	});
+
+	it("falls back to af_bella with a console warning when Samantha preset is missing", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin"], // Samantha (af_same) absent
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+
+		const warnings: string[] = [];
+		const origWarn = console.warn;
+		console.warn = (msg: unknown) => {
+			warnings.push(String(msg));
+		};
+		try {
+			const cfg = resolveKokoroEngineConfig();
+			expect(cfg).not.toBeNull();
+			expect(cfg?.defaultVoiceId).toBe(KOKORO_FALLBACK_VOICE_ID);
+			expect(warnings).toHaveLength(1);
+			expect(warnings[0]).toContain(
+				`default voice ${KOKORO_DEFAULT_VOICE_ID} preset not staged`,
+			);
+			expect(warnings[0]).toContain(
+				`falling back to ${KOKORO_FALLBACK_VOICE_ID}`,
+			);
+		} finally {
+			console.warn = origWarn;
+		}
+	});
+
+	it("can probe an explicit bundle-local Kokoro root before the global install root", () => {
+		const bundleFx = makeStaged({
+			modelFile: "kokoro-82m-v1_0-Q4_K_M.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(bundleFx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = path.join(
+			os.tmpdir(),
+			`not-used-${Date.now()}`,
+		);
+
+		const cfg = resolveKokoroEngineConfig(bundleFx.root);
+		expect(cfg).not.toBeNull();
+		expect(cfg?.layout.root).toBe(bundleFx.root);
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0-Q4_K_M.gguf");
+		expect(cfg?.defaultVoiceId).toBe("af_bella");
+		expect(kokoroEngineModelDir(bundleFx.root)).toBe(bundleFx.root);
+	});
+
+	it("picks any staged voice when the catalog default is missing", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_sarah.bin"], // not the default `af_bella`
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.defaultVoiceId).toBe("af_sarah");
+	});
+
+	it("honours ELIZA_KOKORO_DEFAULT_VOICE_ID when set + staged", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin", "af_nicole.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID = "af_nicole";
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.defaultVoiceId).toBe("af_nicole");
+	});
+
+	it("returns null when ELIZA_KOKORO_DEFAULT_VOICE_ID is set but the .bin is missing", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID = "af_nicole";
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("honours ELIZA_KOKORO_MODEL_FILE override when present", () => {
+		const fx = makeStaged({
+			modelFile: "custom-export.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		process.env.ELIZA_KOKORO_MODEL_FILE = "custom-export.gguf";
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.layout.modelFile).toBe("custom-export.gguf");
+	});
+
+	it("reports runtimeKind=gguf for GGUF model files", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.runtimeKind).toBe("gguf");
+	});
+
+	it("reports runtimeKind=gguf for Q4_K_M GGUF model files", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0-Q4_K_M.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.runtimeKind).toBe("gguf");
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0-Q4_K_M.gguf");
+	});
+
+	it("prefers the Q4_K_M GGUF over the unquantized GGUF when both are staged", () => {
+		const root = mkdtempSync(path.join(os.tmpdir(), "kokoro-engine-test-"));
+		writeFileSync(path.join(root, "kokoro-82m-v1_0.gguf"), Buffer.alloc(4));
+		writeFileSync(
+			path.join(root, "kokoro-82m-v1_0-Q4_K_M.gguf"),
+			Buffer.alloc(4),
+		);
+		mkdirSync(path.join(root, "voices"), { recursive: true });
+		writeFileSync(
+			path.join(root, "voices", "af_bella.bin"),
+			Buffer.alloc(1024),
+		);
+		cleanups.push(() => rmSync(root, { recursive: true, force: true }));
+
+		process.env.ELIZA_KOKORO_MODEL_DIR = root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.runtimeKind).toBe("gguf");
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0-Q4_K_M.gguf");
+	});
+});
+
+describe("isKokoroGgufFile", () => {
+	it("identifies GGUF model files by extension", () => {
+		expect(isKokoroGgufFile("kokoro-82m-v1_0.gguf")).toBe(true);
+		expect(isKokoroGgufFile("kokoro-82m-v1_0-Q4_K_M.gguf")).toBe(true);
+		expect(isKokoroGgufFile("KOKORO.GGUF")).toBe(true);
+	});
+
+	it("identifies non-GGUF model files as not GGUF", () => {
+		expect(isKokoroGgufFile("kokoro-v1.0.pt")).toBe(false);
+		expect(isKokoroGgufFile("model.bin")).toBe(false);
+		expect(isKokoroGgufFile("model.safetensors")).toBe(false);
+		expect(isKokoroGgufFile("model.pth")).toBe(false);
+	});
+});
+
+describe("kokoroEngineModelDir", () => {
+	let origDir: string | undefined;
+	beforeEach(() => {
+		origDir = process.env.ELIZA_KOKORO_MODEL_DIR;
+	});
+	afterEach(() => {
+		if (origDir === undefined) delete process.env.ELIZA_KOKORO_MODEL_DIR;
+		else process.env.ELIZA_KOKORO_MODEL_DIR = origDir;
+	});
+
+	it("returns the env override when set", () => {
+		process.env.ELIZA_KOKORO_MODEL_DIR = "/tmp/custom-kokoro";
+		expect(kokoroEngineModelDir()).toBe("/tmp/custom-kokoro");
+	});
+
+	it("returns the canonical home path when env is unset", () => {
+		delete process.env.ELIZA_KOKORO_MODEL_DIR;
+		expect(kokoroEngineModelDir()).toBe(
+			path.join(resolveStateDir(), "local-inference", "models", "kokoro"),
+		);
+	});
+});

package/src/services/voice/kokoro/__tests__/kokoro-ffi-runtime.test.ts

@@ -0,0 +1,235 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type {
+	ElizaInferenceContextHandle,
+	ElizaInferenceFfi,
+} from "../ffi-bindings";
+import { KokoroFfiRuntime } from "../kokoro-ffi-runtime";
+import type { KokoroRuntimeInputs } from "../kokoro-runtime";
+import type { KokoroModelLayout, KokoroVoicePack } from "../types";
+
+const MODEL_FILE = "kokoro-82m-v1_0.gguf";
+
+interface FakeFfiCalls {
+	loads: Array<{ ggufPath: string; voiceBinPath: string; styleDim?: number }>;
+	synths: Array<{ text: string; maxSamples: number; speed?: number }>;
+	destroyed: number;
+	closed: number;
+}
+
+function fakeKokoroFfi(opts: {
+	supported?: boolean;
+	pcm?: Float32Array;
+	calls: FakeFfiCalls;
+}): ElizaInferenceFfi {
+	const pcm = opts.pcm ?? Float32Array.from([0.1, 0.2, 0.3, 0.4]);
+	return {
+		libraryPath: "/fake/libelizainference.so",
+		libraryAbiVersion: "10",
+		create: () => 7n as ElizaInferenceContextHandle,
+		destroy: () => {
+			opts.calls.destroyed++;
+		},
+		kokoroSupported: () => opts.supported ?? true,
+		kokoroLoad: (a) => {
+			opts.calls.loads.push(a);
+		},
+		kokoroSynthesize: (a) => {
+			opts.calls.synths.push({
+				text: a.text,
+				maxSamples: a.maxSamples,
+				speed: a.speed,
+			});
+			return pcm.slice();
+		},
+		kokoroSampleRate: () => 24_000,
+		close: () => {
+			opts.calls.closed++;
+		},
+	} as unknown as ElizaInferenceFfi;
+}
+
+function makeLayout(root: string): KokoroModelLayout {
+	return {
+		root,
+		modelFile: MODEL_FILE,
+		voicesDir: path.join(root, "voices"),
+		sampleRate: 24_000,
+	};
+}
+
+function voice(id: string, file: string): KokoroVoicePack {
+	return { id, displayName: id, lang: "a", file, dim: 256 };
+}
+
+function makeInputs(
+	v: KokoroVoicePack,
+	onChunk: KokoroRuntimeInputs["onChunk"],
+	cancelSignal = { cancelled: false },
+): KokoroRuntimeInputs {
+	return {
+		phonemes: { ids: Int32Array.from([1, 2, 3]), phonemes: "hɛˈloʊ" },
+		voice: v,
+		cancelSignal,
+		onChunk,
+	};
+}
+
+describe("KokoroFfiRuntime", () => {
+	let root: string;
+	let calls: FakeFfiCalls;
+
+	beforeEach(() => {
+		root = mkdtempSync(path.join(os.tmpdir(), "kokoro-ffi-test-"));
+		mkdirSync(path.join(root, "voices"), { recursive: true });
+		writeFileSync(path.join(root, MODEL_FILE), Buffer.alloc(8));
+		writeFileSync(path.join(root, "voices", "af_same.bin"), Buffer.alloc(1024));
+		writeFileSync(
+			path.join(root, "voices", "af_bella.bin"),
+			Buffer.alloc(1024),
+		);
+		calls = { loads: [], synths: [], destroyed: 0, closed: 0 };
+	});
+
+	afterEach(() => {
+		rmSync(root, { recursive: true, force: true });
+		vi.restoreAllMocks();
+	});
+
+	it("throws when the loaded build does not link the Kokoro engine (no TCP fallback)", () => {
+		const ffi = fakeKokoroFfi({ supported: false, calls });
+		expect(
+			() =>
+				new KokoroFfiRuntime({
+					layout: makeLayout(root),
+					ffi,
+					ctx: 7n as ElizaInferenceContextHandle,
+				}),
+		).toThrow(/does not link the in-process Eliza-1 Kokoro engine/);
+	});
+
+	it("loads the GGUF + voice once and emits one body chunk + final tail", async () => {
+		const ffi = fakeKokoroFfi({ calls });
+		const rt = new KokoroFfiRuntime({
+			layout: makeLayout(root),
+			ffi,
+			ctx: 7n as ElizaInferenceContextHandle,
+		});
+
+		const chunks: Array<{ isFinal: boolean; len: number }> = [];
+		const result = await rt.synthesize(
+			makeInputs(voice("af_same", "af_same.bin"), (c) => {
+				chunks.push({ isFinal: c.isFinal, len: c.pcm.length });
+				return undefined;
+			}),
+		);
+
+		expect(result.cancelled).toBe(false);
+		expect(calls.loads).toHaveLength(1);
+		expect(calls.loads[0]?.ggufPath).toBe(path.join(root, MODEL_FILE));
+		expect(calls.loads[0]?.voiceBinPath).toBe(
+			path.join(root, "voices", "af_same.bin"),
+		);
+		// The fork phonemizes internally — we hand it the phoneme string, the
+		// same `input` the llama-server /v1/audio/speech path sends.
+		expect(calls.synths[0]?.text).toBe("hɛˈloʊ");
+		expect(chunks.filter((c) => !c.isFinal)).toHaveLength(1);
+		expect(chunks.at(-1)?.isFinal).toBe(true);
+		expect(chunks[0]?.len).toBe(4);
+	});
+
+	it("does not reload the voice across synthesize calls for the same voice", async () => {
+		const ffi = fakeKokoroFfi({ calls });
+		const rt = new KokoroFfiRuntime({
+			layout: makeLayout(root),
+			ffi,
+			ctx: 7n as ElizaInferenceContextHandle,
+		});
+
+		const v = voice("af_same", "af_same.bin");
+		await rt.synthesize(makeInputs(v, () => undefined));
+		await rt.synthesize(makeInputs(v, () => undefined));
+
+		expect(calls.loads).toHaveLength(1);
+		expect(calls.synths).toHaveLength(2);
+	});
+
+	it("reloads when the requested voice changes", async () => {
+		const ffi = fakeKokoroFfi({ calls });
+		const rt = new KokoroFfiRuntime({
+			layout: makeLayout(root),
+			ffi,
+			ctx: 7n as ElizaInferenceContextHandle,
+		});
+
+		await rt.synthesize(
+			makeInputs(voice("af_same", "af_same.bin"), () => undefined),
+		);
+		await rt.synthesize(
+			makeInputs(voice("af_bella", "af_bella.bin"), () => undefined),
+		);
+
+		expect(calls.loads).toHaveLength(2);
+		expect(calls.loads[1]?.voiceBinPath).toBe(
+			path.join(root, "voices", "af_bella.bin"),
+		);
+	});
+
+	it("honours a pre-set cancel signal without synthesizing", async () => {
+		const ffi = fakeKokoroFfi({ calls });
+		const rt = new KokoroFfiRuntime({
+			layout: makeLayout(root),
+			ffi,
+			ctx: 7n as ElizaInferenceContextHandle,
+		});
+
+		const chunks: boolean[] = [];
+		const result = await rt.synthesize(
+			makeInputs(
+				voice("af_same", "af_same.bin"),
+				(c) => {
+					chunks.push(c.isFinal);
+					return undefined;
+				},
+				{ cancelled: true },
+			),
+		);
+
+		expect(result.cancelled).toBe(true);
+		// Only the final tail is emitted; no synthesis happened.
+		expect(calls.synths).toHaveLength(0);
+		expect(chunks).toEqual([true]);
+	});
+
+	it("throws when the model file is missing on disk", async () => {
+		rmSync(path.join(root, MODEL_FILE), { force: true });
+		const ffi = fakeKokoroFfi({ calls });
+		const rt = new KokoroFfiRuntime({
+			layout: makeLayout(root),
+			ffi,
+			ctx: 7n as ElizaInferenceContextHandle,
+		});
+
+		await expect(
+			rt.synthesize(
+				makeInputs(voice("af_same", "af_same.bin"), () => undefined),
+			),
+		).rejects.toThrow(/Kokoro model file not found/);
+	});
+
+	it("destroys the ctx and closes the lib only when it owns them", () => {
+		const ffi = fakeKokoroFfi({ calls });
+		const rt = new KokoroFfiRuntime({
+			layout: makeLayout(root),
+			ffi,
+			ctx: 7n as ElizaInferenceContextHandle,
+		});
+		rt.dispose();
+		// ctx + ffi were injected → not owned → not torn down.
+		expect(calls.destroyed).toBe(0);
+		expect(calls.closed).toBe(0);
+	});
+});

package/src/services/voice/kokoro/__tests__/kokoro-runtime.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { KokoroMockRuntime } from "../kokoro-runtime";
+import type { KokoroVoicePack } from "../types";
+
+const OLD_ENV = { ...process.env };
+
+afterEach(() => {
+	process.env = { ...OLD_ENV };
+});
+
+function makeVoice(): KokoroVoicePack {
+	return {
+		id: "af_test",
+		displayName: "Test",
+		lang: "a",
+		file: "af_test.bin",
+		dim: 256,
+		tags: ["test"],
+	};
+}
+
+describe("KokoroMockRuntime", () => {
+	it("emits chunks and a final marker", async () => {
+		const runtime = new KokoroMockRuntime({
+			sampleRate: 24_000,
+			totalSamples: 100,
+			chunkCount: 4,
+		});
+		const chunks: Array<{ isFinal: boolean; len: number }> = [];
+		await runtime.synthesize({
+			phonemes: { ids: Int32Array.from([1, 2, 3]), phonemes: "abc" },
+			voice: makeVoice(),
+			cancelSignal: { cancelled: false },
+			onChunk: (c) => {
+				chunks.push({ isFinal: c.isFinal, len: c.pcm.length });
+				return undefined;
+			},
+		});
+		expect(chunks.at(-1)?.isFinal).toBe(true);
+		const bodyChunks = chunks.filter((c) => !c.isFinal);
+		expect(bodyChunks.length).toBeGreaterThan(0);
+		const total = bodyChunks.reduce((s, c) => s + c.len, 0);
+		expect(total).toBe(100);
+	});
+
+	it("increments calls counter", async () => {
+		const runtime = new KokoroMockRuntime({ sampleRate: 24_000 });
+		expect(runtime.calls).toBe(0);
+		await runtime.synthesize({
+			phonemes: { ids: Int32Array.from([1]), phonemes: "a" },
+			voice: makeVoice(),
+			cancelSignal: { cancelled: false },
+			onChunk: () => undefined,
+		});
+		expect(runtime.calls).toBe(1);
+	});
+
+	it("honours cancel signal", async () => {
+		const runtime = new KokoroMockRuntime({
+			sampleRate: 24_000,
+			totalSamples: 1000,
+			chunkCount: 10,
+		});
+		const signal = { cancelled: false };
+		let bodyCount = 0;
+		const result = await runtime.synthesize({
+			phonemes: { ids: Int32Array.from([1, 2]), phonemes: "ab" },
+			voice: makeVoice(),
+			cancelSignal: signal,
+			onChunk: (c) => {
+				if (!c.isFinal) {
+					bodyCount++;
+					if (bodyCount >= 2) {
+						signal.cancelled = true;
+					}
+				}
+				return undefined;
+			},
+		});
+		expect(result.cancelled).toBe(true);
+		expect(bodyCount).toBeLessThan(10);
+	});
+
+	it("returns cancelled=true when onChunk returns true", async () => {
+		const runtime = new KokoroMockRuntime({ sampleRate: 24_000 });
+		const result = await runtime.synthesize({
+			phonemes: { ids: Int32Array.from([1]), phonemes: "a" },
+			voice: makeVoice(),
+			cancelSignal: { cancelled: false },
+			onChunk: () => true,
+		});
+		expect(result.cancelled).toBe(true);
+	});
+});

package/src/services/voice/kokoro/__tests__/phonemizer.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	FallbackG2PPhonemizer,
+	KOKORO_PAD_ID,
+	kokoroLangToPhonemizerLanguage,
+	NpmPhonemizePhonemizer,
+} from "../phonemizer";
+
+describe("FallbackG2PPhonemizer", () => {
+	it("uses Kokoro tokenizer boundary ids and IPA for common smoke phrases", async () => {
+		const seq = await new FallbackG2PPhonemizer().phonemize(
+			"Hello there.",
+			"a",
+		);
+
+		expect(seq.phonemes).toBe("hɛloʊ ðɛɹ.");
+		expect(Array.from(seq.ids)).toEqual([
+			KOKORO_PAD_ID,
+			50,
+			86,
+			54,
+			57,
+			135,
+			16,
+			81,
+			86,
+			123,
+			4,
+			KOKORO_PAD_ID,
+		]);
+	});
+
+	it("maps Kokoro voice language ids to phonemizer locales", () => {
+		expect(kokoroLangToPhonemizerLanguage("a")).toBe("en-us");
+		expect(kokoroLangToPhonemizerLanguage("b")).toBe("en-gb");
+		expect(kokoroLangToPhonemizerLanguage("en-us")).toBe("en-us");
+	});
+
+	it("loads the bundled phonemizer package before falling back to pseudo phonemes", async () => {
+		const phonemizer = await NpmPhonemizePhonemizer.tryLoad();
+		expect(phonemizer?.id).toBe("phonemizer");
+		if (!phonemizer) {
+			throw new Error("phonemizer package did not load");
+		}
+
+		const seq = await phonemizer.phonemize("Hello there.", "a");
+
+		expect(seq.phonemes).not.toBe("hɛloʊ ðɛɹ.");
+		expect(seq.phonemes).toContain("h");
+		expect(Array.from(seq.ids)).toContain(156);
+	});
+});