@glissade/narrate 0.22.0-pre.3 → 0.22.0-pre.5

package/dist/providers.d.ts

@@ -16,6 +16,21 @@ interface ZhG2p {
  * its Python tool, so the precedent is exact).
  */
 //#endregion
+//#region src/en-g2p.d.ts
+
+interface EnG2p {
+  readonly id: string;
+  /** the g2p identity, folded into kokoroProvider.version() → the cache key */
+  version(): string;
+  /** English text → a misaki[en] phoneme string (US English) */
+  phonemize(text: string): string;
+}
+/**
+ * Fork B: shell out to a pinned Python misaki[en]. Mirrors {@link misakiZhG2p} —
+ * same spawnSync, same ENOENT-is-the-only-true-absent feature detection, same
+ * PURE pin-based version()-fold-into-the-cache-key contract.
+ */
+//#endregion
 //#region src/providers.d.ts
 
 interface TtsRequest {
@@ -202,6 +217,7 @@ declare function kokoroProvider(opts?: {
   voice?: VoiceSpec;
   dtype?: KokoroDtype;
   zhG2p?: ZhG2p;
+  enG2p?: EnG2p;
 }): TtsProvider;
 declare function providerById(id: string): TtsProvider;
 interface AlignRequest {

package/dist/providers.js

@@ -40,19 +40,19 @@ const JIEBA_PIN = "0.42.1";
 */
 const PHONEME_MAP_VERSION = "zh-misaki-1";
 /** The default Python interpreter; override via opts.python or MISAKI_PYTHON. */
-const DEFAULT_PYTHON = "python3";
+const DEFAULT_PYTHON$1 = "python3";
 /**
 * 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 MISAKI_ABSENT_EXIT$1 = 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;
+const MISAKI_PIN_MISMATCH_EXIT$1 = 96;
 /**
 * The phonemize Python program. It imports misaki[zh], ENFORCES the declared pins
 * (resolving the installed versions via `importlib.metadata.version(...)` — the
@@ -104,7 +104,7 @@ _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) {
+function installHint$1(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.`);
 }
 /**
@@ -113,16 +113,16 @@ function installHint(python, why) {
 * `<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) {
+function pinMismatchError$1(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) {
+function spawnFailure$1(r, python) {
 	if (!r.error) return null;
-	if (r.error.code === "ENOENT") return installHint(python, "python");
+	if (r.error.code === "ENOENT") return installHint$1(python, "python");
 	return new NarrationError(`could not run misaki[zh] g2p via '${python}': ${r.error.message}`);
 }
 /**
@@ -132,7 +132,7 @@ function spawnFailure(r, python) {
 * its Python tool, so the precedent is exact).
 */
 function misakiZhG2p(opts = {}) {
-	const python = opts.python ?? process.env["MISAKI_PYTHON"] ?? DEFAULT_PYTHON;
+	const python = opts.python ?? process.env["MISAKI_PYTHON"] ?? DEFAULT_PYTHON$1;
 	return {
 		id: "misaki-zh",
 		version: () => `misaki-zh misaki=${MISAKI_PIN} jieba=${JIEBA_PIN} map=${PHONEME_MAP_VERSION}`,
@@ -147,13 +147,160 @@ function misakiZhG2p(opts = {}) {
 				input: text,
 				maxBuffer: 8 * 1024 * 1024
 			});
+			const fail = spawnFailure$1(r, python);
+			if (fail) throw fail;
+			if (r.status === MISAKI_ABSENT_EXIT$1) throw installHint$1(python, "misaki");
+			if (r.status === MISAKI_PIN_MISMATCH_EXIT$1) throw pinMismatchError$1(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))}`);
+			return out;
+		}
+	};
+}
+//#endregion
+//#region src/en-g2p.ts
+/**
+* '@glissade/narrate/providers' English g2p seam — English text → a misaki[en]
+* phoneme string, the alphabet the kokoro English (`af_`/`am_`/`bf_`/`bm_`)
+* voices were trained on. The gh#2 ENGLISH BLEND follow-up: a blended voice has
+* no registered name, so it must drive `generate_from_ids` with a SUMMED style
+* tensor — which bypasses kokoro-js's internal English phonemizer. So, exactly as
+* the shipped Chinese blend runs misaki[zh] itself, this runs misaki[en] itself.
+*
+* Fork B = shell out to a PINNED Python misaki[en], the SAME pattern as
+* {@link './zh-g2p'} (spawnSync + ENOENT-is-the-only-true-absent + a pure
+* pin-based `version()` that folds into the cache key). misaki[en]'s G2P uses a
+* spaCy tagger (`en_core_web_sm`) + an espeak fallback for out-of-dictionary
+* words — so the install surface is heavier than zh's (misaki[en] + the spaCy
+* model + espeak-ng); each missing piece exits with a distinct code → an
+* actionable hint.
+*
+* DIALECT: US English (`british=False`) — the `af_`/`am_` (American) voices.
+* GB-voice (`bf_`/`bm_`) blends are a documented follow-up; the dialect folds
+* into `version()` so US and GB never share a cache entry.
+*
+* DETERMINISM: g2p runs at PREPARE time, never at render. Its identity — a PURE
+* pin string `misaki=<PIN> map=<MAP> dialect=us` (NO Python, no spawn) — folds
+* UNCONDITIONALLY into kokoroProvider.version() → the segment cache key. The
+* misaki dictionary (the vast majority of words) is fully pinned/deterministic;
+* OOV words route through the espeak fallback, whose phonemes depend on the local
+* espeak-ng (the one OOV-determinism caveat, shared with Kokoro's own English
+* g2p — noted, not silently swept). The pin is ENFORCED against the installed
+* wheel at synth time.
+*/
+/**
+* The phoneme-map version: bump when our text→misaki[en] invocation changes in a
+* way that can move phoneme bytes (normalization, dialect default, fallback
+* wiring), independent of the misaki wheel. Folds into the g2p identity.
+*/
+const EN_PHONEME_MAP_VERSION = "en-misaki-1";
+/** The default Python interpreter; override via opts.python or MISAKI_PYTHON
+* (shared with the zh seam — one interpreter has both extras). */
+const DEFAULT_PYTHON = "python3";
+/** misaki[en] not importable (the Python-present-but-misaki-absent analogue of ENOENT). */
+const MISAKI_ABSENT_EXIT = 97;
+/** installed misaki wheel != the declared pin (caught loudly at synth). */
+const MISAKI_PIN_MISMATCH_EXIT = 96;
+/** the espeak fallback (espeakng) can't load — OOV words would be dropped. */
+const ESPEAK_ABSENT_EXIT = 95;
+/** the spaCy English tagger model (`en_core_web_sm`) isn't installed. */
+const SPACY_MODEL_ABSENT_EXIT = 94;
+/**
+* The phonemize Python program: import misaki[en], ENFORCE the misaki pin, build
+* the US-English G2P (spaCy `en_core_web_sm` tagger + espeak fallback for OOV),
+* read text from stdin, write `<phonemes>` to stdout. Each missing dependency
+* gets its OWN exit code so the TS side raises a specific install hint.
+*/
+const EN_G2P_PY = String.raw`
+import sys
+
+try:
+    import misaki
+    from misaki import en
+    from importlib.metadata import version, PackageNotFoundError
+except ImportError:
+    sys.exit(97)
+
+# pins arrive as: --pins <misaki_pin>; enforce installed==pinned
+def _check_pins():
+    args = sys.argv[1:]
+    if "--pins" not in args:
+        return
+    i = args.index("--pins")
+    pin = args[i + 1]
+    try:
+        installed = version("misaki")
+    except PackageNotFoundError:
+        installed = "unknown"
+    if installed != pin:
+        sys.stderr.write("misaki:%s:%s\n" % (installed, pin))
+        sys.exit(96)
+
+def _g2p():
+    try:
+        from misaki import espeak
+        fallback = espeak.EspeakFallback(british=False)
+    except Exception:
+        sys.exit(95)
+    try:
+        g = en.G2P(trf=False, british=False, fallback=fallback)
+    except OSError:
+        # spaCy en_core_web_sm model not downloaded
+        sys.exit(94)
+    text = sys.stdin.buffer.read().decode("utf-8")
+    phonemes, _ = g(text)
+    sys.stdout.buffer.write((phonemes or "").encode("utf-8"))
+
+_check_pins()
+_g2p()
+`;
+/** Install hint — Python absent (ENOENT), misaki[en] absent, or a missing
+*  sub-dependency (espeak fallback / spaCy model). */
+function installHint(python, why) {
+	return new NarrationError(`${why === "python" ? `Python ('${python}') not found on PATH for misaki[en] g2p` : why === "misaki" ? `misaki[en] is not importable from '${python}'` : why === "espeak" ? `misaki[en]'s espeak fallback is unavailable from '${python}' (needed for out-of-dictionary words)` : `misaki[en]'s spaCy tagger model 'en_core_web_sm' is not installed for '${python}'`} — the kokoro ENGLISH voice-blend route (gh#2) needs it. Install: ${why === "spacy" ? `\`${python} -m spacy download en_core_web_sm\`` : why === "espeak" ? `\`pip install misaki[en]\` AND install the espeak-ng system library (e.g. \`apt-get install espeak-ng\`)` : `\`pip install 'misaki[en]==${MISAKI_PIN}'\` AND \`${python} -m spacy download en_core_web_sm\` AND the espeak-ng system library`} into that interpreter (or set MISAKI_PYTHON to one that has it). A single English voice (the named path) does NOT need this; only English BLENDS do.`);
+}
+/** The installed misaki wheel diverges from the declared pin (caught at synth). */
+function pinMismatchError(python, stderr) {
+	const line = (typeof stderr === "string" ? stderr : stderr?.toString("utf8") ?? "").trim().split("\n").pop() ?? "";
+	const [, installed, pinned] = line.split(":");
+	return new NarrationError(`misaki[en] g2p pin mismatch via '${python}': ${installed && pinned ? `installed misaki ${installed} != pinned ${pinned}` : `installed misaki wheel diverges from the declared pin (${line || "no detail"})`} — the segment cache identity is keyed on the pin, so a divergent wheel would produce uncacheable/cross-machine-divergent audio. Install the pinned wheel: \`pip install 'misaki[en]==${MISAKI_PIN}'\` into that interpreter.`);
+}
+/** Surface a real (non-ENOENT) spawn error, else null. */
+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[en] g2p via '${python}': ${r.error.message}`);
+}
+/**
+* Fork B: shell out to a pinned Python misaki[en]. Mirrors {@link misakiZhG2p} —
+* same spawnSync, same ENOENT-is-the-only-true-absent feature detection, same
+* PURE pin-based version()-fold-into-the-cache-key contract.
+*/
+function misakiEnG2p(opts = {}) {
+	const python = opts.python ?? process.env["MISAKI_PYTHON"] ?? DEFAULT_PYTHON;
+	return {
+		id: "misaki-en",
+		version: () => `misaki-en misaki=${MISAKI_PIN} map=${EN_PHONEME_MAP_VERSION} dialect=us`,
+		phonemize: (text) => {
+			const r = spawnSync(python, [
+				"-c",
+				EN_G2P_PY,
+				"--pins",
+				MISAKI_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 === ESPEAK_ABSENT_EXIT) throw installHint(python, "espeak");
+			if (r.status === SPACY_MODEL_ABSENT_EXIT) throw installHint(python, "spacy");
 			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)}`);
+			if (r.status !== 0) throw new NarrationError(`misaki[en] 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))}`);
+			if (out.length === 0) throw new NarrationError(`misaki[en] g2p produced no phonemes for text: ${JSON.stringify(text.slice(0, 60))}`);
 			return out;
 		}
 	};
@@ -613,6 +760,7 @@ function kokoroProvider(opts = {}) {
 	const modelId = opts.model ?? KOKORO_MODEL;
 	const dtype = opts.dtype ?? "q8";
 	const zhG2p = opts.zhG2p ?? misakiZhG2p();
+	const enG2p = opts.enG2p ?? misakiEnG2p();
 	let loaded = null;
 	const loadLib = async () => {
 		const { entry, entryUrl } = resolveKokoro();
@@ -641,7 +789,11 @@ function kokoroProvider(opts = {}) {
 		id: "kokoro",
 		version: () => {
 			const { version } = resolveKokoro();
-			const blendSuffix = isVoiceBlend(opts.voice) ? ` ${blendIdentity(opts.voice)}` : "";
+			let blendSuffix = "";
+			if (isVoiceBlend(opts.voice)) {
+				blendSuffix = ` ${blendIdentity(opts.voice)}`;
+				if (resolveBlend(opts.voice).language === "en") blendSuffix += ` en-g2p=[${enG2p.version()}]`;
+			}
 			const v = `kokoro-js ${version} ${basename(modelId)} dtype=${dtype} g2p=[${zhG2p.version()}]${blendSuffix}`;
 			return Promise.resolve(v);
 		},
@@ -660,7 +812,10 @@ function kokoroProvider(opts = {}) {
 					if (resolved.language === "zh") {
 						const phonemes = zhG2p.phonemize(req.text);
 						inputIds = tts.tokenizer(phonemes, { truncation: true }).input_ids;
-					} else throw new NarrationError("English voice blends are not yet supported (the z*/Chinese blend is the shipped path) — use a single English voice, or a Chinese (zf_/zm_) blend; see gh#2 for the English follow-up");
+					} else {
+						const phonemes = enG2p.phonemize(req.text);
+						inputIds = tts.tokenizer(phonemes, { truncation: true }).input_ids;
+					}
 					const audio = await kokoroGenerateFromBlend(tts, Tensor, inputIds, blended, speed ?? 1);
 					const wav = floatToWav(audio.audio, audio.sampling_rate);
 					return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/narrate",
-  "version": "0.22.0-pre.3",
+  "version": "0.22.0-pre.5",
   "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.22.0-pre.3",
-    "@glissade/scene": "0.22.0-pre.3"
+    "@glissade/core": "0.22.0-pre.5",
+    "@glissade/scene": "0.22.0-pre.5"
   },
   "peerDependencies": {
     "kokoro-js": "^1.2.0"