@glissade/cli 0.4.3 → 0.4.5

package/dist/cli.js

@@ -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
+  --music <m>      auto (default): mix a sibling *.music.timing.json bed, ducked under narration | off
 
 dev options:
   --record         add a Record button; writes .trace.json sidecars next to the module
@@ -135,6 +136,7 @@ async function main() {
 			...flags.has("state") ? { state: flags.get("state") } : {},
 			...flags.has("force") ? { force: true } : {},
 			captions: parseCaptionsModeOrFail(flags.get("captions")),
+			music: flags.get("music") === "off" ? "off" : "auto",
 			onProgress: (n, total) => {
 				if (process.stderr.isTTY) {
 					if (n % 30 === 0 || n === total) process.stderr.write(`\rrendering ${n}/${total} frames`);

package/dist/index.d.ts

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

package/dist/music.js

@@ -0,0 +1,55 @@
+import { o as resolveAssetPath } from "./audioMix.js";
+import { existsSync, readFileSync } from "node:fs";
+import { music, 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.
+*/
+/** `<module>.music.timing.json`, when the scene has a music bed. */
+function musicPathFor(modulePath) {
+	const candidate = modulePath.replace(/\.[jt]sx?$/, "") + ".music.timing.json";
+	return existsSync(candidate) ? candidate : null;
+}
+/**
+* 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.
+*/
+function buildMusicClip(musicManifestPath, narrationTimingPath) {
+	const timing = JSON.parse(readFileSync(musicManifestPath, "utf8"));
+	validateMusicTiming(timing);
+	if (!timing.stem) return null;
+	const anchors = music(timing);
+	if (narrationTimingPath) {
+		const narration = JSON.parse(readFileSync(narrationTimingPath, "utf8"));
+		return {
+			clip: anchors.clip(void 0, { duckUnder: narration }),
+			note: `music bed '${timing.stem}'${timing.gainDb ? ` at ${timing.gainDb}dB` : ""}, ducked under narration`
+		};
+	}
+	return {
+		clip: anchors.clip(),
+		note: `music bed '${timing.stem}'${timing.gainDb ? ` at ${timing.gainDb}dB` : ""}`
+	};
+}
+/**
+* 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).
+*/
+function bedAlreadyReferenced(clips, bedUrl, modulePath) {
+	const bedPath = resolveAssetPath(bedUrl, modulePath);
+	return clips.some((c) => {
+		try {
+			return resolveAssetPath(c.asset.url, modulePath) === bedPath;
+		} catch {
+			return false;
+		}
+	});
+}
+//#endregion
+export { bedAlreadyReferenced, buildMusicClip, musicPathFor };

package/dist/render.js

@@ -130,8 +130,21 @@ async function render(opts) {
 			"+faststart"
 		]
 	];
+	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 { planAudioMix } = await import("./audioMix.js").then((n) => n.r);
-	const mix = planAudioMix(compiled.audio, opts.modulePath, duration);
+	const mix = planAudioMix(audioClips, opts.modulePath, duration);
 	if (mix?.hasEasedGain) process.stderr.write("note: eased gain keys are approximated linearly in the FFmpeg mix\n");
 	const audioInputs = mix ? mix.inputs.flatMap((p) => ["-i", p]) : [];
 	const audioEnc = mix ? pickEncoder("audio", container) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glissade/cli",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "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.3",
-    "@glissade/core": "0.4.3",
-    "@glissade/interact": "0.4.3",
-    "@glissade/lottie": "0.4.3",
-    "@glissade/narrate": "0.4.3",
-    "@glissade/player": "0.4.3",
-    "@glissade/scene": "0.4.3"
+    "@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"
   },
   "repository": {
     "type": "git",