@glissade/narrate 0.15.0 → 0.16.0-pre.0

package/dist/index.d.ts

@@ -3,10 +3,36 @@ import { FilterSpec, Text } from "@glissade/scene";
 
 //#region src/index.d.ts
 
+/**
+ * One weighted base voice in a blend: `[<voiceName>, <weight>]`. Weights are
+ * NORMALIZED to sum to 1 at resolution (so `[["a",1],["b",1]]` is 50/50, not
+ * 2×). Each `weight` must be finite and > 0.
+ */
+type VoiceBlendEntry = readonly [voice: string, weight: number];
+/**
+ * A blended kokoro voice — a weighted sum of two-or-more named base voices'
+ * `[510×256]` style vectors, computed ONCE at prepare time into a derived
+ * custom voice (the HF "Make Custom Voices With KokoroTTS" recipe). All base
+ * voices must share a language front-end (all Chinese `zf_`/`zm_` OR all
+ * English; a mixed-language blend throws — different g2p). Both names + weights
+ * fold into the provider `version()`, so the segment cache invalidates whenever
+ * any weight or base voice changes. kokoro-only.
+ */
+interface VoiceBlend {
+  /** ≥2 weighted base voices; weights normalized to sum to 1. */
+  blend: readonly VoiceBlendEntry[];
+}
+/**
+ * A voice is EITHER a provider voice name (the string form, unchanged) OR a
+ * `VoiceBlend` spec (kokoro only — a weighted sum of named base voices).
+ */
+type VoiceSpec = string | VoiceBlend;
+/** A `VoiceSpec` is a blend when it carries a `blend` array (vs a plain string). */
+declare function isVoiceBlend(voice: VoiceSpec | undefined): voice is VoiceBlend;
 interface NarrationSegment {
   id: string;
   text: string;
-  voice?: string;
+  voice?: VoiceSpec;
   /** speaking rate multiplier; 1 = provider default */
   rate?: number;
   /** silence after THIS segment (s); overrides the script default */
@@ -45,7 +71,7 @@ declare function isPause(el: NarrationElement): el is NarrationPause;
 interface NarrationScript {
   narrationVersion: 1;
   provider?: string;
-  voice?: string;
+  voice?: VoiceSpec;
   rate?: number;
   /** silence between segments (s); default 0.35 */
   gap?: number;
@@ -327,4 +353,4 @@ declare function music(timing: MusicTiming, at?: number): MusicAnchors;
 declare function toSrt(timing: NarrationTiming): string;
 declare function toVtt(timing: NarrationTiming): string;
 //#endregion
-export { BedMode, CaptionCue, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, captionNode, captionTrack, duckEnvelope, isPause, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };
+export { BedMode, CaptionCue, CaptionStyle, CaptionTrackOptions, DuckOptions, MusicAnchors, MusicClipOptions, MusicTiming, NarrationAnchors, NarrationElement, NarrationError, NarrationPause, NarrationScript, NarrationSegment, NarrationTiming, TimedPause, TimedSegment, TimedWord, VoiceBlend, VoiceBlendEntry, VoiceSpec, captionNode, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };

package/dist/index.js

@@ -8,6 +8,10 @@ import { Text, breakLines, estimatingMeasurer, glow, quantize } from "@glissade/
 * offline and deterministic. Captions are a plain string track driving a
 * Text node — they live in the timeline JSON and golden-frame CI covers them.
 */
+/** A `VoiceSpec` is a blend when it carries a `blend` array (vs a plain string). */
+function isVoiceBlend(voice) {
+	return typeof voice === "object" && voice !== null && Array.isArray(voice.blend);
+}
 /** A pause element is the one carrying a numeric `pause` field. */
 function isPause(el) {
 	return typeof el.pause === "number";
@@ -363,4 +367,4 @@ function toVtt(timing) {
 	return "WEBVTT\n\n" + timing.segments.flatMap((s) => splitCaption(s, timing.captionSplit?.maxChars)).map((c) => `${srtTime(c.start, ".")} --> ${srtTime(c.end, ".")}\n${c.text}`).join("\n\n") + "\n";
 }
 //#endregion
-export { NarrationError, captionNode, captionTrack, duckEnvelope, isPause, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };
+export { NarrationError, captionNode, captionTrack, duckEnvelope, isPause, isVoiceBlend, music, narration, splitCaption, toSrt, toVtt, validateMusicTiming };

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-import { NarrationTiming } from "./index.js";
+import { NarrationTiming, VoiceBlend, VoiceSpec } from "./index.js";
 
 //#region src/zh-g2p.d.ts
 
@@ -20,7 +20,8 @@ interface ZhG2p {
 
 interface TtsRequest {
   text: string;
-  voice?: string;
+  /** a provider voice NAME (string) or a kokoro `VoiceBlend` (weighted sum) */
+  voice?: VoiceSpec;
   rate?: number;
 }
 interface TtsResult {
@@ -43,6 +44,13 @@ interface TtsProvider {
 }
 /** Parse duration from a RIFF/WAV header (PCM): data bytes / byte-rate. */
 declare function wavDuration(wav: Buffer): number;
+/**
+ * Coerce a request voice to a plain NAME string for the providers that only
+ * speak named voices (espeak / openai / piper). A `VoiceBlend` is kokoro-only,
+ * so it is a clear authoring error to hand one to any other provider — throw
+ * rather than silently stringify `[object Object]` into the request.
+ */
+declare function requireStringVoice(voice: VoiceSpec | undefined, provider: string): string | undefined;
 /**
  * A pure function of the request: a quiet tone whose duration models reading
  * speed (≈170 wpm + lead-out). Same text → identical bytes, every machine.
@@ -87,11 +95,111 @@ 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';
+interface KokoroAudio {
+  audio: Float32Array;
+  sampling_rate: number;
+}
+/** the StyleTextToSpeech2 ONNX module call: {input_ids, style, speed} → {waveform}. */
+type KokoroOnnxModel = (inputs: {
+  input_ids: unknown;
+  style: unknown;
+  speed: unknown;
+}) => Promise<{
+  waveform: {
+    data: Float32Array;
+  };
+}>;
+interface KokoroModel {
+  generate(text: string, opts: {
+    voice?: string;
+    speed?: number;
+  }): Promise<KokoroAudio>;
+  /** char-isolated tokenizer over kokoro's phoneme alphabet → model input ids */
+  tokenizer(text: string, opts?: {
+    truncation?: boolean;
+  }): {
+    input_ids: KokoroInputIds;
+  };
+  /** the g2p BYPASS: pre-tokenized phoneme ids straight to the model (no espeak) */
+  generate_from_ids(input_ids: unknown, opts: {
+    voice?: string;
+    speed?: number;
+  }): Promise<KokoroAudio>;
+  /** the underlying StyleTextToSpeech2 ONNX module — the BLEND path calls it
+   *  directly with a SUMMED style tensor (generate_from_ids only accepts a
+   *  named voice it loads from disk; a blend has no registered name). */
+  model: KokoroOnnxModel;
+}
+/** the tokenizer output we read: token count drives the style-vector slice. */
+interface KokoroInputIds {
+  dims: number[];
+}
+/** the @huggingface/transformers Tensor ctor (kokoro-js's own dep) — used to
+ *  wrap the summed style Float32Array as the model's `style` input. */
+type TensorCtor = new (type: 'float32', data: Float32Array | number[], dims: number[]) => unknown;
+/**
+ * Blend-spec identity version. Bump when the blend MATH or canonicalization
+ * changes in a way that can move synthesized bytes (independent of kokoro-js /
+ * model / dtype). Folds into kokoroProvider.version() → the segment cache key.
+ */
+declare const BLEND_SPEC_VERSION = "blend-1";
+/** Resolved, validated blend: normalized weights, in SPEC ORDER (preserved). */
+interface ResolvedBlend {
+  /** `[name, normalizedWeight]` in the author's spec order (NOT re-sorted). */
+  entries: readonly (readonly [string, number])[];
+  /** 'zh' (all zf_/zm_) or 'en' (all other / English) — the g2p front-end. */
+  language: 'zh' | 'en';
+}
+/**
+ * Validate + normalize a `VoiceBlend`: ≥2 entries, finite positive weights,
+ * weights NORMALIZED to sum to 1 (so `[["a",1],["b",1]]` = 50/50). The entry
+ * ORDER is PRESERVED from the spec (the weighted sum is commutative, so order
+ * does not affect the result — but a stable order keeps version() deterministic
+ * and the identity readable). Language is inferred from the base-voice prefixes:
+ * all `zf_`/`zm_` → 'zh'; all English → 'en'; a MIXED-language blend throws
+ * (different g2p front-ends can't be blended).
+ */
+declare function resolveBlend(spec: VoiceBlend): ResolvedBlend;
+/**
+ * The blend's cache identity — a PURE deterministic string (no async, no model
+ * load) folded into kokoroProvider.version(). Names are kept in spec order; the
+ * normalized weights are fixed-precision so float formatting never drifts the
+ * key. Any base voice or weight change moves this string → invalidates the
+ * segment cache, EXACTLY the 0.15 g2p-identity pattern.
+ */
+declare function blendIdentity(spec: VoiceBlend): string;
+/**
+ * Compute the normalized weighted sum of base-voice style tensors into one
+ * `[510 × 256]` Float32Array (the derived blended voice). Each loader returns a
+ * base voice's raw `[510 × 256]` float32 data; the weights are already
+ * normalized. Deterministic: a fixed pass over the spec-ordered entries, plain
+ * float adds. Validates every base tensor's length so a wrong-shape voice fails
+ * loudly rather than producing a silently-truncated blend.
+ */
+declare function blendStyleVectors(entries: readonly (readonly [string, number])[], loadVoice: (name: string) => Float32Array): Float32Array;
+/**
+ * Load a base voice's raw `[510×256]` float32 style tensor straight from the
+ * kokoro-js package's committed `voices/<name>.bin` (the same file kokoro-js
+ * reads internally for a named voice). Resolved relative to the kokoro-js entry
+ * (`<pkg>/dist/kokoro.* → ../voices/<name>.bin`), so the blend uses the SAME
+ * Apache-2.0 voice bytes the model was packaged with — no download, fully
+ * deterministic at prepare. A `.bin` whose size isn't 510×256×4 fails loudly.
+ */
+declare function loadKokoroVoiceData(entry: string, name: string): Float32Array;
+/**
+ * Drive a SUMMED style vector through the model — the blend analogue of
+ * generate_from_ids (which only accepts a NAMED voice it loads from disk). This
+ * replicates kokoro-js's exact style-slicing: row = min(max(tokenCount-2, 0),
+ * 509), style = blended[row*256 : row*256+256] → Tensor[1,256], then the same
+ * `model({input_ids, style, speed})` call. Deterministic: a fixed slice + the
+ * model's own forward pass (no sampling).
+ */
+declare function kokoroGenerateFromBlend(tts: KokoroModel, Tensor: TensorCtor, inputIds: KokoroInputIds, blended: Float32Array, speed: number): Promise<KokoroAudio>;
 /** 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;
+  voice?: VoiceSpec;
   dtype?: KokoroDtype;
   zhG2p?: ZhG2p;
 }): TtsProvider;
@@ -214,7 +322,7 @@ interface SynthesizeResult {
 }
 declare function cacheKey(seg: {
   text: string;
-  voice?: string;
+  voice?: VoiceSpec;
   rate?: number;
 }, provider: string, providerVersion: string): string;
 /**
@@ -226,4 +334,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, isKokoroChineseVoice, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };
+export { AlignRequest, Aligner, BLEND_SPEC_VERSION, KokoroDtype, ResolvedBlend, SynthesizeOptions, SynthesizeResult, TtsProvider, TtsRequest, TtsResult, VoskAlignWord, alignerById, blendIdentity, blendStyleVectors, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, isKokoroChineseVoice, kokoroGenerateFromBlend, kokoroProvider, loadKokoroVoiceData, mapAsrToScript, openaiProvider, piperProvider, providerById, requireStringVoice, resolveBlend, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };

package/dist/providers.js

@@ -1,4 +1,4 @@
-import { NarrationError, isPause } from "./index.js";
+import { NarrationError, isPause, isVoiceBlend } from "./index.js";
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
@@ -187,6 +187,16 @@ function wavDuration(wav) {
 	throw new NarrationError("WAV has no data chunk");
 }
 /**
+* Coerce a request voice to a plain NAME string for the providers that only
+* speak named voices (espeak / openai / piper). A `VoiceBlend` is kokoro-only,
+* so it is a clear authoring error to hand one to any other provider — throw
+* rather than silently stringify `[object Object]` into the request.
+*/
+function requireStringVoice(voice, provider) {
+	if (isVoiceBlend(voice)) throw new NarrationError(`provider '${provider}' does not support voice blends — only --provider kokoro can blend voices`);
+	return voice;
+}
+/**
 * A pure function of the request: a quiet tone whose duration models reading
 * speed (≈170 wpm + lead-out). Same text → identical bytes, every machine.
 */
@@ -243,8 +253,9 @@ function espeakProvider() {
 			return Promise.resolve(r.stdout.trim().split("\n")[0] ?? "espeak-ng");
 		},
 		synthesize: (req) => {
+			const voice = requireStringVoice(req.voice, "espeak");
 			const args = ["--stdout"];
-			if (req.voice) args.push("-v", req.voice);
+			if (voice) args.push("-v", voice);
 			args.push("-s", String(Math.round(175 * (req.rate ?? 1))));
 			args.push(req.text);
 			const r = spawnSync("espeak-ng", args, { maxBuffer: 64 * 1024 * 1024 });
@@ -263,6 +274,7 @@ function openaiProvider(opts = {}) {
 		id: "openai",
 		version: () => Promise.resolve(model),
 		synthesize: async (req) => {
+			const voice = requireStringVoice(req.voice, "openai");
 			const key = process.env["OPENAI_API_KEY"];
 			if (!key) throw new NarrationError("OPENAI_API_KEY is not set — required for --provider openai");
 			const res = await fetch("https://api.openai.com/v1/audio/speech", {
@@ -273,7 +285,7 @@ function openaiProvider(opts = {}) {
 				},
 				body: JSON.stringify({
 					model,
-					voice: req.voice ?? "alloy",
+					voice: voice ?? "alloy",
 					input: req.text,
 					response_format: "wav",
 					...req.rate !== void 0 ? { speed: req.rate } : {}
@@ -347,7 +359,7 @@ function piperProvider(opts = {}) {
 			].filter(Boolean).join(" "));
 		},
 		synthesize: (req) => {
-			const raw = req.voice ?? opts.model;
+			const raw = requireStringVoice(req.voice, "piper") ?? opts.model;
 			if (!raw) throw new NarrationError("piper needs a voice model (.onnx) — pass { model }, or set the segment voice to its path or name");
 			const model = resolvePiperVoice(raw, opts.voicesDir);
 			const tag = createHash("sha256").update(req.text).digest("hex").slice(0, 8);
@@ -406,6 +418,86 @@ function floatToWav(samples, sampleRate) {
 const KOKORO_MODEL = "onnx-community/Kokoro-82M-v1.0-ONNX";
 const KOKORO_DEFAULT_VOICE = "af_heart";
 /**
+* A kokoro voice style vector is a `[510 × 256]` float32 tensor (one 256-d
+* style row per phoneme-token-count bucket); a WEIGHTED SUM of two-or-more such
+* tensors is a valid custom voice (the HF "Make Custom Voices With KokoroTTS"
+* recipe). Both base voices are Apache-2.0, so the derived blend is a derived
+* Apache-2.0 voice (provenance is surfaced in the synth log + folded into
+* version() so the artifact is auditable). The blend is computed ONCE at
+* prepare and driven through the model directly (generate_from_ids only accepts
+* a NAMED voice it loads from disk — a blend has no registered name).
+*/
+const KOKORO_VOICE_ROWS = 510;
+const KOKORO_STYLE_DIM = 256;
+const KOKORO_VOICE_FLOATS = KOKORO_VOICE_ROWS * KOKORO_STYLE_DIM;
+/**
+* Blend-spec identity version. Bump when the blend MATH or canonicalization
+* changes in a way that can move synthesized bytes (independent of kokoro-js /
+* model / dtype). Folds into kokoroProvider.version() → the segment cache key.
+*/
+const BLEND_SPEC_VERSION = "blend-1";
+/**
+* Validate + normalize a `VoiceBlend`: ≥2 entries, finite positive weights,
+* weights NORMALIZED to sum to 1 (so `[["a",1],["b",1]]` = 50/50). The entry
+* ORDER is PRESERVED from the spec (the weighted sum is commutative, so order
+* does not affect the result — but a stable order keeps version() deterministic
+* and the identity readable). Language is inferred from the base-voice prefixes:
+* all `zf_`/`zm_` → 'zh'; all English → 'en'; a MIXED-language blend throws
+* (different g2p front-ends can't be blended).
+*/
+function resolveBlend(spec) {
+	const raw = spec.blend;
+	if (!Array.isArray(raw) || raw.length < 2) throw new NarrationError(`voice blend needs ≥2 base voices (got ${Array.isArray(raw) ? raw.length : "none"})`);
+	let sum = 0;
+	for (const entry of raw) {
+		if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || typeof entry[1] !== "number") throw new NarrationError(`voice blend entries must be ["<voice>", <weight>]; got ${JSON.stringify(entry)}`);
+		const [name, weight] = entry;
+		if (!name) throw new NarrationError("voice blend entry has an empty voice name");
+		if (!Number.isFinite(weight) || weight <= 0) throw new NarrationError(`voice blend weight for '${name}' must be a finite number > 0 (got ${weight})`);
+		sum += weight;
+	}
+	const chinese = raw.map(([name]) => isKokoroChineseVoice(name));
+	const allZh = chinese.every(Boolean);
+	const allEn = chinese.every((c) => !c);
+	if (!allZh && !allEn) {
+		const zh = raw.filter((_, i) => chinese[i]).map(([n]) => n);
+		const en = raw.filter((_, i) => !chinese[i]).map(([n]) => n);
+		throw new NarrationError(`voice blend mixes languages — Chinese [${zh.join(", ")}] with non-Chinese [${en.join(", ")}]; a blend must share one g2p front-end (all zf_/zm_ OR all English)`);
+	}
+	return {
+		entries: raw.map(([name, weight]) => [name, weight / sum]),
+		language: allZh ? "zh" : "en"
+	};
+}
+/**
+* The blend's cache identity — a PURE deterministic string (no async, no model
+* load) folded into kokoroProvider.version(). Names are kept in spec order; the
+* normalized weights are fixed-precision so float formatting never drifts the
+* key. Any base voice or weight change moves this string → invalidates the
+* segment cache, EXACTLY the 0.15 g2p-identity pattern.
+*/
+function blendIdentity(spec) {
+	const { entries, language } = resolveBlend(spec);
+	return `blend=[${entries.map(([name, w]) => `${name}:${w.toFixed(6)}`).join(",")} lang=${language} v${BLEND_SPEC_VERSION}]`;
+}
+/**
+* Compute the normalized weighted sum of base-voice style tensors into one
+* `[510 × 256]` Float32Array (the derived blended voice). Each loader returns a
+* base voice's raw `[510 × 256]` float32 data; the weights are already
+* normalized. Deterministic: a fixed pass over the spec-ordered entries, plain
+* float adds. Validates every base tensor's length so a wrong-shape voice fails
+* loudly rather than producing a silently-truncated blend.
+*/
+function blendStyleVectors(entries, loadVoice) {
+	const out = new Float32Array(KOKORO_VOICE_FLOATS);
+	for (const [name, weight] of entries) {
+		const vec = loadVoice(name);
+		if (vec.length !== KOKORO_VOICE_FLOATS) throw new NarrationError(`kokoro voice '${name}' has ${vec.length} floats, expected ${KOKORO_VOICE_FLOATS} (${KOKORO_VOICE_ROWS}×${KOKORO_STYLE_DIM}) — not a valid style vector`);
+		for (let i = 0; i < KOKORO_VOICE_FLOATS; i++) out[i] += vec[i] * weight;
+	}
+	return out;
+}
+/**
 * 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
@@ -449,6 +541,7 @@ function resolveKokoro() {
 	for (const base of bases) try {
 		const entry = createRequire(base).resolve("kokoro-js");
 		return {
+			entry,
 			entryUrl: pathToFileURL(entry).href,
 			version: kokoroVersionFrom(entry)
 		};
@@ -457,6 +550,61 @@ 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`);
 }
+/**
+* Load a base voice's raw `[510×256]` float32 style tensor straight from the
+* kokoro-js package's committed `voices/<name>.bin` (the same file kokoro-js
+* reads internally for a named voice). Resolved relative to the kokoro-js entry
+* (`<pkg>/dist/kokoro.* → ../voices/<name>.bin`), so the blend uses the SAME
+* Apache-2.0 voice bytes the model was packaged with — no download, fully
+* deterministic at prepare. A `.bin` whose size isn't 510×256×4 fails loudly.
+*/
+function loadKokoroVoiceData(entry, name) {
+	const path = resolve(dirname(entry), "..", "voices", `${name}.bin`);
+	if (!existsSync(path)) throw new NarrationError(`kokoro voice '${name}' not found at ${path} — blend base voices must be kokoro built-in voices (e.g. zf_xiaoni, zf_xiaoxiao)`);
+	const buf = readFileSync(path);
+	if (buf.byteLength !== KOKORO_VOICE_FLOATS * 4) throw new NarrationError(`kokoro voice '${name}' is ${buf.byteLength} bytes, expected ${KOKORO_VOICE_FLOATS * 4} (${KOKORO_VOICE_ROWS}×${KOKORO_STYLE_DIM} float32)`);
+	return new Float32Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength));
+}
+/** Resolve the @huggingface/transformers `Tensor` ctor (kokoro-js's own dep) —
+*  used to wrap the summed style vector as the model's `style` input. Resolved
+*  RELATIVE to the kokoro-js entry so we get the exact version kokoro-js uses. */
+async function loadTensorCtor(entry) {
+	const req = createRequire(pathToFileURL(entry).href);
+	let resolved;
+	try {
+		resolved = req.resolve("@huggingface/transformers");
+	} catch (e) {
+		const err = e;
+		throw new NarrationError(`@huggingface/transformers could not be resolved from kokoro-js (${err?.code ?? "error"}: ${err?.message ?? "not found"}) — it is a kokoro-js dependency; reinstall kokoro-js, or use a single (non-blended) voice`);
+	}
+	const mod = await import(pathToFileURL(resolved).href);
+	const Tensor = mod["Tensor"] ?? mod["default"]?.["Tensor"];
+	if (!Tensor) throw new NarrationError("@huggingface/transformers loaded but exposes no Tensor export");
+	return Tensor;
+}
+/**
+* Drive a SUMMED style vector through the model — the blend analogue of
+* generate_from_ids (which only accepts a NAMED voice it loads from disk). This
+* replicates kokoro-js's exact style-slicing: row = min(max(tokenCount-2, 0),
+* 509), style = blended[row*256 : row*256+256] → Tensor[1,256], then the same
+* `model({input_ids, style, speed})` call. Deterministic: a fixed slice + the
+* model's own forward pass (no sampling).
+*/
+async function kokoroGenerateFromBlend(tts, Tensor, inputIds, blended, speed) {
+	const tokens = inputIds.dims.at(-1) ?? 0;
+	const row = Math.min(Math.max(tokens - 2, 0), KOKORO_VOICE_ROWS - 1);
+	const styleTensor = new Tensor("float32", blended.slice(row * KOKORO_STYLE_DIM, row * KOKORO_STYLE_DIM + KOKORO_STYLE_DIM), [1, KOKORO_STYLE_DIM]);
+	const speedTensor = new Tensor("float32", [speed], [1]);
+	const { waveform } = await tts.model({
+		input_ids: inputIds,
+		style: styleTensor,
+		speed: speedTensor
+	});
+	return {
+		audio: waveform.data,
+		sampling_rate: 24e3
+	};
+}
 /** A z* (zf_/zm_) kokoro voice routes through misaki[zh] g2p (not espeak cmn). */
 function isKokoroChineseVoice(voice) {
 	return voice.startsWith("zf_") || voice.startsWith("zm_");
@@ -467,7 +615,7 @@ function kokoroProvider(opts = {}) {
 	const zhG2p = opts.zhG2p ?? misakiZhG2p();
 	let loaded = null;
 	const loadLib = async () => {
-		const { entryUrl } = resolveKokoro();
+		const { entry, entryUrl } = resolveKokoro();
 		let mod;
 		try {
 			mod = await import(entryUrl);
@@ -477,22 +625,53 @@ function kokoroProvider(opts = {}) {
 		}
 		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;
+		return {
+			lib,
+			entry
+		};
 	};
-	const getModel = () => loaded ??= loadLib().then((k) => k.KokoroTTS.from_pretrained(modelId, {
-		dtype,
-		device: "cpu"
+	const getModel = () => loaded ??= loadLib().then(async ({ lib, entry }) => ({
+		tts: await lib.KokoroTTS.from_pretrained(modelId, {
+			dtype,
+			device: "cpu"
+		}),
+		entry
 	}));
 	return {
 		id: "kokoro",
 		version: () => {
 			const { version } = resolveKokoro();
-			const v = `kokoro-js ${version} ${basename(modelId)} dtype=${dtype} g2p=[${zhG2p.version()}]`;
+			const blendSuffix = isVoiceBlend(opts.voice) ? ` ${blendIdentity(opts.voice)}` : "";
+			const v = `kokoro-js ${version} ${basename(modelId)} dtype=${dtype} g2p=[${zhG2p.version()}]${blendSuffix}`;
 			return Promise.resolve(v);
 		},
 		synthesize: async (req) => {
 			const voice = req.voice ?? opts.voice ?? KOKORO_DEFAULT_VOICE;
 			const speed = req.rate !== void 0 && req.rate > 0 ? req.rate : void 0;
+			if (isVoiceBlend(voice)) {
+				const resolved = resolveBlend(voice);
+				const { tts, entry } = await getModel();
+				const blended = blendStyleVectors(resolved.entries, (name) => loadKokoroVoiceData(entry, name));
+				const Tensor = await loadTensorCtor(entry);
+				const recipe = resolved.entries.map(([n, w]) => `${n}*${w.toFixed(4)}`).join(" + ");
+				console.log(`[narrate] kokoro blended voice (Apache-2.0, derived) lang=${resolved.language}: ${recipe}`);
+				let inputIds;
+				try {
+					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");
+					const audio = await kokoroGenerateFromBlend(tts, Tensor, inputIds, blended, speed ?? 1);
+					const wav = floatToWav(audio.audio, audio.sampling_rate);
+					return {
+						wav,
+						duration: wavDuration(wav)
+					};
+				} catch (e) {
+					if (e instanceof NarrationError) throw e;
+					throw new NarrationError(`kokoro blended synthesis failed: ${e instanceof Error ? e.message : String(e)}`);
+				}
+			}
 			const genOpts = speed !== void 0 ? {
 				voice,
 				speed
@@ -500,7 +679,7 @@ function kokoroProvider(opts = {}) {
 			let audio;
 			if (isKokoroChineseVoice(voice)) {
 				const phonemes = zhG2p.phonemize(req.text);
-				const tts = await getModel();
+				const { tts } = await getModel();
 				try {
 					const { input_ids } = tts.tokenizer(phonemes, { truncation: true });
 					audio = await tts.generate_from_ids(input_ids, genOpts);
@@ -508,7 +687,7 @@ function kokoroProvider(opts = {}) {
 					throw new NarrationError(`kokoro Chinese synthesis failed: ${e instanceof Error ? e.message : String(e)}`);
 				}
 			} else {
-				const tts = await getModel();
+				const { tts } = await getModel();
 				try {
 					audio = await tts.generate(req.text, genOpts);
 				} catch (e) {
@@ -704,10 +883,22 @@ function alignerById(id) {
 		default: throw new NarrationError(`unknown aligner '${id}' (have: heuristic, vosk, none)`);
 	}
 }
+/**
+* Canonicalize a voice for the cache key. A plain string is itself; a BLEND
+* spec collapses to its `blendIdentity()` — normalized weights + language +
+* `BLEND_SPEC_VERSION`. This is what folds the blend into the cache key on the
+* real CLI path (where the blend is a per-REQUEST voice and the provider is
+* built with no opts): any weight / base-voice / spec-version change moves the
+* identity → re-synthesizes; the same blend (even re-serialized) stays stable.
+*/
+function voiceCacheIdentity(voice) {
+	if (voice === void 0) return null;
+	return isVoiceBlend(voice) ? blendIdentity(voice) : voice;
+}
 function cacheKey(seg, provider, providerVersion) {
 	return createHash("sha256").update(JSON.stringify({
 		text: seg.text,
-		voice: seg.voice ?? null,
+		voice: voiceCacheIdentity(seg.voice),
 		rate: seg.rate ?? 1,
 		provider,
 		providerVersion
@@ -861,4 +1052,4 @@ function scriptPathFor(input) {
 	return candidate;
 }
 //#endregion
-export { alignerById, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, isKokoroChineseVoice, kokoroProvider, mapAsrToScript, openaiProvider, piperProvider, providerById, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };
+export { BLEND_SPEC_VERSION, alignerById, blendIdentity, blendStyleVectors, cacheKey, espeakProvider, fakeProvider, floatToWav, heuristicAligner, heuristicWords, interpolateMissing, isKokoroChineseVoice, kokoroGenerateFromBlend, kokoroProvider, loadKokoroVoiceData, mapAsrToScript, openaiProvider, piperProvider, providerById, requireStringVoice, resolveBlend, resolvePiperVoice, scriptPathFor, stderrTail, synthesizeScript, voskAligner, wavDuration };

package/package.json

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