@glissade/cli 0.5.0-pre.1 → 0.5.0-pre.2

package/dist/cli.js

@@ -44,6 +44,7 @@ const USAGE = `usage:
   gs dev <scene-module> [--record] [--port <n>]
   gs import <lottie.json> [--out <dir>] [--allow-degraded]
   gs narrate <scene-module|script.narration.json> [--provider <id>] [--align <id>] [--force]
+  gs sfx <scene-module|script.sfx.json>
 
 render options:
   --out <path>     output directory for a PNG sequence, or .mp4/.webm (needs ffmpeg). default: ./out
@@ -55,6 +56,7 @@ render options:
   --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
+  --sfx <m>        auto (default): mix effect hits from a sibling *.sfx.timing.json | off
 
 dev options:
   --record         add a Record button; writes .trace.json sidecars next to the module
@@ -71,7 +73,7 @@ narrate options (the explicit TTS prepare step; render itself stays offline):
 `;
 async function main() {
 	const [command, ...rest] = process.argv.slice(2);
-	if (command !== "render" && command !== "dev" && command !== "import" && command !== "narrate") {
+	if (command !== "render" && command !== "dev" && command !== "import" && command !== "narrate" && command !== "sfx") {
 		console.error(USAGE);
 		process.exit(command === void 0 || command === "help" || command === "--help" ? 0 : 1);
 	}
@@ -98,6 +100,16 @@ async function main() {
 		}
 		return;
 	}
+	if (command === "sfx") {
+		const { prepareSfx, sfxScriptPathFor } = await import("./sfx.js");
+		try {
+			const result = prepareSfx(sfxScriptPathFor(modulePath));
+			process.stderr.write(`gs sfx: ${result.clipCount} ${result.clipCount === 1 ? "hit" : "hits"}, ${result.voices.length} ${result.voices.length === 1 ? "voice" : "voices"} rendered → ${result.timingPath}\n`);
+		} catch (err) {
+			fail(err instanceof Error ? err.message : String(err));
+		}
+		return;
+	}
 	if (command === "import") {
 		const { importCommand } = await import("./import.js").then((n) => n.n);
 		try {
@@ -145,6 +157,7 @@ async function main() {
 			captions: parseCaptionsModeOrFail(flags.get("captions")),
 			narration: flags.get("narration") === "off" ? "off" : "auto",
 			music: flags.get("music") === "off" ? "off" : "auto",
+			sfx: flags.get("sfx") === "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

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

package/dist/render.js

@@ -155,6 +155,18 @@ async function render(opts) {
 				}
 			}
 		}
+		if ((opts.sfx ?? "auto") === "auto") {
+			const { buildSfxClipsFromTiming, sfxTimingPathFor } = await import("./sfx.js");
+			const sfxPath = sfxTimingPathFor(opts.modulePath);
+			if (sfxPath) {
+				const fx = buildSfxClipsFromTiming(sfxPath);
+				if (fx) if (fx.clips.some((c) => bedAlreadyReferenced(audioClips, c.asset.url, opts.modulePath))) process.stderr.write("note: sfx already in the timeline audio — auto-mix skipped\n");
+				else {
+					audioClips.push(...fx.clips);
+					process.stderr.write(`note: auto-mixing ${fx.note}\n`);
+				}
+			}
+		}
 	}
 	const { planAudioMix } = await import("./audioMix.js").then((n) => n.r);
 	const mix = planAudioMix(audioClips, opts.modulePath, duration);

package/dist/sfx.js

@@ -0,0 +1,125 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { narration } from "@glissade/narrate";
+import { buildSfxClips, renderSfxAssets, sfxFileName, sfxrSource } from "@glissade/sfx";
+//#region src/sfx.ts
+/**
+* gs sfx — the explicit sound-effects prepare step, and the render-time
+* auto-mix half. Like narration, synthesis happens HERE: the prepare step
+* resolves each hit's time (absolute, or anchored to a narration beat so it
+* re-flows on re-narrate), renders the referenced voices to a committed WAV
+* cache (deduped), applies deterministic index-seeded pitch/gain variation, and
+* writes a committed `<base>.sfx.timing.json`. gs render consumes that manifest,
+* fully offline — a sibling next to the scene joins the mix with zero config.
+*/
+var SfxCliError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SfxCliError";
+	}
+};
+/** `<scene>.sfx.json` for a scene module, or the script path itself. */
+function sfxScriptPathFor(input) {
+	if (input.endsWith(".sfx.json")) return input;
+	const candidate = input.replace(/\.[jt]sx?$/, "") + ".sfx.json";
+	if (!existsSync(candidate)) throw new SfxCliError(`no sfx script at ${candidate} — create it or pass the script path directly`);
+	return candidate;
+}
+/** `<module>.sfx.timing.json`, when the scene has effects. */
+function sfxTimingPathFor(modulePath) {
+	const candidate = modulePath.replace(/\.[jt]sx?$/, "") + ".sfx.timing.json";
+	return existsSync(candidate) ? candidate : null;
+}
+/**
+* Resolve, render, and commit a scene's sound effects. Anchored hits are
+* resolved against the sibling `<base>.narration.timing.json`; absolute hits
+* use their `at`. The referenced voices render once each (deduped) to
+* `<base>.sfx-cache/`, and the index-seeded jitter is baked into the committed
+* clip list — so render is a pure read of the manifest.
+*/
+function prepareSfx(scriptPath) {
+	if (!scriptPath.endsWith(".sfx.json")) throw new SfxCliError(`script path must end with .sfx.json: ${scriptPath}`);
+	const raw = JSON.parse(readFileSync(scriptPath, "utf8"));
+	if (raw.sfxVersion !== 1) throw new SfxCliError(`unsupported sfxVersion ${String(raw.sfxVersion)}`);
+	if ((raw.source ?? "sfxr") !== "sfxr") throw new SfxCliError(`gs sfx v1 supports source 'sfxr' only; use buildSfxClips() in code for sample packs`);
+	const source = sfxrSource(raw.sampleRate !== void 0 ? { sampleRate: raw.sampleRate } : {});
+	const validVoices = new Set(source.voices().map((v) => v.id));
+	const base = scriptPath.replace(/\.sfx\.json$/, "");
+	const narrationPath = `${base}.narration.timing.json`;
+	let beats = null;
+	const loadBeats = () => {
+		if (beats) return beats;
+		if (!existsSync(narrationPath)) throw new SfxCliError(`hit anchors a narration beat but no ${basename(narrationPath)} found — run gs narrate first`);
+		beats = narration(JSON.parse(readFileSync(narrationPath, "utf8")));
+		return beats;
+	};
+	const hits = raw.hits.map((h, i) => {
+		if (!validVoices.has(h.voice)) throw new SfxCliError(`hit ${i}: unknown voice '${h.voice}' (have: ${[...validVoices].join(", ")})`);
+		const hasAnchor = h.anchor !== void 0;
+		if (hasAnchor === (h.at !== void 0)) throw new SfxCliError(`hit ${i} ('${h.voice}') needs exactly one of 'anchor' or 'at'`);
+		const at = hasAnchor ? loadBeats().at(h.anchor, h.offset ?? 0) : h.at;
+		return {
+			voice: h.voice,
+			at,
+			...h.gain !== void 0 ? { gain: h.gain } : {}
+		};
+	});
+	const timedClips = buildSfxClips(hits, source, {
+		seed: raw.seed ?? 0,
+		...raw.jitterRate !== void 0 ? { jitterRate: raw.jitterRate } : {},
+		...raw.jitterGain !== void 0 ? { jitterGain: raw.jitterGain } : {},
+		...raw.gain !== void 0 ? { gain: raw.gain } : {}
+	}).map((c, i) => ({
+		voice: hits[i].voice,
+		at: c.at,
+		file: sfxFileName(source.id, hits[i].voice),
+		...c.gain ? { gain: c.gain.keys[0].value } : {},
+		...c.playbackRate !== void 0 ? { playbackRate: c.playbackRate } : {}
+	}));
+	const cacheDir = `${base}.sfx-cache`;
+	mkdirSync(cacheDir, { recursive: true });
+	const assets = renderSfxAssets(source, hits.map((h) => h.voice));
+	for (const [file, bytes] of Object.entries(assets)) writeFileSync(join(cacheDir, file), bytes);
+	const timing = {
+		sfxTimingVersion: 1,
+		source: source.id,
+		clips: timedClips
+	};
+	const timingPath = `${base}.sfx.timing.json`;
+	writeFileSync(timingPath, JSON.stringify(timing, null, 2) + "\n");
+	return {
+		timingPath,
+		cacheDir,
+		voices: Object.keys(assets),
+		clipCount: timedClips.length
+	};
+}
+/**
+* Build the effect clips from a sibling timing manifest for render auto-mix.
+* Clip urls stay relative to the cache dir next to the manifest, so the mixer
+* resolves them against the module dir (mirrors buildNarrationClips).
+*/
+function buildSfxClipsFromTiming(timingPath) {
+	const timing = JSON.parse(readFileSync(timingPath, "utf8"));
+	if (!timing.clips || timing.clips.length === 0) return null;
+	const cacheBase = basename(timingPath).replace(/\.sfx\.timing\.json$/, "") + ".sfx-cache";
+	const clips = timing.clips.map((c) => ({
+		asset: {
+			kind: "audio",
+			url: `${cacheBase}/${c.file}`
+		},
+		at: c.at,
+		...c.playbackRate !== void 0 ? { playbackRate: c.playbackRate } : {},
+		...c.gain !== void 0 ? { gain: { keys: [{
+			t: 0,
+			value: c.gain
+		}] } } : {}
+	}));
+	const n = clips.length;
+	return {
+		clips,
+		note: `sfx (${n} ${n === 1 ? "hit" : "hits"})`
+	};
+}
+//#endregion
+export { buildSfxClipsFromTiming, prepareSfx, sfxScriptPathFor, sfxTimingPathFor };

package/package.json

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