@glissade/narrate 0.14.0 → 0.15.0-pre.0

package/dist/providers.d.ts

@@ -1,5 +1,21 @@
 import { NarrationTiming } from "./index.js";
 
+//#region src/zh-g2p.d.ts
+
+interface ZhG2p {
+  readonly id: string;
+  /** the g2p identity, folded into kokoroProvider.version() → the cache key */
+  version(): string;
+  /** Mandarin text → a misaki[zh] phoneme string (custom-IPA + arrow tones) */
+  phonemize(text: string): string;
+}
+/**
+ * Fork B: shell out to a pinned Python misaki[zh]. Mirrors piperProvider — same
+ * spawnSync, same ENOENT-is-the-only-true-absent feature detection, same
+ * version()-parse-and-fold-into-the-cache-key contract (piper even pip-installs
+ * its Python tool, so the precedent is exact).
+ */
+//#endregion
 //#region src/providers.d.ts
 
 interface TtsRequest {
@@ -71,10 +87,13 @@ declare function piperProvider(opts?: {
 /** 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';
+/** A z* (zf_/zm_) kokoro voice routes through misaki[zh] g2p (not espeak cmn). */
+declare function isKokoroChineseVoice(voice: string): boolean;
 declare function kokoroProvider(opts?: {
   model?: string;
   voice?: string;
   dtype?: KokoroDtype;
+  zhG2p?: ZhG2p;
 }): TtsProvider;
 declare function providerById(id: string): TtsProvider;
 interface AlignRequest {
@@ -207,4 +226,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, 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 };
+export { AlignRequest, Aligner, KokoroDtype, SynthesizeOptions, SynthesizeResult, TtsProvider, TtsRequest, TtsResult, VoskAlignWord, alignerById, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, isKokoroChineseVoice, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };

package/dist/providers.js

@@ -6,6 +6,134 @@ 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/zh-g2p.ts
+/**
+* '@glissade/narrate/providers' Chinese g2p seam — Mandarin text → a misaki[zh]
+* phoneme string (custom-IPA + arrow tone marks ↓→↗↘), the alphabet the kokoro
+* z* (zf_/zm_) voices were trained on. Without this, kokoro-js routes Chinese
+* through espeak-ng `cmn`, whose phonemes mismatch → garbled audio.
+*
+* Fork B = shell out to a PINNED Python misaki[zh], reusing the EXACT pattern
+* piperProvider/espeakProvider ship: spawnSync + ENOENT-is-the-only-true-absent
+* + a version() string that folds into the cache key. The shared oracle is the
+* committed parity corpus (test/fixtures/misaki-zh-parity.json) — produced ONCE
+* from this same Python reference (scripts/gen-misaki-parity.py); a future
+* pure-TS Fork A can be checked against it offline.
+*
+* DETERMINISM: g2p runs at PREPARE time (gs narrate), never at render. Its
+* identity (engine-id + jieba-dict hash + phoneme-map version + the pinned
+* misaki wheel version) folds into kokoroProvider.version(), which keys the
+* segment cache — so any g2p change invalidates stale/cross-machine audio.
+*/
+/** The misaki wheel this seam is pinned to (matches scripts/gen-misaki-parity.py). */
+const MISAKI_PIN = "0.9.4";
+/** The jieba dict this seam is pinned to (its segmentation drives word boundaries). */
+const JIEBA_PIN = "0.42.1";
+/**
+* The phoneme-map version: bump when our text→misaki invocation changes in a way
+* that can move phoneme bytes (e.g. a normalization tweak), independent of the
+* misaki wheel. Folds into the g2p identity → the cache key.
+*/
+const PHONEME_MAP_VERSION = "zh-misaki-1";
+/** The default Python interpreter; override via opts.python or MISAKI_PYTHON. */
+const DEFAULT_PYTHON = "python3";
+/**
+* The Python program we shell out to. It imports misaki[zh], builds the g2p once,
+* reads the Mandarin text from stdin, prints `<phonemes>\n` to stdout, and — when
+* asked with `--id` — prints a stable identity line
+*   `misaki=<ver> jieba=<ver> dict=<sha12>`
+* (jieba dict hash included: its segmentation determines word boundaries, so a
+* dict change can move phonemes). ENOENT (python absent) is the only true
+* "g2p unavailable"; any other failure surfaces the Python traceback tail.
+*/
+/**
+* On a missing misaki/jieba import the program exits with this exact code (not a
+* raw traceback) so the TS side can raise the install hint — the Python-present-
+* but-misaki-absent analogue of ENOENT. Picked to not collide with 0/1/2.
+*/
+const MISAKI_ABSENT_EXIT = 97;
+const ZH_G2P_PY = String.raw`
+import sys, hashlib, os
+
+try:
+    import misaki, jieba
+    from misaki import zh
+except ImportError:
+    sys.exit(97)
+
+def _ident():
+    mv = getattr(misaki, "__version__", "unknown")
+    jv = getattr(jieba, "__version__", "unknown")
+    # hash jieba's prefix dict — its segmentation drives the phoneme boundaries
+    dpath = os.path.join(os.path.dirname(jieba.__file__), "dict.txt")
+    try:
+        with open(dpath, "rb") as f:
+            dh = hashlib.sha256(f.read()).hexdigest()[:12]
+    except OSError:
+        dh = "nodict"
+    sys.stdout.write("misaki=%s jieba=%s dict=%s\n" % (mv, jv, dh))
+
+def _phonemize():
+    g = zh.ZHG2P()
+    text = sys.stdin.buffer.read().decode("utf-8")
+    phonemes, _ = g(text)
+    sys.stdout.buffer.write(phonemes.encode("utf-8"))
+
+if "--id" in sys.argv[1:]:
+    _ident()
+else:
+    _phonemize()
+`;
+/** The shared install hint — raised when Python is absent (ENOENT) OR present
+*  but misaki/jieba can't be imported (the MISAKI_ABSENT_EXIT sentinel). */
+function installHint(python, why) {
+	return new NarrationError(`${why === "python" ? `Python ('${python}') not found on PATH for misaki[zh] g2p` : `misaki[zh] is not importable from '${python}'`} — the kokoro Chinese (z*) route needs it. Install: \`pip install 'misaki[zh]==${MISAKI_PIN}' 'jieba==${JIEBA_PIN}'\` into that interpreter (or set MISAKI_PYTHON to one that has it), or use --provider piper for Chinese.`);
+}
+/** Surface a real (non-ENOENT) spawn error as a NarrationError, else null.
+*  ENOENT (python absent) becomes the install hint. */
+function spawnFailure(r, python) {
+	if (!r.error) return null;
+	if (r.error.code === "ENOENT") return installHint(python, "python");
+	return new NarrationError(`could not run misaki[zh] g2p via '${python}': ${r.error.message}`);
+}
+/**
+* Fork B: shell out to a pinned Python misaki[zh]. Mirrors piperProvider — same
+* spawnSync, same ENOENT-is-the-only-true-absent feature detection, same
+* version()-parse-and-fold-into-the-cache-key contract (piper even pip-installs
+* its Python tool, so the precedent is exact).
+*/
+function misakiZhG2p(opts = {}) {
+	const python = opts.python ?? process.env["MISAKI_PYTHON"] ?? DEFAULT_PYTHON;
+	return {
+		id: "misaki-zh",
+		version: () => {
+			const r = spawnSync(python, [
+				"-c",
+				ZH_G2P_PY,
+				"--id"
+			], { encoding: "utf8" });
+			const fail = spawnFailure(r, python);
+			if (fail) throw fail;
+			if (r.status === MISAKI_ABSENT_EXIT) throw installHint(python, "misaki");
+			if (r.status !== 0) throw new NarrationError(`misaki[zh] g2p not available via '${python}' (exit ${String(r.status)}): ${stderrTail(r.stderr)} — \`pip install 'misaki[zh]==${MISAKI_PIN}' 'jieba==${JIEBA_PIN}'\` into that interpreter.`);
+			return `misaki-zh ${(r.stdout ?? "").trim()} map=${PHONEME_MAP_VERSION}`;
+		},
+		phonemize: (text) => {
+			const r = spawnSync(python, ["-c", ZH_G2P_PY], {
+				input: text,
+				maxBuffer: 8 * 1024 * 1024
+			});
+			const fail = spawnFailure(r, python);
+			if (fail) throw fail;
+			if (r.status === MISAKI_ABSENT_EXIT) throw installHint(python, "misaki");
+			if (r.status !== 0) throw new NarrationError(`misaki[zh] g2p failed: ${stderrTail(r.stderr)}`);
+			const out = r.stdout?.toString("utf8") ?? "";
+			if (out.length === 0) throw new NarrationError(`misaki[zh] g2p produced no phonemes for text: ${JSON.stringify(text.slice(0, 60))}`);
+			return out;
+		}
+	};
+}
+//#endregion
 //#region src/providers.ts
 /**
 * '@glissade/narrate/providers' — the Node-only prepare side. Provider calls
@@ -304,9 +432,15 @@ function resolveKokoro() {
 	}
 	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`);
 }
+/** A z* (zf_/zm_) kokoro voice routes through misaki[zh] g2p (not espeak cmn). */
+function isKokoroChineseVoice(voice) {
+	return voice.startsWith("zf_") || voice.startsWith("zm_");
+}
 function kokoroProvider(opts = {}) {
 	const modelId = opts.model ?? KOKORO_MODEL;
 	const dtype = opts.dtype ?? "q8";
+	const zhG2p = opts.zhG2p ?? misakiZhG2p();
+	const usesChinese = isKokoroChineseVoice(opts.voice ?? KOKORO_DEFAULT_VOICE);
 	let loaded = null;
 	const loadLib = async () => {
 		const { entryUrl } = resolveKokoro();
@@ -329,21 +463,34 @@ function kokoroProvider(opts = {}) {
 		id: "kokoro",
 		version: () => {
 			const { version } = resolveKokoro();
-			return Promise.resolve(`kokoro-js ${version} ${basename(modelId)} dtype=${dtype}`);
+			let v = `kokoro-js ${version} ${basename(modelId)} dtype=${dtype}`;
+			if (usesChinese) v += ` g2p=[${zhG2p.version()}]`;
+			return Promise.resolve(v);
 		},
 		synthesize: async (req) => {
 			const voice = req.voice ?? opts.voice ?? KOKORO_DEFAULT_VOICE;
-			if (voice.startsWith("zf_") || voice.startsWith("zm_")) throw new NarrationError("kokoro Chinese voices (z*) need misaki[zh] g2p (pinyin+jieba), which is not wired — kokoro-js routes zh through espeak-ng cmn (mismatched phonemes → garbled). Use --provider piper for Chinese. (tracked: card 24vKUw2HVC6D)");
-			const tts = await getModel();
-			const genOpts = req.rate !== void 0 && req.rate > 0 ? {
+			const speed = req.rate !== void 0 && req.rate > 0 ? req.rate : void 0;
+			const genOpts = speed !== void 0 ? {
 				voice,
-				speed: req.rate
+				speed
 			} : { 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)}`);
+			if (isKokoroChineseVoice(voice)) {
+				const phonemes = zhG2p.phonemize(req.text);
+				const tts = await getModel();
+				try {
+					const { input_ids } = tts.tokenizer(phonemes, { truncation: true });
+					audio = await tts.generate_from_ids(input_ids, genOpts);
+				} catch (e) {
+					throw new NarrationError(`kokoro Chinese synthesis failed: ${e instanceof Error ? e.message : String(e)}`);
+				}
+			} else {
+				const tts = await getModel();
+				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 {
@@ -691,4 +838,4 @@ function scriptPathFor(input) {
 	return candidate;
 }
 //#endregion
-export { alignerById, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };
+export { alignerById, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, isKokoroChineseVoice, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.14.0",
+  "version": "0.15.0-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",
   "engines": {
@@ -22,8 +22,8 @@
     "dist"
   ],
   "dependencies": {
-    "@glissade/core": "0.14.0",
-    "@glissade/scene": "0.14.0"
+    "@glissade/core": "0.15.0-pre.0",
+    "@glissade/scene": "0.15.0-pre.0"
   },
   "peerDependencies": {
     "kokoro-js": "^1.2.0"