@glissade/cli 0.4.5 → 0.5.0-pre.0

package/dist/cli.js

@@ -43,7 +43,7 @@ const USAGE = `usage:
   gs render <scene-module> [options]
   gs dev <scene-module> [--record] [--port <n>]
   gs import <lottie.json> [--out <dir>] [--allow-degraded]
-  gs narrate <scene-module|script.narration.json> [--provider <id>] [--force]
+  gs narrate <scene-module|script.narration.json> [--provider <id>] [--align <id>] [--force]
 
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
@@ -53,6 +53,7 @@ render options:
   --state <name>   render one machine state's timeline linearly
   --force          downgrade a trace hash mismatch to a warning
   --captions <m>   burn (default) | sidecar | off; burn/sidecar also write .srt/.vtt
+  --narration <m>  auto (default): mix the voice from a sibling *.narration.timing.json | off
   --music <m>      auto (default): mix a sibling *.music.timing.json bed, ducked under narration | off
 
 dev options:
@@ -64,7 +65,8 @@ import options:
   --allow-degraded     downgrade degradable rejections (expressions, merge-paths modes != 1) to warnings
 
 narrate options (the explicit TTS prepare step; render itself stays offline):
-  --provider <id>  fake | espeak | openai (default: the script's provider, else espeak)
+  --provider <id>  fake | espeak | piper | openai (default: the script's provider, else espeak)
+  --align <id>     heuristic (default) | vosk | none — word timings for providers that emit none
   --force          ignore the cache and re-synthesize every segment
 `;
 async function main() {
@@ -82,9 +84,14 @@ async function main() {
 			const result = await narrateCommand({
 				input: modulePath,
 				...flags.has("provider") ? { provider: flags.get("provider") } : {},
+				...flags.has("align") ? { aligner: flags.get("align") } : {},
 				...flags.has("force") ? { force: true } : {}
 			});
-			const parts = [result.synthesized.length > 0 ? `synthesized ${result.synthesized.join(", ")}` : null, result.reused.length > 0 ? `reused ${result.reused.length} cached` : null].filter(Boolean);
+			const parts = [
+				result.synthesized.length > 0 ? `synthesized ${result.synthesized.join(", ")}` : null,
+				result.reused.length > 0 ? `reused ${result.reused.length} cached` : null,
+				result.aligned.length > 0 ? `aligned ${result.aligned.length} via ${result.aligner}` : null
+			].filter(Boolean);
 			process.stderr.write(`gs narrate: ${parts.join("; ") || "nothing to do"} → ${result.timingPath}\n`);
 		} catch (err) {
 			fail(err instanceof Error ? err.message : String(err));
@@ -136,6 +143,7 @@ async function main() {
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},
 			captions: parseCaptionsModeOrFail(flags.get("captions")),
+			narration: flags.get("narration") === "off" ? "off" : "auto",
 			music: flags.get("music") === "off" ? "off" : "auto",
 			onProgress: (n, total) => {
 				if (process.stderr.isTTY) {

package/dist/index.d.ts

@@ -20,6 +20,8 @@ interface RenderOptions {
   captions?: 'burn' | 'sidecar' | 'off';
   /** auto (default): mix a sibling *.music.timing.json bed, ducked under narration. */
   music?: 'auto' | 'off';
+  /** auto (default): mix the voice from a sibling *.narration.timing.json. */
+  narration?: 'auto' | 'off';
   onProgress?: (frame: number, total: number) => void;
 }
 declare class SceneModuleError extends Error {

package/dist/music.js

@@ -1,13 +1,15 @@
 import { o as resolveAssetPath } from "./audioMix.js";
 import { existsSync, readFileSync } from "node:fs";
-import { music, validateMusicTiming } from "@glissade/narrate";
+import { basename } from "node:path";
+import { music, narration, validateMusicTiming } from "@glissade/narrate";
 //#region src/music.ts
 /**
-* Render-time music auto-mix (the narration parity): a committed
-* `<module>.music.timing.json` with a `stem` field next to the scene mixes
-* its bed automatically — and when a narration timing manifest ALSO sits
-* there, the bed auto-ducks under the voice. Zero-config
-* narrated-explainer-with-bed; everything derives from the two manifests.
+* Render-time audio auto-mix. Sibling manifests next to a scene join the
+* timeline mix automatically: the NARRATION voice (`*.narration.timing.json`)
+* and the MUSIC bed (`*.music.timing.json` with a `stem`), the bed
+* auto-ducked under the voice. Scene + manifests → finished mp4, no
+* hand-wired `timeline.audio`. Author-wired clips are detected and not
+* doubled.
 */
 /** `<module>.music.timing.json`, when the scene has a music bed. */
 function musicPathFor(modulePath) {
@@ -15,6 +17,24 @@ function musicPathFor(modulePath) {
 	return existsSync(candidate) ? candidate : null;
 }
 /**
+* Build the narration voice clips from a sibling timing manifest — the half
+* of audio auto-mix that 0.4.x's "music parity" was missing (music mixed,
+* narration didn't). Clip urls stay relative to the cache dir, which sits
+* next to the manifest (and the module), so the mixer resolves them against
+* the module dir.
+*/
+function buildNarrationClips(timingPath) {
+	const timing = JSON.parse(readFileSync(timingPath, "utf8"));
+	if (!timing.segments || timing.segments.length === 0) return null;
+	const cacheBase = basename(timingPath).replace(/\.narration\.timing\.json$/, "") + ".narration-cache";
+	const clips = narration(timing).clips(cacheBase);
+	const n = timing.segments.length;
+	return {
+		clips,
+		note: `narration (${n} ${n === 1 ? "segment" : "segments"})`
+	};
+}
+/**
 * Build the bed clip from the manifests. The stem path stays relative — the
 * manifest sits next to the module, and the mixer resolves clip urls against
 * the module dir, so the bases coincide.
@@ -37,19 +57,20 @@ function buildMusicClip(musicManifestPath, narrationTimingPath) {
 	};
 }
 /**
-* True when the timeline's audio already references the bed stem (same
-* resolved file) — auto-mix must then SKIP, or the bed plays twice and adds
-* +6dB of coherent doubling (measured downstream before this guard existed).
+* True when the timeline's audio already references a file (same resolved
+* path) — auto-mix must then SKIP it, or the source plays twice: a coherent
+* duplicate adds +6dB (measured downstream before this guard existed).
+* Used for both the bed and the narration clips.
 */
-function bedAlreadyReferenced(clips, bedUrl, modulePath) {
-	const bedPath = resolveAssetPath(bedUrl, modulePath);
+function bedAlreadyReferenced(clips, url, modulePath) {
+	const target = resolveAssetPath(url, modulePath);
 	return clips.some((c) => {
 		try {
-			return resolveAssetPath(c.asset.url, modulePath) === bedPath;
+			return resolveAssetPath(c.asset.url, modulePath) === target;
 		} catch {
 			return false;
 		}
 	});
 }
 //#endregion
-export { bedAlreadyReferenced, buildMusicClip, musicPathFor };
+export { bedAlreadyReferenced, buildMusicClip, buildNarrationClips, musicPathFor };

package/dist/narrate.js

@@ -8,12 +8,15 @@ import { scriptPathFor, synthesizeScript } from "@glissade/narrate/providers";
 async function narrateCommand(opts) {
 	const result = await synthesizeScript(scriptPathFor(opts.input), {
 		...opts.provider !== void 0 ? { provider: opts.provider } : {},
+		...opts.aligner !== void 0 ? { aligner: opts.aligner } : {},
 		...opts.force !== void 0 ? { force: opts.force } : {}
 	});
 	return {
 		timingPath: result.timingPath,
 		synthesized: result.synthesized,
-		reused: result.reused
+		reused: result.reused,
+		aligned: result.aligned,
+		aligner: result.aligner
 	};
 }
 //#endregion

package/dist/render.js

@@ -131,15 +131,28 @@ async function render(opts) {
 		]
 	];
 	const audioClips = [...compiled.audio];
-	if ((opts.music ?? "auto") === "auto") {
-		const { bedAlreadyReferenced, buildMusicClip, musicPathFor } = await import("./music.js");
-		const musicPath = musicPathFor(opts.modulePath);
-		if (musicPath) {
-			const bed = buildMusicClip(musicPath, timingPathFor(opts.modulePath));
-			if (bed) if (bedAlreadyReferenced(audioClips, bed.clip.asset.url, opts.modulePath)) process.stderr.write("note: music bed already in the timeline audio — auto-mix skipped\n");
-			else {
-				audioClips.push(bed.clip);
-				process.stderr.write(`note: auto-mixing ${bed.note}\n`);
+	{
+		const { bedAlreadyReferenced, buildMusicClip, buildNarrationClips, musicPathFor } = await import("./music.js");
+		if ((opts.narration ?? "auto") === "auto") {
+			const narrationPath = timingPathFor(opts.modulePath);
+			if (narrationPath) {
+				const voice = buildNarrationClips(narrationPath);
+				if (voice) if (voice.clips.some((c) => bedAlreadyReferenced(audioClips, c.asset.url, opts.modulePath))) process.stderr.write("note: narration already in the timeline audio — auto-mix skipped\n");
+				else {
+					audioClips.push(...voice.clips);
+					process.stderr.write(`note: auto-mixing ${voice.note}\n`);
+				}
+			}
+		}
+		if ((opts.music ?? "auto") === "auto") {
+			const musicPath = musicPathFor(opts.modulePath);
+			if (musicPath) {
+				const bed = buildMusicClip(musicPath, timingPathFor(opts.modulePath));
+				if (bed) if (bedAlreadyReferenced(audioClips, bed.clip.asset.url, opts.modulePath)) process.stderr.write("note: music bed already in the timeline audio — auto-mix skipped\n");
+				else {
+					audioClips.push(bed.clip);
+					process.stderr.write(`note: auto-mixing ${bed.note}\n`);
+				}
 			}
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.4.5",
+  "version": "0.5.0-pre.0",
   "description": "glissade CLI: headless rendering via backend-skia (+ FFmpeg mux).",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,13 +20,13 @@
     "@napi-rs/canvas": "^0.1.65",
     "esbuild": "^0.28.0",
     "jiti": "^2.4.2",
-    "@glissade/backend-skia": "0.4.5",
-    "@glissade/core": "0.4.5",
-    "@glissade/interact": "0.4.5",
-    "@glissade/lottie": "0.4.5",
-    "@glissade/narrate": "0.4.5",
-    "@glissade/player": "0.4.5",
-    "@glissade/scene": "0.4.5"
+    "@glissade/backend-skia": "0.5.0-pre.0",
+    "@glissade/core": "0.5.0-pre.0",
+    "@glissade/interact": "0.5.0-pre.0",
+    "@glissade/lottie": "0.5.0-pre.0",
+    "@glissade/narrate": "0.5.0-pre.0",
+    "@glissade/player": "0.5.0-pre.0",
+    "@glissade/scene": "0.5.0-pre.0"
   },
   "repository": {
     "type": "git",