@glissade/narrate 0.8.0 → 0.8.1-pre.1

package/dist/index.d.ts

@@ -46,7 +46,7 @@ interface NarrationScript {
   leadIn?: number;
   /**
    * Word-timing aligner for providers that don't emit word timestamps
-   * (espeak / openai / piper). 'heuristic' (default) estimates from text;
+   * (espeak / openai / piper / kokoro). 'heuristic' (default) estimates from text;
    * 'vosk' derives real timings from the audio (offline ASR); 'none' leaves
    * segments word-less. Providers that supply their own words ignore this.
    */

package/dist/providers.d.ts

@@ -68,6 +68,14 @@ declare function piperProvider(opts?: {
   noiseScale?: number;
   noiseWScale?: number;
 }): TtsProvider;
+/** PCM16 mono WAV from float samples in [-1, 1]. Round-to-nearest → deterministic. */
+declare function floatToWav(samples: Float32Array, sampleRate: number): Buffer;
+type KokoroDtype = 'fp32' | 'fp16' | 'q8' | 'q4' | 'q4f16';
+declare function kokoroProvider(opts?: {
+  model?: string;
+  voice?: string;
+  dtype?: KokoroDtype;
+}): TtsProvider;
 declare function providerById(id: string): TtsProvider;
 interface AlignRequest {
   /** the synthesized RIFF/WAV bytes */
@@ -199,4 +207,4 @@ declare function synthesizeScript(scriptPath: string, opts?: SynthesizeOptions):
 /** Resolve `<scene>.narration.json` for a scene-module path (or accept the script itself). */
 declare function scriptPathFor(input: string): string;
 //#endregion
-export { AlignRequest, Aligner, SynthesizeOptions, SynthesizeResult, TtsProvider, TtsRequest, TtsResult, VoskAlignWord, alignerById, cacheKey, espeakProvider, fakeProvider, heuristicAligner, heuristicWords, interpolateMissing, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };
+export { AlignRequest, Aligner, KokoroDtype, SynthesizeOptions, SynthesizeResult, TtsProvider, TtsRequest, TtsResult, VoskAlignWord, alignerById, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };

package/dist/providers.js

@@ -1,9 +1,11 @@
 import { NarrationError, isPause } from "./index.js";
+import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
 //#region src/providers.ts
 /**
 * '@glissade/narrate/providers' — the Node-only prepare side. Provider calls
@@ -225,13 +227,139 @@ function piperProvider(opts = {}) {
 		}
 	};
 }
+/** PCM16 mono WAV from float samples in [-1, 1]. Round-to-nearest → deterministic. */
+function floatToWav(samples, sampleRate) {
+	const data = Buffer.alloc(samples.length * 2);
+	for (let i = 0; i < samples.length; i++) {
+		const s = Math.max(-1, Math.min(1, samples[i]));
+		data.writeInt16LE(Math.round(s * 32767), i * 2);
+	}
+	const header = Buffer.alloc(44);
+	header.write("RIFF", 0, "ascii");
+	header.writeUInt32LE(36 + data.length, 4);
+	header.write("WAVE", 8, "ascii");
+	header.write("fmt ", 12, "ascii");
+	header.writeUInt32LE(16, 16);
+	header.writeUInt16LE(1, 20);
+	header.writeUInt16LE(1, 22);
+	header.writeUInt32LE(sampleRate, 24);
+	header.writeUInt32LE(sampleRate * 2, 28);
+	header.writeUInt16LE(2, 32);
+	header.writeUInt16LE(16, 34);
+	header.write("data", 36, "ascii");
+	header.writeUInt32LE(data.length, 40);
+	return Buffer.concat([header, data]);
+}
+const KOKORO_MODEL = "onnx-community/Kokoro-82M-v1.0-ONNX";
+const KOKORO_DEFAULT_VOICE = "af_heart";
+/**
+* Apache-2.0 82M neural TTS — markedly more natural than espeak/piper, fully
+* offline on CPU via onnxruntime, no API key. Pure-Node through `kokoro-js`
+* (Transformers.js), so unlike piper there is no `pip install` / external
+* binary; `kokoro-js` is an OPTIONAL peer dep, lazy-loaded here.
+*
+* DETERMINISTIC by construction: inference takes tokenized phonemes + a FIXED
+* voice/style embedding (not diffusion-sampled per call), so the same text →
+* byte-identical PCM — no noise to zero out (piper's trick). `version()` pins
+* the lib version + model + dtype, so any of those moving invalidates the
+* cache. The model (~q8 92MB / fp32 326MB) downloads + caches on first use; it
+* stays out of the bundle and the determinism-critical path.
+*/
+/** kokoro-js version read by walking up from its entry (it does not export
+* `./package.json`, so the subpath can't be resolved directly). */
+function kokoroVersionFrom(entry) {
+	let dir = dirname(entry);
+	for (let i = 0; i < 8; i++) {
+		const p = join(dir, "package.json");
+		if (existsSync(p)) try {
+			const j = JSON.parse(readFileSync(p, "utf8"));
+			if (j.name === "kokoro-js" && j.version) return j.version;
+		} catch {}
+		const up = dirname(dir);
+		if (up === dir) break;
+		dir = up;
+	}
+	return "unknown";
+}
+/**
+* Resolve the OPTIONAL peer `kokoro-js` from the USER'S project first. Under
+* pnpm's isolated layout a peer is NOT linked into `@glissade/narrate`'s own
+* store dir, so a bare `import('kokoro-js')` from this module fails; resolving
+* relative to `process.cwd()` (where the user ran `add kokoro-js`) finds it.
+* Falls back to this module for hoisted/global installs. Returns a `file://`
+* entry URL (so the dynamic import is never bundled) + the resolved version.
+* Throws a NarrationError that carries the REAL resolution error.
+*/
+function resolveKokoro() {
+	const bases = [pathToFileURL(join(process.cwd(), "package.json")).href, import.meta.url];
+	let lastErr;
+	for (const base of bases) try {
+		const entry = createRequire(base).resolve("kokoro-js");
+		return {
+			entryUrl: pathToFileURL(entry).href,
+			version: kokoroVersionFrom(entry)
+		};
+	} catch (e) {
+		lastErr = e;
+	}
+	throw new NarrationError(`kokoro-js could not be resolved from ${process.cwd()} (${lastErr?.code ?? "error"}: ${lastErr?.message ?? "not found"}) — install it in your project (npm / pnpm / yarn add kokoro-js; pnpm users must also allow its native build scripts — see the narration docs), or use --provider piper/espeak/openai`);
+}
+function kokoroProvider(opts = {}) {
+	const modelId = opts.model ?? KOKORO_MODEL;
+	const dtype = opts.dtype ?? "q8";
+	let loaded = null;
+	const loadLib = async () => {
+		const { entryUrl } = resolveKokoro();
+		let mod;
+		try {
+			mod = await import(entryUrl);
+		} catch (e) {
+			const err = e;
+			throw new NarrationError(`kokoro-js failed to load from ${entryUrl} (${err?.code ?? "error"}: ${err?.message ?? String(e)}) — ensure kokoro-js and onnxruntime-node are installed, or use --provider piper/espeak/openai`);
+		}
+		const lib = mod["KokoroTTS"] ? mod : mod["default"];
+		if (!lib?.KokoroTTS) throw new NarrationError(`kokoro-js loaded but exposes no KokoroTTS export (from ${entryUrl})`);
+		return lib;
+	};
+	const getModel = () => loaded ??= loadLib().then((k) => k.KokoroTTS.from_pretrained(modelId, {
+		dtype,
+		device: "cpu"
+	}));
+	return {
+		id: "kokoro",
+		version: () => {
+			const { version } = resolveKokoro();
+			return Promise.resolve(`kokoro-js ${version} ${basename(modelId)} dtype=${dtype}`);
+		},
+		synthesize: async (req) => {
+			const tts = await getModel();
+			const voice = req.voice ?? opts.voice ?? KOKORO_DEFAULT_VOICE;
+			const genOpts = req.rate !== void 0 && req.rate > 0 ? {
+				voice,
+				speed: req.rate
+			} : { voice };
+			let audio;
+			try {
+				audio = await tts.generate(req.text, genOpts);
+			} catch (e) {
+				throw new NarrationError(`kokoro synthesis failed: ${e instanceof Error ? e.message : String(e)}`);
+			}
+			const wav = floatToWav(audio.audio, audio.sampling_rate);
+			return {
+				wav,
+				duration: wavDuration(wav)
+			};
+		}
+	};
+}
 function providerById(id) {
 	switch (id) {
 		case "fake": return fakeProvider();
 		case "espeak": return espeakProvider();
 		case "piper": return piperProvider();
+		case "kokoro": return kokoroProvider();
 		case "openai": return openaiProvider();
-		default: throw new NarrationError(`unknown TTS provider '${id}' (have: fake, espeak, piper, openai)`);
+		default: throw new NarrationError(`unknown TTS provider '${id}' (have: fake, espeak, piper, kokoro, openai)`);
 	}
 }
 /** ≈ syllable count: vowel groups, floored at 1 — a cheap spoken-length proxy. */
@@ -558,4 +686,4 @@ function scriptPathFor(input) {
 	return candidate;
 }
 //#endregion
-export { alignerById, cacheKey, espeakProvider, fakeProvider, heuristicAligner, heuristicWords, interpolateMissing, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };
+export { alignerById, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.8.0",
+  "version": "0.8.1-pre.1",
   "description": "glissade narration + captions: TTS at prepare time (gs narrate), deterministic caching, narration-anchored timeline beats, and captions as plain tracks. Render stays offline.",
   "license": "Apache-2.0",
   "type": "module",
@@ -19,14 +19,25 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.8.0",
-    "@glissade/scene": "0.8.0"
+    "@glissade/core": "0.8.1-pre.1",
+    "@glissade/scene": "0.8.1-pre.1"
+  },
+  "peerDependencies": {
+    "kokoro-js": "^1.2.0"
+  },
+  "peerDependenciesMeta": {
+    "kokoro-js": {
+      "optional": true
+    }
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tyevco/glissade.git",
     "directory": "packages/narrate"
   },
+  "devDependencies": {
+    "kokoro-js": "^1.2.1"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit"