@glissade/narrate 0.15.0-pre.0 → 0.15.0

package/dist/providers.js

@@ -21,9 +21,13 @@ import { pathToFileURL } from "node:url";
 * 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.
+* identity — a PURE pin-based string `misaki=<MISAKI_PIN> jieba=<JIEBA_PIN>
+* map=<PHONEME_MAP_VERSION>`, with NO Python (no spawn, no wheel introspection) —
+* folds UNCONDITIONALLY into kokoroProvider.version(), which keys the segment
+* cache. The pinned wheel version implies its bundled dict, so a live dict-hash is
+* not needed in the identity. Bumping any pin/map invalidates stale Mandarin audio.
+* The declared pins are ENFORCED against the installed wheel at synth time
+* (phonemize, via importlib.metadata) — a divergent wheel fails LOUDLY there.
 */
 /** The misaki wheel this seam is pinned to (matches scripts/gen-misaki-parity.py). */
 const MISAKI_PIN = "0.9.4";
@@ -38,40 +42,56 @@ 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;
+/**
+* On an installed-vs-PINNED version MISMATCH the phonemize program exits with this
+* exact code so the TS side raises an actionable `installed X != pinned PIN` error
+* (never a silent 'unknown'). Distinct from MISAKI_ABSENT_EXIT (97) and 0/1/2.
+*/
+const MISAKI_PIN_MISMATCH_EXIT = 96;
+/**
+* The phonemize Python program. It imports misaki[zh], ENFORCES the declared pins
+* (resolving the installed versions via `importlib.metadata.version(...)` — the
+* authoritative dist-info, present even when a wheel exposes no `__version__`, as
+* jieba historically does not), reads the Mandarin text from stdin, and writes
+* `<phonemes>` to stdout.
+*
+* Pin enforcement lives at SYNTH time (HERE), NOT in `version()`: `version()` is a
+* PURE pin-based identity string (no Python at all). A divergent wheel is caught
+* loudly here — on a mismatch it writes `<dist>:<installed>:<pinned>` to stderr and
+* exits MISAKI_PIN_MISMATCH_EXIT so the TS side raises an actionable error. ENOENT
+* (python absent) and ImportError (misaki absent → exit 97) remain the two
+* "g2p unavailable" exits; any other failure surfaces the Python traceback tail.
+*/
 const ZH_G2P_PY = String.raw`
-import sys, hashlib, os
+import sys
 
 try:
     import misaki, jieba
     from misaki import zh
+    from importlib.metadata import version, PackageNotFoundError
 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))
+# pins arrive as: --pins <misaki_pin> <jieba_pin>; enforce installed==pinned
+def _check_pins():
+    args = sys.argv[1:]
+    if "--pins" not in args:
+        return
+    i = args.index("--pins")
+    pins = (("misaki", args[i + 1]), ("jieba", args[i + 2]))
+    for dist, pin in pins:
+        try:
+            installed = version(dist)
+        except PackageNotFoundError:
+            installed = "unknown"
+        if installed != pin:
+            sys.stderr.write("%s:%s:%s\n" % (dist, installed, pin))
+            sys.exit(96)
 
 def _phonemize():
     g = zh.ZHG2P()
@@ -79,16 +99,25 @@ def _phonemize():
     phonemes, _ = g(text)
     sys.stdout.buffer.write(phonemes.encode("utf-8"))
 
-if "--id" in sys.argv[1:]:
-    _ident()
-else:
-    _phonemize()
+_check_pins()
+_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.`);
 }
+/**
+* Raised when the installed misaki/jieba wheel diverges from the declared pins
+* (the MISAKI_PIN_MISMATCH_EXIT sentinel at synth time). The Python side wrote
+* `<dist>:<installed>:<pinned>` to stderr; we surface it as an actionable error so
+* a divergent wheel is caught LOUDLY rather than silently hashing to 'unknown'.
+*/
+function pinMismatchError(python, stderr) {
+	const line = (typeof stderr === "string" ? stderr : stderr?.toString("utf8") ?? "").trim().split("\n").pop() ?? "";
+	const [dist, installed, pinned] = line.split(":");
+	return new NarrationError(`misaki[zh] g2p pin mismatch via '${python}': ${dist && installed && pinned ? `installed ${dist} ${installed} != pinned ${dist === "misaki" ? "MISAKI_PIN" : "JIEBA_PIN"} ${pinned}` : `installed misaki/jieba wheel diverges from the declared pins (${line || "no detail"})`} — the segment cache identity is keyed on the pins, so a divergent wheel would produce uncacheable/cross-machine-divergent audio. Install the pinned wheels: \`pip install 'misaki[zh]==${MISAKI_PIN}' 'jieba==${JIEBA_PIN}'\` into that interpreter (or set MISAKI_PYTHON to one that has them).`);
+}
 /** Surface a real (non-ENOENT) spawn error as a NarrationError, else null.
 *  ENOENT (python absent) becomes the install hint. */
 function spawnFailure(r, python) {
@@ -106,26 +135,22 @@ function misakiZhG2p(opts = {}) {
 	const python = opts.python ?? process.env["MISAKI_PYTHON"] ?? DEFAULT_PYTHON;
 	return {
 		id: "misaki-zh",
-		version: () => {
+		version: () => `misaki-zh misaki=${MISAKI_PIN} jieba=${JIEBA_PIN} map=${PHONEME_MAP_VERSION}`,
+		phonemize: (text) => {
 			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], {
+				"--pins",
+				MISAKI_PIN,
+				JIEBA_PIN
+			], {
 				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 === MISAKI_PIN_MISMATCH_EXIT) throw pinMismatchError(python, r.stderr);
 			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))}`);
@@ -440,7 +465,6 @@ 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();
@@ -463,8 +487,7 @@ function kokoroProvider(opts = {}) {
 		id: "kokoro",
 		version: () => {
 			const { version } = resolveKokoro();
-			let v = `kokoro-js ${version} ${basename(modelId)} dtype=${dtype}`;
-			if (usesChinese) v += ` g2p=[${zhG2p.version()}]`;
+			const v = `kokoro-js ${version} ${basename(modelId)} dtype=${dtype} g2p=[${zhG2p.version()}]`;
 			return Promise.resolve(v);
 		},
 		synthesize: async (req) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.15.0-pre.0",
+  "version": "0.15.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.15.0-pre.0",
-    "@glissade/scene": "0.15.0-pre.0"
+    "@glissade/core": "0.15.0",
+    "@glissade/scene": "0.15.0"
   },
   "peerDependencies": {
     "kokoro-js": "^1.2.0"