@glissade/narrate 0.8.0 → 0.8.1-pre.0

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,27 @@ 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';
+/**
+ * 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.
+ */
+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 +220,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,4 +1,5 @@
 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";
@@ -225,13 +226,101 @@ 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.
+*/
+function kokoroProvider(opts = {}) {
+	const modelId = opts.model ?? KOKORO_MODEL;
+	const dtype = opts.dtype ?? "q8";
+	let loaded = null;
+	const loadLib = async () => {
+		try {
+			return await import("kokoro-js");
+		} catch {
+			throw new NarrationError("kokoro-js not found — `npm install kokoro-js` (it pulls onnxruntime-node), or use --provider piper/espeak/openai");
+		}
+	};
+	const getModel = () => loaded ??= loadLib().then((k) => k.KokoroTTS.from_pretrained(modelId, {
+		dtype,
+		device: "cpu"
+	}));
+	return {
+		id: "kokoro",
+		version: () => {
+			let lib = "kokoro-js";
+			try {
+				const req = createRequire(import.meta.url);
+				const pkg = JSON.parse(readFileSync(req.resolve("kokoro-js/package.json"), "utf8"));
+				if (pkg.version) lib = `kokoro-js ${pkg.version}`;
+			} catch {
+				throw new NarrationError("kokoro-js not found — `npm install kokoro-js` (it pulls onnxruntime-node), or use --provider piper/espeak/openai");
+			}
+			return Promise.resolve(`${lib} ${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 +647,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.0",
   "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.0",
+    "@glissade/scene": "0.8.1-pre.0"
+  },
+  "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"