luckiest-co 1.0.32 → 1.0.34

package/skills/luckiest-video-studio/scripts/render-scenes.mjs

@@ -1,24 +1,26 @@
 #!/usr/bin/env node
 // Render each storyboard scene to clips/NN-id.mp4, skip unchanged scenes, then join final.mp4 and write TIMING.md.
-// Usage: node render-scenes.mjs <run-dir> [--scene <id>]... [--quality draft|looks|delivery] [--no-join]
-import { spawnSync } from "node:child_process";
+// With storyboard "formats", each format renders into clips/<format>/ and joins final-<format>.mp4.
+// Landscape reuses the clips of a finished single-format 16:9 render, so adding formats renders only the new ones.
+// --stills skips the render: one hold-frame PNG per scene per format in stills/[<format>/], plus a sheet.png each.
+// Usage: node render-scenes.mjs <run-dir> [--scene <id>]... [--quality draft|looks|delivery] [--no-join] [--stills [--jobs 2]]
+import { spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { FORMATS, stampFormat } from "./stamp-format.mjs";
 
 const args = process.argv.slice(2);
-const runDir = resolve(args.find((a, i) => !a.startsWith("--") && !["--scene", "--quality"].includes(args[i - 1])) ?? ".");
+const runDir = resolve(args.find((a, i) => !a.startsWith("--") && !["--scene", "--quality", "--jobs"].includes(args[i - 1])) ?? ".");
 const forced = args.flatMap((a, i) => (a === "--scene" ? [args[i + 1]] : []));
 const quality = args.includes("--quality") ? args[args.indexOf("--quality") + 1] : "looks";
 const join_ = !args.includes("--no-join");
+const stills = args.includes("--stills");
+const jobs = args.includes("--jobs") ? Number(args[args.indexOf("--jobs") + 1]) : 2; // ponytail: 4 parallel snapshots hit the 10s navigation timeout here
 
 const sb = JSON.parse(readFileSync(join(runDir, "storyboard.json"), "utf8"));
-const { width: W, height: H, fps } = sb.format;
-const clipsDir = join(runDir, "clips");
-const rawDir = join(clipsDir, ".raw");
-mkdirSync(rawDir, { recursive: true });
-const cachePath = join(clipsDir, ".cache.json");
-const cache = existsSync(cachePath) ? JSON.parse(readFileSync(cachePath, "utf8")) : {};
+const { fps } = sb.format;
 
 const fail = (msg) => { console.error(`error: ${msg}`); process.exit(1); };
 const run = (cmd, argv, opts = {}) => {
@@ -37,6 +39,17 @@ for (const s of sb.scenes) {
 }
 for (const id of forced) if (!ids.has(id)) fail(`--scene ${id}: no such scene`);
 
+// No "formats": one target with today's paths. With "formats": one target per format, each in its own folder.
+const multi = Array.isArray(sb.formats);
+const clipsRoot = join(runDir, "clips");
+const targets = multi
+  ? sb.formats.map((fmt) => {
+    if (!FORMATS[fmt]) fail(`formats: unknown format "${fmt}" (landscape, vertical, square)`);
+    const [W, H] = FORMATS[fmt];
+    return { fmt, W, H, dir: join(clipsRoot, fmt), final: `final-${fmt}.mp4` };
+  })
+  : [{ fmt: null, W: sb.format.width, H: sb.format.height, dir: clipsRoot, final: "final.mp4" }];
+
 const inputsOf = (s) => {
   const files = [...(s.assets ?? [])];
   if (s.kind === "demo") {
@@ -45,81 +58,193 @@ const inputsOf = (s) => {
   } else files.push(join("composition", s.composition ?? `compositions/${s.id}.html`));
   return files;
 };
-const hashOf = (s) => {
-  const h = createHash("sha256").update(JSON.stringify({ s, W, H, fps, quality }));
+
+// Cache key for one scene at one target. fmt null is a single-format run with today's paths.
+function sceneHash(s, { W, H, fmt }) {
+  const h = createHash("sha256").update(JSON.stringify({ s, W, H, fps, quality, fmt }));
   for (const f of inputsOf(s)) {
     const p = join(runDir, f);
     if (!existsSync(p)) fail(`scene ${s.id}: missing ${f}`);
     h.update(f).update(readFileSync(p));
   }
   return h.digest("hex").slice(0, 16);
-};
+}
 
-// Every clip gets the same codec, size, fps and a stereo audio track so the join is a lossless concat.
-const normalize = (input, out, s, seek = 0) => {
-  const probe = spawnSync("ffprobe", ["-v", "error", "-select_streams", "a", "-show_entries", "stream=index", "-of", "csv=p=0", input], { encoding: "utf8" });
-  const hasAudio = probe.stdout.trim().length > 0;
-  const vf = `scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2,fps=${fps},format=yuv420p`;
-  const a = ["-y", "-v", "error", "-ss", String(seek), "-t", String(s.duration), "-i", input];
-  if (!hasAudio) a.push("-f", "lavfi", "-t", String(s.duration), "-i", "anullsrc=r=48000:cl=stereo");
-  a.push("-map", "0:v:0", "-map", hasAudio ? "0:a:0" : "1:a:0", "-vf", vf, "-c:v", "libx264", "-crf", "18", "-preset", "medium",
-    "-c:a", "aac", "-ar", "48000", "-ac", "2", "-shortest", "-movflags", "+faststart", out);
-  run("ffmpeg", a);
-};
+// Footage is cropped to fill around scenes[].focus when rendering formats or when focus is set;
+// otherwise it is letterboxed as before, so a single-format run keeps its old framing.
+function fitFilter(s, W, H) {
+  const { x = 0.5, y = 0.5 } = s.focus ?? {};
+  return s.kind === "demo" && (multi || s.focus)
+    ? `scale=${W}:${H}:force_original_aspect_ratio=increase,crop=${W}:${H}:'max(0,min(iw-ow,${x}*iw-ow/2))':'max(0,min(ih-oh,${y}*ih-oh/2))'`
+    : `scale=${W}:${H}:force_original_aspect_ratio=decrease,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2`;
+}
 
 const hf = hasBin("hyperframes") ? ["hyperframes"] : ["npx", `hyperframes@${sb.hyperframes ?? "latest"}`];
 let rendered = 0;
-const clips = sb.scenes.map((s, i) => {
-  const name = `${String(i + 1).padStart(2, "0")}-${s.id}.mp4`;
-  const out = join(clipsDir, name);
-  const hash = hashOf(s);
-  const prev = cache[s.id];
-  const force = forced.includes(s.id);
-  if (!force && prev?.hash === hash && existsSync(join(clipsDir, prev.file))) {
-    if (prev.file !== name) renameSync(join(clipsDir, prev.file), out);
-    console.log(`skip   ${name} (unchanged)`);
-  } else if (forced.length && !force && prev && existsSync(join(clipsDir, prev.file))) {
-    if (prev.file !== name) renameSync(join(clipsDir, prev.file), out);
-    console.log(`keep   ${name} (not selected)`);
-    return { s, name, hash: prev.hash };
-  } else {
-    console.log(`render ${name}`);
-    if (s.kind === "demo") normalize(join(runDir, s.source), out, s, s.sourceStart ?? 0);
-    else {
-      const raw = join(rawDir, name);
-      const comp = s.composition ?? `compositions/${s.id}.html`;
-      run(hf[0], [...hf.slice(1), "render", "-c", comp, "-o", raw, "--fps", String(fps), "--quality", quality], { cwd: join(runDir, "composition") });
-      normalize(raw, out, s);
+
+function renderTarget({ fmt, W, H, dir, final: finalName }) {
+  const rawDir = join(dir, ".raw");
+  mkdirSync(rawDir, { recursive: true });
+  const cachePath = join(dir, ".cache.json");
+  const cache = existsSync(cachePath) ? JSON.parse(readFileSync(cachePath, "utf8")) : {};
+  const tag = (name) => (fmt ? `${fmt}/${name}` : name);
+
+  const hashOf = (s) => sceneHash(s, { W, H, fmt });
+  // A finished single-format 16:9 render (clips/.cache.json) stands in for the landscape format: the landscape
+  // stamp only restates the master defaults, so the pixels match. Footage is framed differently, so demos re-run.
+  const single = fmt === "landscape" && sb.format.width === W && sb.format.height === H && existsSync(join(clipsRoot, ".cache.json"))
+    ? JSON.parse(readFileSync(join(clipsRoot, ".cache.json"), "utf8")) : {};
+
+  // Every clip gets the same codec, size, fps and a stereo audio track so the join is a lossless concat.
+  const normalize = (input, out, s, seek = 0) => {
+    const probe = spawnSync("ffprobe", ["-v", "error", "-select_streams", "a", "-show_entries", "stream=index", "-of", "csv=p=0", input], { encoding: "utf8" });
+    const hasAudio = probe.stdout.trim().length > 0;
+    const vf = `${fitFilter(s, W, H)},fps=${fps},format=yuv420p`;
+    const a = ["-y", "-v", "error", "-ss", String(seek), "-t", String(s.duration), "-i", input];
+    if (!hasAudio) a.push("-f", "lavfi", "-t", String(s.duration), "-i", "anullsrc=r=48000:cl=stereo");
+    a.push("-map", "0:v:0", "-map", hasAudio ? "0:a:0" : "1:a:0", "-vf", vf, "-c:v", "libx264", "-crf", "18", "-preset", "medium",
+      "-c:a", "aac", "-ar", "48000", "-ac", "2", "-shortest", "-movflags", "+faststart", out);
+    run("ffmpeg", a);
+  };
+
+  const clips = sb.scenes.map((s, i) => {
+    const name = `${String(i + 1).padStart(2, "0")}-${s.id}.mp4`;
+    const out = join(dir, name);
+    const hash = hashOf(s);
+    const prev = cache[s.id];
+    const force = forced.includes(s.id);
+    const legacy = single[s.id];
+    if (!force && prev?.hash === hash && existsSync(join(dir, prev.file))) {
+      if (prev.file !== name) renameSync(join(dir, prev.file), out);
+      console.log(`skip   ${tag(name)} (unchanged)`);
+    } else if (!force && s.kind !== "demo" && legacy?.hash === sceneHash(s, { W, H, fmt: null }) && existsSync(join(clipsRoot, legacy.file))) {
+      copyFileSync(join(clipsRoot, legacy.file), out);
+      console.log(`reuse  ${tag(name)} (from the 16:9 render)`);
+    } else if (forced.length && !force && prev && existsSync(join(dir, prev.file))) {
+      if (prev.file !== name) renameSync(join(dir, prev.file), out);
+      console.log(`keep   ${tag(name)} (not selected)`);
+      return { s, name, hash: prev.hash };
+    } else {
+      console.log(`render ${tag(name)}`);
+      if (s.kind === "demo") normalize(join(runDir, s.source), out, s, s.sourceStart ?? 0);
+      else {
+        const raw = join(rawDir, name);
+        const compDir = join(runDir, "composition");
+        let comp = s.composition ?? `compositions/${s.id}.html`;
+        // A stamped copy next to the original, so relative asset paths still resolve.
+        if (fmt) {
+          const stamped = comp.replace(/\.html$/, `.${fmt}.html`);
+          writeFileSync(join(compDir, stamped), stampFormat(readFileSync(join(compDir, comp), "utf8"), fmt));
+          comp = stamped;
+        }
+        run(hf[0], [...hf.slice(1), "render", "-c", comp, "-o", raw, "--fps", String(fps), "--quality", quality], { cwd: compDir });
+        if (fmt) rmSync(join(compDir, comp));
+        normalize(raw, out, s);
+      }
+      rendered++;
+    }
+    return { s, name, hash };
+  });
+
+  writeFileSync(cachePath, JSON.stringify(Object.fromEntries(clips.map((c) => [c.s.id, { hash: c.hash, file: c.name }])), null, 2));
+  const t = clips.reduce((sum, c) => sum + c.s.duration, 0);
+
+  if (join_) {
+    const list = join(dir, ".concat.txt");
+    writeFileSync(list, clips.map((c) => `file '${join(dir, c.name).replace(/'/g, "'\\''")}'`).join("\n") + "\n");
+    const joined = join(dir, ".joined.mp4");
+    run("ffmpeg", ["-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", joined]);
+    const final = join(runDir, finalName);
+    // Mix the clips' own audio with the music bed and the global SFX track from sfx-cues.mjs.
+    // music.offset skips into the track, music.at starts it in the video, so a chosen kick lands on a chosen moment.
+    const ins = ["-i", joined], legs = [], tags = ["[0:a]"];
+    if (sb.music?.file) {
+      const at = sb.music.at ?? 0;
+      ins.push("-stream_loop", "-1", "-i", join(runDir, sb.music.file));
+      legs.push(`[1:a]atrim=start=${sb.music.offset ?? 0},asetpts=PTS-STARTPTS,volume=${sb.music.volume ?? 0.35},afade=t=out:st=${Math.max(0, t - at - 1.5)}:d=1.5,adelay=${Math.round(at * 1000)}:all=1[m]`);
+      tags.push("[m]");
+    }
+    if (sb.sfx?.file) {
+      ins.push("-i", join(runDir, sb.sfx.file));
+      legs.push(`[${tags.length}:a]volume=${sb.sfx.volume ?? 1}[x]`);
+      tags.push("[x]");
+    }
+    const mixed = join(dir, ".mix.wav");
+    const graph = tags.length > 1 ? `${legs.join(";")};${tags.join("")}amix=inputs=${tags.length}:duration=first:normalize=0[a]` : "[0:a]anull[a]";
+    run("ffmpeg", ["-y", "-v", "error", ...ins, "-filter_complex", graph, "-map", "[a]", "-c:a", "pcm_s16le", "-ar", "48000", "-t", String(t), mixed]);
+    // Two-pass loudness to sb.loudness LUFS (default -14, the streaming norm). false skips it; silence is left alone.
+    const target = sb.loudness ?? -14;
+    let af = "anull";
+    if (target !== false) {
+      const m = spawnSync("ffmpeg", ["-hide_banner", "-nostats", "-i", mixed, "-af", `loudnorm=I=${target}:TP=-1.2:LRA=11:print_format=json`, "-f", "null", "-"], { encoding: "utf8" });
+      const js = JSON.parse(m.stderr.match(/\{[^{}]*"input_i"[^{}]*\}/)?.[0] ?? "{}");
+      if (Number(js.input_i) > -70) af = `loudnorm=I=${target}:TP=-1.2:LRA=11:measured_I=${js.input_i}:measured_TP=${js.input_tp}:measured_LRA=${js.input_lra}:measured_thresh=${js.input_thresh}:offset=${js.target_offset}:linear=true,aresample=48000`;
     }
-    rendered++;
+    run("ffmpeg", ["-y", "-v", "error", "-i", joined, "-i", mixed, "-map", "0:v", "-map", "1:a", "-af", af,
+      "-c:v", "copy", "-c:a", "aac", "-b:a", "192k", "-t", String(t), "-movflags", "+faststart", final]);
+    rmSync(joined);
+    rmSync(mixed);
+    console.log(`joined ${finalName} (${t.toFixed(2)}s)`);
   }
-  return { s, name, hash };
-});
+  return { clips, t, tag };
+}
 
-const nextCache = Object.fromEntries(clips.map((c) => [c.s.id, { hash: c.hash, file: c.name }]));
-writeFileSync(cachePath, JSON.stringify(nextCache, null, 2));
+// One PNG per scene at its hold frame (scenes[].hold, else 0.5s before the cut), no video encode.
+// Each motion or logo scene is snapshotted as the index.html of a temp project whose other entries link
+// back to composition/, the same stamped copy the render uses, so relative asset paths still resolve.
+async function captureStills({ fmt, W, H }) {
+  const dir = join(runDir, "stills", fmt ?? "");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const compDir = join(runDir, "composition");
+  const queue = sb.scenes.map((s, i) => ({ s, name: `${String(i + 1).padStart(2, "0")}-${s.id}.png` }));
+  const worker = async () => {
+    for (let job = queue.shift(); job; job = queue.shift()) {
+      const { s, name } = job, at = s.hold ?? Math.max(0, s.duration - 0.5), out = join(dir, name);
+      if (s.kind === "demo") {
+        run("ffmpeg", ["-y", "-v", "error", "-ss", String((s.sourceStart ?? 0) + at), "-i", join(runDir, s.source), "-frames:v", "1", "-vf", fitFilter(s, W, H), out]);
+        continue;
+      }
+      const proj = mkdtempSync(join(tmpdir(), "stills-"));
+      for (const e of readdirSync(compDir)) if (e !== "index.html") symlinkSync(join(compDir, e), join(proj, e));
+      const html = readFileSync(join(compDir, s.composition ?? `compositions/${s.id}.html`), "utf8");
+      writeFileSync(join(proj, "index.html"), fmt ? stampFormat(html, fmt) : html);
+      let err = "";
+      const code = await new Promise((done) => {
+        const p = spawn(hf[0], [...hf.slice(1), "snapshot", proj, "--at", String(at), "--no-end", "-o", join(proj, ".snap"), "--describe", "false"]);
+        p.stdout.resume();
+        p.stderr.on("data", (b) => (err += b));
+        p.on("close", done);
+      });
+      const png = existsSync(join(proj, ".snap")) && readdirSync(join(proj, ".snap")).find((f) => f.startsWith("frame-"));
+      if (code !== 0 || !png) fail(`snapshot failed for scene ${s.id}${fmt ? ` (${fmt})` : ""}: ${err.trim().split("\n").pop()}`);
+      copyFileSync(join(proj, ".snap", png), out);
+      rmSync(proj, { recursive: true, force: true });
+    }
+  };
+  await Promise.all(Array.from({ length: jobs }, worker));
+  // ponytail: one sheet per format, 6 across at 320px wide; read it instead of every PNG.
+  const cols = Math.min(6, sb.scenes.length), rows = Math.ceil(sb.scenes.length / cols);
+  run("ffmpeg", ["-y", "-v", "error", "-pattern_type", "glob", "-i", join(dir, "[0-9]*.png"),
+    "-vf", `scale=320:-2,tile=${cols}x${rows}:padding=6:color=white`, "-frames:v", "1", join(dir, "sheet.png")]);
+  console.log(`stills ${join("stills", fmt ?? "", "sheet.png")} (${sb.scenes.length} scenes, ${W}x${H})`);
+}
+
+if (stills) {
+  for (const t of targets) await captureStills(t);
+  process.exit(0);
+}
+const results = targets.map(renderTarget);
 
-let t = 0;
+// Timing is the same in every format, so TIMING.md lists the first format's clips.
+const { clips, t, tag } = results[0];
+let at = 0;
 const rows = clips.map(({ s, name }, i) => {
-  const row = `| ${i + 1} | ${s.id} | ${s.kind} | ${t.toFixed(2)} | ${(t + s.duration).toFixed(2)} | \`clips/${name}\` | ${(s.line ?? "").replace(/\|/g, "/")} |`;
-  t += s.duration;
+  const row = `| ${i + 1} | ${s.id} | ${s.kind} | ${at.toFixed(2)} | ${(at + s.duration).toFixed(2)} | \`clips/${tag(name)}\` | ${(s.line ?? "").replace(/\|/g, "/")} |`;
+  at += s.duration;
   return row;
 });
-writeFileSync(join(runDir, "TIMING.md"), `# Timing: ${sb.title}\n\nTotal ${t.toFixed(2)}s at ${W}x${H}, ${fps} fps.\n\n| # | Scene | Kind | In (s) | Out (s) | Clip | Line |\n|---|---|---|---|---|---|---|\n${rows.join("\n")}\n`);
-
-if (join_) {
-  const list = join(clipsDir, ".concat.txt");
-  writeFileSync(list, clips.map((c) => `file '${join(clipsDir, c.name).replace(/'/g, "'\\''")}'`).join("\n") + "\n");
-  const joined = join(clipsDir, ".joined.mp4");
-  run("ffmpeg", ["-y", "-v", "error", "-f", "concat", "-safe", "0", "-i", list, "-c", "copy", joined]);
-  const final = join(runDir, "final.mp4");
-  if (sb.music?.file) {
-    const vol = String(sb.music.volume ?? 0.35);
-    run("ffmpeg", ["-y", "-v", "error", "-i", joined, "-stream_loop", "-1", "-i", join(runDir, sb.music.file),
-      "-filter_complex", `[1:a]volume=${vol},afade=t=out:st=${Math.max(0, t - 1.5)}:d=1.5[m];[0:a][m]amix=inputs=2:duration=first:normalize=0[a]`,
-      "-map", "0:v", "-map", "[a]", "-c:v", "copy", "-c:a", "aac", "-t", String(t), "-movflags", "+faststart", final]);
-    rmSync(joined);
-  } else renameSync(joined, final);
-  console.log(`joined final.mp4 (${t.toFixed(2)}s)`);
-}
-console.log(`done: ${rendered} rendered, ${clips.length - rendered} reused`);
+const size = multi ? targets.map((x) => `${x.fmt} ${x.W}x${x.H} (${x.final})`).join(", ") : `${targets[0].W}x${targets[0].H}`;
+writeFileSync(join(runDir, "TIMING.md"), `# Timing: ${sb.title}\n\nTotal ${t.toFixed(2)}s at ${size}, ${fps} fps.\n\n| # | Scene | Kind | In (s) | Out (s) | Clip | Line |\n|---|---|---|---|---|---|---|\n${rows.join("\n")}\n`);
+const total = clips.length * targets.length;
+console.log(`done: ${rendered} rendered, ${total - rendered} reused`);

package/skills/luckiest-video-studio/scripts/render-scenes.test.mjs

@@ -0,0 +1,109 @@
+// The join places the music where storyboard.json says and lands the mix at the target loudness.
+// Demo scenes only, so nothing but ffmpeg runs; fixtures are lavfi clips in a temp folder.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { audioOnsets } from "./qa.mjs";
+import { stampFormat } from "./stamp-format.mjs";
+
+const ff = (...a) => { const r = spawnSync("ffmpeg", ["-v", "error", "-y", ...a]); assert.equal(r.status, 0, r.stderr?.toString()); };
+const lufs = (f) => Number(spawnSync("ffmpeg", ["-hide_banner", "-nostats", "-i", f, "-af", "ebur128", "-f", "null", "-"], { encoding: "utf8" }).stderr.match(/I:\s+(-?[\d.]+) LUFS/g).pop().match(/-?[\d.]+/)[0]);
+
+function run(music, { burst = true } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "render-scenes-"));
+  mkdirSync(join(dir, "demo"));
+  mkdirSync(join(dir, "audio"));
+  ff("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30:duration=4", "-c:v", "libx264", join(dir, "demo/a.mp4"));
+  // A quiet noise bed, with one loud burst 1.0 s into the track for the placement test.
+  ff("-f", "lavfi", "-i", `aevalsrc='(0.05+${burst ? 0.8 : 0}*between(t,1,1.1))*(random(0)-0.5)':s=48000:d=6`, join(dir, "audio/music.wav"));
+  writeFileSync(join(dir, "storyboard.json"), JSON.stringify({
+    version: 1, title: "t", mode: "demo", format: { width: 320, height: 180, fps: 30 },
+    music: { file: "audio/music.wav", volume: 0.5, ...music },
+    scenes: [{ id: "a", kind: "demo", duration: 2, source: "demo/a.mp4" }, { id: "b", kind: "demo", duration: 2, source: "demo/a.mp4", sourceStart: 2 }],
+  }));
+  const r = spawnSync(process.execPath, [join(import.meta.dirname, "render-scenes.mjs"), dir], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  return join(dir, "final.mp4");
+}
+
+test("music.offset and music.at land a moment in the track on a moment in the video", () => {
+  // Burst at 1.0 s in the track; skip 0.5 s of it and start it 1.0 s in: the burst lands at 1.5 s.
+  const on = audioOnsets(run({ offset: 0.5, at: 1 }));
+  assert.ok(on[0] >= 0.95, `music starts at ${on[0]}, not before 1.0`);
+  assert.ok(on.some((t) => Math.abs(t - 1.5) < 1 / 30), JSON.stringify(on));
+});
+
+test("the final mix is normalized to -14 LUFS by default", () => {
+  const quiet = run({}, { burst: false });
+  assert.ok(Math.abs(lufs(quiet) + 14) <= 1, `measured ${lufs(quiet)} LUFS`);
+});
+
+test("formats render one final per format, cropping footage around focus", () => {
+  const dir = mkdtempSync(join(tmpdir(), "render-formats-"));
+  mkdirSync(join(dir, "demo"));
+  // Left half red, right half blue, so the crop side is visible in one pixel.
+  ff("-f", "lavfi", "-i", "color=red:size=320x180:rate=30:duration=2", "-f", "lavfi", "-i", "color=blue:size=160x180:rate=30:duration=2",
+    "-filter_complex", "[0][1]overlay=x=160", "-c:v", "libx264", join(dir, "demo/a.mp4"));
+  writeFileSync(join(dir, "storyboard.json"), JSON.stringify({
+    version: 1, title: "t", mode: "demo", format: { width: 1920, height: 1080, fps: 30 }, formats: ["landscape", "vertical"], loudness: false,
+    scenes: [{ id: "a", kind: "demo", duration: 1, source: "demo/a.mp4", focus: { x: 0.9, y: 0.5 } }],
+  }));
+  const r = spawnSync(process.execPath, [join(import.meta.dirname, "render-scenes.mjs"), dir], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  const size = (f) => spawnSync("ffprobe", ["-v", "error", "-select_streams", "v", "-show_entries", "stream=width,height", "-of", "csv=p=0", join(dir, f)], { encoding: "utf8" }).stdout.trim();
+  assert.equal(size("final-landscape.mp4"), "1920,1080");
+  assert.equal(size("final-vertical.mp4"), "1080,1920");
+  assert.ok(existsSync(join(dir, "clips/vertical/01-a.mp4")) && !existsSync(join(dir, "final.mp4")));
+  // focus x 0.9 keeps the blue right side in the vertical crop.
+  const px = spawnSync("ffmpeg", ["-v", "error", "-i", join(dir, "final-vertical.mp4"), "-frames:v", "1", "-vf", "crop=2:2:540:960", "-f", "rawvideo", "-pix_fmt", "rgb24", "-"]).stdout;
+  assert.ok(px[2] > 150 && px[0] < 100, `center pixel ${[...px]}`);
+});
+
+test("stampFormat sizes the root, tags the format, and injects size tokens", () => {
+  const html = `<html lang="en" data-resolution="landscape"><head><style>:root{--w:1920px}</style></head><body><div id="root" data-composition-id="main" data-width="1920" data-height="1080"></div></body></html>`;
+  const out = stampFormat(html, "vertical");
+  assert.match(out, /<html lang="en" data-resolution="portrait" data-format="vertical">/);
+  assert.match(out, /data-composition-id="main" data-width="1080" data-height="1920" data-format="vertical">/);
+  assert.match(out, /--w:1920px\}<\/style><style>:root\{--w:1080px;--h:1920px;--u:10\.8px;--safe-t:288px;--safe-b:672px;--safe-l:119px;--safe-r:194px\}<\/style><\/head>/);
+});
+
+test("formats reuse a finished 16:9 render for landscape instead of rendering it again", () => {
+  const dir = mkdtempSync(join(tmpdir(), "render-reuse-"));
+  mkdirSync(join(dir, "composition/compositions"), { recursive: true });
+  mkdirSync(join(dir, "clips"));
+  writeFileSync(join(dir, "composition/compositions/m.html"), "<html><body>m</body></html>");
+  const scene = { id: "m", kind: "motion", duration: 1 };
+  const sb = { version: 1, title: "t", mode: "launch", format: { width: 1920, height: 1080, fps: 30 }, scenes: [scene] };
+  // The cache entry a single-format render writes: same key the coordinator computes for fmt null.
+  const comp = join("composition", "compositions/m.html");
+  const hash = createHash("sha256").update(JSON.stringify({ s: scene, W: 1920, H: 1080, fps: 30, quality: "looks", fmt: null }))
+    .update(comp).update(readFileSync(join(dir, comp))).digest("hex").slice(0, 16);
+  writeFileSync(join(dir, "clips/.cache.json"), JSON.stringify({ m: { hash, file: "01-m.mp4" } }));
+  ff("-f", "lavfi", "-i", "color=red:size=1920x1080:rate=30:duration=1", "-c:v", "libx264", join(dir, "clips/01-m.mp4"));
+  writeFileSync(join(dir, "storyboard.json"), JSON.stringify({ ...sb, formats: ["landscape"] }));
+  const r = spawnSync(process.execPath, [join(import.meta.dirname, "render-scenes.mjs"), dir, "--no-join"], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /reuse {2}landscape\/01-m\.mp4/);
+  assert.match(r.stdout, /done: 0 rendered, 1 reused/);
+  assert.ok(existsSync(join(dir, "clips/landscape/01-m.mp4")));
+});
+
+test("--stills writes one hold frame per scene per format and a sheet, without rendering", () => {
+  const dir = mkdtempSync(join(tmpdir(), "render-stills-"));
+  mkdirSync(join(dir, "demo"));
+  ff("-f", "lavfi", "-i", "testsrc2=size=320x180:rate=30:duration=2", "-c:v", "libx264", join(dir, "demo/a.mp4"));
+  writeFileSync(join(dir, "storyboard.json"), JSON.stringify({
+    version: 1, title: "t", mode: "demo", format: { width: 1920, height: 1080, fps: 30 }, formats: ["landscape", "vertical"],
+    scenes: [{ id: "a", kind: "demo", duration: 1.5, source: "demo/a.mp4" }],
+  }));
+  const r = spawnSync(process.execPath, [join(import.meta.dirname, "render-scenes.mjs"), dir, "--stills"], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  const size = (f) => spawnSync("ffprobe", ["-v", "error", "-show_entries", "stream=width,height", "-of", "csv=p=0", join(dir, f)], { encoding: "utf8" }).stdout.trim();
+  assert.equal(size("stills/landscape/01-a.png"), "1920,1080");
+  assert.equal(size("stills/vertical/01-a.png"), "1080,1920");
+  assert.ok(existsSync(join(dir, "stills/vertical/sheet.png")) && !existsSync(join(dir, "clips")));
+});

package/skills/luckiest-video-studio/scripts/sfx-cues.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Mix a cue file of sound effects into one sfx.wav, each sound placed by its anchor, plus a cue sheet.
+// Needs Node 22+ and ffmpeg/ffprobe; nothing else is installed or downloaded.
+//
+//   node sfx-cues.mjs <sfx_cues.json> [--sfx-dir <skill-dir>/assets/sfx] [--events <composition-dir>] [--out <dir>]
+//
+// sfx_cues.json:
+//   { "duration": 20,
+//     "cues":  [{ "t": 4.0, "file": "impact/impactSoft_medium_001.ogg", "align": "start", "volume": 0.8, "label": "reveal" },
+//               { "t": 6.0, "file": "<sourced>/whoosh.wav", "align": "peak" },          // peak on the cut
+//               { "t": 9.5, "kind": "impact" }],                                        // file from kinds
+//     "slots": { "02-reveal": 3.5 },          // scene id -> global start, for scene events
+//     "kinds": { "card": "casino/card-slide-1.ogg" } }   // extra or overriding event kinds
+//
+// Scene events: <events-dir>/<scene-id>.motion.json = { "events": [{ "t": 0.25, "kind": "key", "note": "typed H" }] }
+// with times local to the scene. Each one becomes a cue at slot start + t.
+// align: start (default) puts the file start on t, peak its loudest 10 ms, end its last sample.
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname, isAbsolute } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const KEYS = Array.from({ length: 32 }, (_, i) => `keyboard/keypress-${String(i + 1).padStart(3, "0")}.wav`);
+// [file, volume] per event kind; volumes follow the gain ladder in references/audio.md.
+export const DEFAULT_KINDS = {
+  key: [KEYS, 0.3], click: ["interface/click_001.ogg", 0.35], switch: ["interface/switch_001.ogg", 0.35],
+  pop: ["interface/drop_001.ogg", 0.4], card: ["casino/card-place-1.ogg", 0.4],
+  glitch: ["interface/glitch_002.ogg", 0.6], error: ["interface/error_005.ogg", 0.6],
+  impact: ["impact/impactSoft_medium_000.ogg", 0.8], success: ["impact/impactBell_heavy_000.ogg", 0.8],
+};
+
+const anchors = new Map();
+export function anchorOffset(file, align = "start") {
+  if (align === "start") return 0;
+  const key = `${file}|${align}`;
+  if (anchors.has(key)) return anchors.get(key);
+  const r = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-ac", "1", "-ar", "8000", "-f", "s16le", "-"], { maxBuffer: 1 << 28 });
+  if (r.status !== 0) throw new Error(`ffmpeg failed on ${file}: ${r.stderr}`);
+  const pcm = new Int16Array(r.stdout.buffer, r.stdout.byteOffset, r.stdout.length >> 1);
+  let off;
+  if (align === "end") off = pcm.length / 8000;
+  else if (align === "peak") {
+    let best = -1, at = 0;
+    for (let o = 0; o + 80 <= pcm.length; o += 80) {
+      let s = 0; for (let i = o; i < o + 80; i++) s += (pcm[i] / 32768) ** 2;
+      if (s > best) { best = s; at = o + 40; }
+    }
+    off = at / 8000;
+  } else throw new Error(`unknown align "${align}" (start, peak, end)`);
+  anchors.set(key, off);
+  return off;
+}
+
+// Cue file + scene events -> [{ t, file, align, volume, label, start, trim }], sorted by t.
+export function buildCues(spec, { sfxDir, eventsDir } = {}) {
+  const kinds = { ...DEFAULT_KINDS };
+  for (const [k, f] of Object.entries(spec.kinds ?? {})) kinds[k] = [f, kinds[k]?.[1] ?? 0.6];
+  const at = (f) => (isAbsolute(f) ? f : join(sfxDir, f));
+  const fromKind = (kind, i) => { const [f, v] = kinds[kind]; return [Array.isArray(f) ? f[i % f.length] : f, v]; };
+  const cues = [];
+  (spec.cues ?? []).forEach((c, i) => {
+    if (!c.file && !kinds[c.kind]) return console.error(`skip cue at ${c.t}s: no file and unknown kind "${c.kind}"`);
+    const [f, v] = c.file ? [c.file, 0.6] : fromKind(c.kind, i);
+    cues.push({ t: c.t, file: at(f), align: c.align ?? "start", volume: c.volume ?? v, label: c.label ?? c.kind ?? "" });
+  });
+  for (const [id, start] of Object.entries(spec.slots ?? {})) {
+    const p = eventsDir && join(eventsDir, `${id}.motion.json`);
+    if (!p || !existsSync(p)) continue;
+    JSON.parse(readFileSync(p, "utf8")).events?.forEach((e, i) => {
+      if (!kinds[e.kind]) return console.error(`skip ${id} event at ${e.t}s: unknown kind "${e.kind}"`);
+      const [f, v] = fromKind(e.kind, i);
+      cues.push({ t: Number((start + e.t).toFixed(3)), file: at(f), align: "start", volume: v, label: `${id}: ${e.note ?? e.kind}` });
+    });
+  }
+  for (const c of cues) {
+    if (!existsSync(c.file)) throw new Error(`missing sound file: ${c.file}`);
+    const s = c.t - anchorOffset(c.file, c.align);
+    c.start = Math.max(0, s);
+    c.trim = Math.max(0, -s); // a sound whose lead-in falls before 0 loses that part
+  }
+  return cues.sort((a, b) => a.t - b.t);
+}
+
+export function mixCues(cues, { duration, outDir }) {
+  mkdirSync(outDir, { recursive: true });
+  const out = join(outDir, "sfx.wav");
+  const args = ["-v", "error", "-y"];
+  let graph;
+  if (!cues.length) {
+    args.push("-f", "lavfi", "-i", `anullsrc=r=48000:cl=stereo:d=${duration}`);
+    graph = "[0:a]anull[out]";
+  } else {
+    // ponytail: one ffmpeg input per cue; hundreds are fine, thousands would want pre-mixed buses.
+    cues.forEach((c) => args.push("-i", c.file));
+    const legs = cues.map((c, i) => `[${i}:a]aresample=48000,aformat=channel_layouts=stereo,atrim=start=${c.trim.toFixed(4)},asetpts=PTS-STARTPTS,volume=${c.volume},adelay=${Math.round(c.start * 1000)}:all=1[a${i}]`);
+    graph = `${legs.join(";")};${cues.map((_, i) => `[a${i}]`).join("")}amix=inputs=${cues.length}:normalize=0:duration=longest,apad=whole_dur=${duration},atrim=0:${duration}[out]`;
+  }
+  const r = spawnSync("ffmpeg", [...args, "-filter_complex", graph, "-map", "[out]", "-c:a", "pcm_s16le", out], { encoding: "utf8" });
+  if (r.status !== 0) throw new Error(`ffmpeg mix failed: ${r.stderr}`);
+  const rows = cues.map((c) => `| ${c.t.toFixed(3)} | ${c.align} | ${c.start.toFixed(3)} | ${c.volume} | ${c.file.split("/").slice(-2).join("/")} | ${c.label} |`);
+  writeFileSync(join(outDir, "sfx-cuesheet.md"), `# SFX cue sheet\n\n${cues.length} cues, ${duration}s.\n\n| t | anchor | file starts | volume | sound | label |\n|---|---|---|---|---|---|\n${rows.join("\n")}\n`);
+  return out;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [file, ...rest] = process.argv.slice(2);
+  const opt = (n, d) => { const i = rest.indexOf(n); return i >= 0 ? rest[i + 1] : d; };
+  if (!file) { console.error("Usage: sfx-cues.mjs <sfx_cues.json> [--sfx-dir dir] [--events dir] [--out dir]"); process.exit(1); }
+  const spec = JSON.parse(readFileSync(file, "utf8"));
+  if (!(spec.duration > 0)) { console.error("sfx_cues.json needs a positive duration"); process.exit(1); }
+  const here = dirname(fileURLToPath(import.meta.url));
+  const cues = buildCues(spec, { sfxDir: resolve(opt("--sfx-dir", join(here, "../assets/sfx"))), eventsDir: opt("--events") && resolve(opt("--events")) });
+  const out = mixCues(cues, { duration: spec.duration, outDir: resolve(opt("--out", dirname(resolve(file)))) });
+  console.log(JSON.stringify({ ok: true, out, cues: cues.length }, null, 2));
+}

package/skills/luckiest-video-studio/scripts/sfx-cues.test.mjs

@@ -0,0 +1,76 @@
+// sfx-cues places each sound by its anchor (start, peak, end) and mixes one sfx.wav.
+// Fixtures are tiny ffmpeg tones in a temp folder; nothing is downloaded.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { anchorOffset, buildCues, mixCues } from "./sfx-cues.mjs";
+
+const dir = mkdtempSync(join(tmpdir(), "sfx-cues-"));
+const sfx = join(dir, "sfx");
+mkdirSync(sfx);
+const tone = (name, d, env) => {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "lavfi", "-i", `aevalsrc='(${env})*sin(2*PI*800*t)':s=48000:d=${d}`, join(sfx, name)]);
+  assert.equal(r.status, 0, r.stderr?.toString());
+};
+tone("click.wav", 0.05, "0.8");
+tone("whoosh.wav", 0.6, "0.8*(1-abs(t-0.3)/0.3)"); // loudest at 0.3 s
+tone("riser.wav", 0.5, "0.8*t/0.5");               // ends at full level
+
+// RMS per 10 ms window of a mono decode.
+function energy(file) {
+  const r = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-ac", "1", "-ar", "8000", "-f", "s16le", "-"], { maxBuffer: 1 << 28 });
+  const pcm = new Int16Array(r.stdout.buffer, r.stdout.byteOffset, r.stdout.length >> 1), n = 80, e = [];
+  for (let o = 0; o + n <= pcm.length; o += n) { let s = 0; for (let i = o; i < o + n; i++) s += (pcm[i] / 32768) ** 2; e.push(Math.sqrt(s / n)); }
+  return e;
+}
+const win = (e, a, b) => e.slice(Math.round(a * 100), Math.round(b * 100));
+
+test("anchorOffset: start is 0, peak is the loudest point, end is the length", () => {
+  assert.equal(anchorOffset(join(sfx, "click.wav"), "start"), 0);
+  assert.ok(Math.abs(anchorOffset(join(sfx, "whoosh.wav"), "peak") - 0.3) < 0.02);
+  assert.ok(Math.abs(anchorOffset(join(sfx, "riser.wav"), "end") - 0.5) < 0.02);
+});
+
+test("mix: a click starts, a whoosh peaks, and a riser ends on its cue, within one frame", () => {
+  const cues = { duration: 3, cues: [
+    { t: 0.5, file: "click.wav", align: "start", label: "pop" },
+    { t: 1.5, file: "whoosh.wav", align: "peak", label: "cut" },
+    { t: 2.5, file: "riser.wav", align: "end", label: "into the hit" },
+  ] };
+  const placed = buildCues(cues, { sfxDir: sfx });
+  const out = join(dir, "out");
+  mixCues(placed, { duration: 3, outDir: out });
+  const e = energy(join(out, "sfx.wav")), frame = 1 / 30;
+  const firstLoud = win(e, 0.3, 0.8).findIndex((v) => v > 0.05) / 100 + 0.3;
+  assert.ok(Math.abs(firstLoud - 0.5) < frame, `click at ${firstLoud}`);
+  const w = win(e, 1.0, 2.0), peak = w.indexOf(Math.max(...w)) / 100 + 1.0;
+  assert.ok(Math.abs(peak - 1.5) < frame, `whoosh peak at ${peak}`);
+  const r = win(e, 2.0, 3.0), lastLoud = (r.length - 1 - [...r].reverse().findIndex((v) => v > 0.05)) / 100 + 2.0;
+  assert.ok(Math.abs(lastLoud - 2.5) < frame, `riser ends at ${lastLoud}`);
+  const sheet = readFileSync(join(out, "sfx-cuesheet.md"), "utf8");
+  assert.match(sheet, /into the hit/);
+  assert.equal(spawnSync("ffprobe", ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", join(out, "sfx.wav")], { encoding: "utf8" }).stdout.trim().slice(0, 3), "3.0");
+});
+
+test("scene events: local times shift by the slot start and map kinds to files", () => {
+  const comp = join(dir, "composition");
+  mkdirSync(comp, { recursive: true });
+  writeFileSync(join(comp, "02-reveal.motion.json"), JSON.stringify({ events: [{ t: 0.25, kind: "click", note: "button" }, { t: 0.5, kind: "nope" }] }));
+  const placed = buildCues({ duration: 4, slots: { "02-reveal": 2 }, kinds: { click: "click.wav" }, cues: [] }, { sfxDir: sfx, eventsDir: comp });
+  assert.equal(placed.length, 1);
+  assert.equal(placed[0].t, 2.25);
+  assert.equal(placed[0].file, join(sfx, "click.wav"));
+  assert.equal(placed[0].skipped, undefined);
+});
+
+test("CLI writes sfx.wav and the cue sheet next to the cue file", () => {
+  const run = join(dir, "run");
+  mkdirSync(run);
+  writeFileSync(join(run, "sfx_cues.json"), JSON.stringify({ duration: 1, cues: [{ t: 0.2, file: "click.wav" }] }));
+  const r = spawnSync(process.execPath, [join(import.meta.dirname, "sfx-cues.mjs"), join(run, "sfx_cues.json"), "--sfx-dir", sfx], { encoding: "utf8" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(existsSync(join(run, "sfx.wav")) && existsSync(join(run, "sfx-cuesheet.md")));
+});