creator-editing-studio 1.0.20260930

package/template/scripts/refstyle.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Read a reference edit and write a style brief: how fast it cuts, how it paces itself,
+ * and what its colour looks like. Feed the brief to a session and say "match this energy".
+ *
+ *   npm run refstyle -- references/somereel.mp4 [--threshold 0.30] [--fps 30]
+ *
+ * Writes work/refs/<clip>/style-brief.md and .json — cut list, shot lengths, pacing over
+ * time, and colour stats. Nothing from the clip is ever used in your videos; this is
+ * measurement, the same way an editor watches a reference and takes notes.
+ */
+import {existsSync, mkdirSync, writeFileSync} from 'node:fs';
+import {basename, extname, join} from 'node:path';
+import {FFMPEG, fmt, median, probe, run, timecode} from './lib/media.mjs';
+
+const args = process.argv.slice(2);
+const positional = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('--')) { i++; continue; }
+  positional.push(args[i]);
+}
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+};
+
+const file = positional[0];
+if (!file || !existsSync(file)) {
+  console.error('Usage: npm run refstyle -- <reference-clip> [--threshold 0.30] [--fps 30]');
+  process.exit(2);
+}
+
+const threshold = Number(flag('threshold', 0.3));
+const fps = Number(flag('fps', 30));
+const info = probe(file);
+if (!info) {
+  console.error('Could not read that file.');
+  process.exit(1);
+}
+
+/* ---------------------------------------------------------------- cuts */
+
+const scene = run(FFMPEG, [
+  '-hide_banner', '-i', file,
+  '-filter_complex', `select='gt(scene,${threshold})',metadata=print:file=-`,
+  '-an', '-f', 'null', '-',
+]);
+
+const cuts = [];
+for (const line of (scene.out + '\n' + scene.err).split('\n')) {
+  const m = /pts_time:([\d.]+)/.exec(line);
+  if (m) {
+    const t = Number(m[1]);
+    if (!cuts.length || t - cuts[cuts.length - 1] > 0.12) cuts.push(Number(t.toFixed(3)));
+  }
+}
+
+const bounds = [0, ...cuts, info.duration];
+const shots = [];
+for (let i = 0; i < bounds.length - 1; i++) {
+  const len = bounds[i + 1] - bounds[i];
+  if (len > 0.05) shots.push({start: bounds[i], end: bounds[i + 1], length: Number(len.toFixed(3))});
+}
+const lengths = shots.map((s) => s.length);
+const cutsPerMinute = info.duration ? (cuts.length / info.duration) * 60 : 0;
+
+/* ---------------------------------------------------------------- colour, one sample per second */
+
+const raw = run(FFMPEG, [
+  '-v', 'error', '-i', file,
+  '-vf', 'fps=1,scale=32:18',
+  '-pix_fmt', 'rgb24', '-f', 'rawvideo', '-',
+], {encoding: 'buffer'});
+
+const pixels = raw.ok ? raw.out : Buffer.alloc(0);
+const perFrame = 32 * 18 * 3;
+const samples = [];
+for (let f = 0; f + perFrame <= pixels.length; f += perFrame) {
+  let r = 0, g = 0, b = 0, lum = 0, sat = 0;
+  const count = 32 * 18;
+  const lums = [];
+  for (let p = 0; p < count; p++) {
+    const i = f + p * 3;
+    const pr = pixels[i], pg = pixels[i + 1], pb = pixels[i + 2];
+    r += pr; g += pg; b += pb;
+    const mx = Math.max(pr, pg, pb);
+    const mn = Math.min(pr, pg, pb);
+    sat += mx ? (mx - mn) / mx : 0;
+    const l = 0.2126 * pr + 0.7152 * pg + 0.0722 * pb;
+    lum += l;
+    lums.push(l);
+  }
+  lums.sort((x, y) => x - y);
+  samples.push({
+    second: samples.length,
+    r: r / count, g: g / count, b: b / count,
+    brightness: lum / count,
+    saturation: sat / count,
+    contrast: (lums[Math.floor(lums.length * 0.95)] - lums[Math.floor(lums.length * 0.05)]) / 255,
+  });
+}
+
+const avg = (key) => (samples.length ? samples.reduce((s, x) => s + x[key], 0) / samples.length : 0);
+const warmth = avg('r') - avg('b'); // positive = warm, negative = cool
+const colour = {
+  r: Math.round(avg('r')), g: Math.round(avg('g')), b: Math.round(avg('b')),
+  brightness: Math.round(avg('brightness')),
+  saturation: Number(avg('saturation').toFixed(3)),
+  contrast: Number(avg('contrast').toFixed(3)),
+  warmth: Number(warmth.toFixed(1)),
+};
+
+/* ---------------------------------------------------------------- pacing over time */
+
+const buckets = [];
+const bucketSize = Math.max(5, Math.round(info.duration / 8));
+for (let t = 0; t < info.duration; t += bucketSize) {
+  const inBucket = shots.filter((s) => s.start >= t && s.start < t + bucketSize);
+  buckets.push({
+    from: t,
+    to: Math.min(t + bucketSize, info.duration),
+    shots: inBucket.length,
+    avgShot: inBucket.length ? Number((inBucket.reduce((a, s) => a + s.length, 0) / inBucket.length).toFixed(2)) : null,
+  });
+}
+
+/* ---------------------------------------------------------------- write */
+
+const name = basename(file, extname(file));
+const dir = join('work', 'refs', name);
+mkdirSync(dir, {recursive: true});
+
+const med = median(lengths);
+const pace = med < 0.8 ? 'very fast' : med < 1.6 ? 'fast' : med < 3 ? 'medium' : 'slow and held';
+const look =
+  `${colour.warmth > 8 ? 'warm' : colour.warmth < -8 ? 'cool' : 'neutral'}, ` +
+  `${colour.saturation > 0.45 ? 'saturated' : colour.saturation < 0.25 ? 'desaturated' : 'moderately saturated'}, ` +
+  `${colour.brightness > 150 ? 'bright' : colour.brightness < 80 ? 'dark' : 'mid-key'}, ` +
+  `${colour.contrast > 0.75 ? 'high contrast' : colour.contrast < 0.45 ? 'soft contrast' : 'normal contrast'}`;
+
+const brief = `# Style brief — ${name}
+
+Measured from the reference, not copied from it. Use it to match energy and look.
+
+## Pacing
+- **Length:** ${fmt(info.duration, 1)}s
+- **Cuts:** ${cuts.length}  (${fmt(cutsPerMinute, 1)} per minute)
+- **Shot length:** median ${fmt(med, 2)}s · shortest ${fmt(Math.min(...lengths, 0), 2)}s · longest ${fmt(Math.max(...lengths, 0), 2)}s
+- **Feel:** ${pace}
+
+| Section | Shots | Average shot |
+|---|---|---|
+${buckets.map((b) => `| ${timecode(b.from)}–${timecode(b.to)} | ${b.shots} | ${b.avgShot ? `${b.avgShot}s` : '—'} |`).join('\n')}
+
+## Colour
+- **Look:** ${look}
+- Average RGB ${colour.r}, ${colour.g}, ${colour.b} · brightness ${colour.brightness}/255
+- Saturation ${colour.saturation} · contrast ${colour.contrast} · warmth ${colour.warmth > 0 ? '+' : ''}${colour.warmth}
+
+## How to match it
+- Cut roughly every **${fmt(med, 2)}s** (${Math.round(med * fps)} frames at ${fps}fps).
+- ${med < 1 ? 'Keep almost every shot under a second; hold only the payoff.' : med < 2 ? 'Most shots under two seconds, with one or two longer holds to breathe.' : 'Let shots breathe; use motion inside the frame instead of cutting.'}
+- ${colour.warmth > 8 ? 'Warm the grade slightly; protect skin from going orange.' : colour.warmth < -8 ? 'Cool the grade slightly; keep skin neutral.' : 'Keep the grade neutral.'}
+- ${colour.saturation > 0.45 ? 'Colour is doing work here — one strong hue can dominate a shot.' : 'Colour is restrained; contrast and framing carry it.'}
+
+## Cut list
+${shots.map((s, i) => `${String(i + 1).padStart(2, '0')}. ${timecode(s.start)} → ${timecode(s.end)}  (${fmt(s.length, 2)}s)`).join('\n')}
+`;
+
+writeFileSync(join(dir, 'style-brief.md'), brief);
+writeFileSync(
+  join(dir, 'style-brief.json'),
+  JSON.stringify({source: file, duration: info.duration, fps: info.fps, cuts, shots, cutsPerMinute, medianShot: med, colour, buckets}, null, 2),
+);
+
+console.log(`${name}: ${cuts.length} cuts, median shot ${fmt(med, 2)}s (${pace}), ${look}`);
+console.log(`Written  ${join(dir, 'style-brief.md')}`);

package/template/scripts/sounddesign.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/**
+ * Sound design pass: turn a cut list into placed, timed, ducked SFX cues.
+ *
+ *   npm run sound -- --cuts <assembly.json|*.trim.json|cuts.json> [--beats <beats.json>]
+ *                    [--words <words.json>] [--project <name>] [--fps 30] [--sfx <dir>]
+ *
+ * Writes work/<project>/sound/:
+ *   SFX-CUES.txt      the numbered, timecoded cue sheet the user rebalances from
+ *   sound-cues.json   the same thing for the composition
+ *   mix.txt           a ready ffmpeg filter_complex: SFX bus, ducked off the voice,
+ *                     high-passed, then the final loudness stage
+ *
+ * The rules come straight from the audio standard in CLAUDE.md, and they are applied,
+ * not suggested: nothing over 0.8s sits under a word unless it is 24 dB down, risers go
+ * in pauses, whooshes lead the picture by TRANSITION.sfxLeadMs, everything is
+ * high-passed off the voice. Claude cannot hear — this engineers the mix so the user
+ * only has to judge taste, not fix collisions.
+ */
+import {existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync} from 'node:fs';
+import {basename, join} from 'node:path';
+import {fmt, timecode} from './lib/media.mjs';
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : fallback;
+};
+
+const cutsPath = flag('cuts', null);
+const beatsPath = flag('beats', null);
+const wordsPath = flag('words', null);
+const project = flag('project', null);
+const fps = Number(flag('fps', 30));
+const sfxDir = flag('sfx', null);
+
+if (!cutsPath || !existsSync(cutsPath)) {
+  console.error('Usage: npm run sound -- --cuts <assembly.json|*.trim.json|cuts.json> [--beats <beats.json>] [--words <words.json>] [--sfx <dir>]');
+  process.exit(2);
+}
+
+/** From src/design/motion.ts — kept in step by hand; these two are the whole contract. */
+const SFX_LEAD = 0.133;
+const SFX_TAIL = 0.267;
+
+/* ---------------------------------------------------------------- read the cut list */
+
+const raw = JSON.parse(readFileSync(cutsPath, 'utf8'));
+let cuts = [];
+let phases = [];
+let source = cutsPath;
+
+if (Array.isArray(raw) && raw.every((n) => typeof n === 'number')) {
+  // scripts/find_cuts.py output: bare frame numbers.
+  cuts = raw.map((f) => ({at: f / fps, kind: 'jump', phase: 'talk'}));
+} else if (raw.shots) {
+  // assembly.json
+  phases = raw.phases || [];
+  cuts = raw.shots
+    .filter((s) => s.transitionIn && s.transitionIn !== 'none')
+    .map((s) => ({at: s.startSeconds, kind: s.transitionIn, phase: s.phase, beats: s.beats}));
+  source = raw.music || cutsPath;
+} else if (raw.punchIns) {
+  // trim.json
+  cuts = raw.punchIns.map((p) => ({at: p.atSeconds, kind: 'punchIn', phase: 'talk'}));
+  source = raw.source || cutsPath;
+} else {
+  console.error('Unrecognised cut list. Expected assembly.json, a .trim.json, or cuts.json.');
+  process.exit(1);
+}
+
+if (!cuts.length) {
+  console.error('That cut list has no cuts in it.');
+  process.exit(1);
+}
+
+/* ---------------------------------------------------------------- speech windows */
+
+let speech = [];
+if (wordsPath && existsSync(wordsPath)) {
+  try {
+    const w = JSON.parse(readFileSync(wordsPath, 'utf8'));
+    speech = (Array.isArray(w) ? w : w.words || [])
+      .filter((x) => Number.isFinite(x.start) && Number.isFinite(x.end))
+      .map((x) => ({start: Number(x.start), end: Number(x.end)}));
+  } catch {
+    console.error(`Could not read ${wordsPath} — placing cues without voice awareness.`);
+  }
+} else if (raw.keep) {
+  // A trim list already tells us exactly where the voice is.
+  speech = raw.keep.map((k) => ({start: k.atSeconds, end: k.atSeconds + k.seconds}));
+}
+
+const underVoice = (from, to) => speech.some((s) => from < s.end && to > s.start);
+/** Nearest gap in the voice, within reach, so a riser can move instead of being dropped. */
+const nearestGap = (t, need) => {
+  for (let shift = 0; shift <= 0.25; shift += 0.02) {
+    for (const cand of [t - shift, t + shift]) {
+      if (cand >= 0 && !underVoice(cand, cand + need)) return Number(cand.toFixed(3));
+    }
+  }
+  return null;
+};
+
+/* ---------------------------------------------------------------- beats, drop, bars */
+
+let beats = null;
+let dropAt = null;
+let barSeconds = null;
+if (beatsPath && existsSync(beatsPath)) {
+  beats = JSON.parse(readFileSync(beatsPath, 'utf8'));
+  const db = beats.downbeatSeconds || [];
+  if (db.length > 1) barSeconds = db[1] - db[0];
+}
+const dropPhase = phases.find((p) => p.name === 'drop');
+if (dropPhase) dropAt = dropPhase.fromSeconds;
+
+/* ---------------------------------------------------------------- the cue rules */
+
+/**
+ * Each cue type carries its own shape. Durations are the top of the range in the audio
+ * standard; gains are relative to the music bus, before ducking.
+ */
+const TYPES = {
+  whoosh: {durationMs: 600, gainDb: -8, highpassHz: 140, fadeOutMs: 90, note: 'movement — leads the picture'},
+  impact: {durationMs: 450, gainDb: -6, highpassHz: 120, fadeOutMs: 70, note: 'lands on the cut'},
+  riser: {durationMs: 2000, gainDb: -10, highpassHz: 180, fadeOutMs: 120, note: 'tension into a change — pauses only'},
+  sub: {durationMs: 800, gainDb: -7, highpassHz: 30, fadeOutMs: 120, note: 'weight under the drop'},
+  tick: {durationMs: 120, gainDb: -18, highpassHz: 400, fadeOutMs: 40, note: 'text arriving'},
+};
+
+const cues = [];
+const moved = [];
+const dropped = [];
+let dropCuts = 0;
+
+const add = (type, at, reason, extra = {}) => {
+  const spec = TYPES[type];
+  const need = spec.durationMs / 1000;
+  let start = Number(at.toFixed(3));
+  let gainDb = spec.gainDb;
+  let durationMs = spec.durationMs;
+  let placement = 'clear';
+
+  if (speech.length && underVoice(start, start + need)) {
+    if (type === 'riser' || type === 'sub') {
+      // Long, tonal, and unmissable under a word — the exact mistake that broke an early video.
+      const gap = nearestGap(start, need);
+      if (gap === null) {
+        dropped.push({type, at: start, reason: 'no gap in the voice long enough — add it by hand or shorten the VO'});
+        return;
+      }
+      moved.push({type, from: start, to: gap});
+      start = gap;
+    } else {
+      // Short cues may stay, but only well under the voice, and trimmed to the motion.
+      durationMs = Math.min(durationMs, 800);
+      gainDb = Math.min(gainDb, -24);
+      placement = 'under voice — trimmed and 24 dB down';
+    }
+  }
+
+  cues.push({
+    n: cues.length + 1,
+    type,
+    atSeconds: start,
+    atFrame: Math.round(start * fps),
+    timecode: timecode(start),
+    durationMs,
+    gainDb,
+    highpassHz: spec.highpassHz,
+    fadeOutMs: spec.fadeOutMs,
+    placement,
+    reason,
+    ...extra,
+  });
+};
+
+/** Whooshes lead the picture; impacts land on it. Which one depends on what the cut is. */
+for (const cut of cuts) {
+  if (cut.kind === 'whipPan' || cut.kind === 'push' || cut.kind === 'punchIn') {
+    add('whoosh', Math.max(0, cut.at - SFX_LEAD), `${cut.kind} at ${timecode(cut.at)}`);
+  } else if (cut.kind === 'colourFlip' || cut.kind === 'dip') {
+    add('impact', cut.at, `${cut.kind} at ${timecode(cut.at)}`);
+  } else if (cut.kind === 'jump') {
+    add('whoosh', Math.max(0, cut.at - SFX_LEAD), `jump cut at ${timecode(cut.at)} — the zoom needs a sound`);
+  } else if (cut.phase === 'drop') {
+    // A sound on every cut through the drop is noise, and silence through it is worse.
+    // Accent every third, so the section has a pulse without turning into a drum fill.
+    if (dropCuts++ % 3 === 0) add('impact', cut.at, 'accent on the drop');
+  }
+}
+
+/** The riser goes two bars before the drop, the sub lands on it. */
+if (dropAt !== null) {
+  const lead = barSeconds ? barSeconds * 2 : 2;
+  add('riser', Math.max(0, dropAt - lead), 'two bars into the drop');
+  add('sub', dropAt, 'the drop itself');
+}
+
+/** Text arriving gets a tick, but only where nothing else is already happening. */
+if (speech.length && raw.shots) {
+  for (const s of speech.slice(0, 40)) {
+    const clash = cues.some((c) => Math.abs(c.atSeconds - s.start) < 0.25);
+    if (!clash) add('tick', s.start, 'text lands on this word');
+  }
+}
+
+cues.sort((a, b) => a.atSeconds - b.atSeconds);
+cues.forEach((c, i) => {
+  c.n = i + 1;
+});
+
+/* ---------------------------------------------------------------- match real files */
+
+let library = {};
+if (sfxDir && existsSync(sfxDir)) {
+  // Real SFX libraries are folders of folders ("Whooshs", "Risers", "Impacts"), so walk
+  // the whole tree and match on the full relative path — the folder name is usually the
+  // only thing that says what a file is.
+  const walk = (dir) =>
+    readdirSync(dir, {withFileTypes: true}).flatMap((e) => {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) return walk(p);
+      return /\.(wav|mp3|aif|aiff|flac|m4a)$/i.test(e.name) ? [p] : [];
+    });
+  const files = walk(sfxDir);
+  const pick = (re) => files.filter((f) => re.test(f));
+  library = {
+    whoosh: pick(/whoosh|swoosh|swish|transition/i),
+    impact: pick(/impact|hit|boom|thud|punch/i),
+    riser: pick(/riser|rise|build|uplift/i),
+    sub: pick(/sub|drop|bass|808/i),
+    tick: pick(/tick|click|pop|blip|ui/i),
+  };
+  for (const c of cues) {
+    const pool = library[c.type] || [];
+    if (pool.length) c.file = pool[(c.n - 1) % pool.length];
+  }
+}
+
+/* ---------------------------------------------------------------- the mix */
+
+const placed = cues.filter((c) => c.file);
+const mixLines = [];
+mixLines.push('# SFX bus — one input per cue, trimmed, high-passed, faded, delayed into place.');
+mixLines.push('# Inputs: 0 = voice/picture audio, 1 = music, 2.. = the SFX files below, in cue order.');
+mixLines.push('');
+if (placed.length) {
+  const parts = placed.map((c, i) => {
+    const idx = i + 2;
+    const delayMs = Math.round(c.atSeconds * 1000);
+    return `[${idx}:a]atrim=0:${fmt(c.durationMs / 1000, 3)},highpass=f=${c.highpassHz},afade=t=out:st=${fmt((c.durationMs - c.fadeOutMs) / 1000, 3)}:d=${fmt(c.fadeOutMs / 1000, 3)},volume=${c.gainDb}dB,adelay=${delayMs}|${delayMs}[s${i}]`;
+  });
+  mixLines.push(`${parts.join(';\n')};`);
+  mixLines.push('');
+  mixLines.push(`${placed.map((_, i) => `[s${i}]`).join('')}amix=inputs=${placed.length}:normalize=0[sfxraw];`);
+  mixLines.push('[sfxraw]alimiter=limit=0.9[sfx];');
+  mixLines.push('# Duck the SFX bus off the voice, then sit it under the music.');
+  mixLines.push('[sfx][0:a]sidechaincompress=threshold=0.04:ratio=6:attack=8:release=260[sfxducked];');
+  mixLines.push('[1:a][sfxducked]amix=inputs=2:normalize=0[bed];');
+  mixLines.push('[0:a][bed]amix=inputs=2:normalize=0[mixout]');
+  mixLines.push('');
+  mixLines.push('# Final stage — one encode, per the audio standard:');
+  mixLines.push('#   -map "[mixout]" -af "loudnorm=I=-14:TP=-1:LRA=11:print_format=summary" -c:a aac -b:a 256k');
+  mixLines.push('# Stems: render voice.wav (untouched), sfx.wav ([sfx] before ducking), music.wav separately.');
+} else {
+  mixLines.push('# No --sfx directory given, so no files are wired up yet.');
+  mixLines.push('# Point --sfx at a folder with whoosh*/impact*/riser*/sub*/tick* files and run again.');
+}
+
+/* ---------------------------------------------------------------- write */
+
+const dir = join('work', project || basename(cutsPath).replace(/\..*$/, ''), 'sound');
+mkdirSync(dir, {recursive: true});
+
+const json = {
+  source,
+  cutList: cutsPath,
+  fps,
+  sfxLeadSeconds: SFX_LEAD,
+  sfxTailSeconds: SFX_TAIL,
+  voiceAware: speech.length > 0,
+  cues,
+  moved,
+  dropped,
+};
+writeFileSync(join(dir, 'sound-cues.json'), JSON.stringify(json, null, 2));
+writeFileSync(join(dir, 'mix.txt'), `${mixLines.join('\n')}\n`);
+
+const sheet = `SFX CUES — ${basename(String(source))}
+${'='.repeat(60)}
+Cut list   ${cutsPath}
+Voice      ${speech.length ? `${speech.length} spoken windows — cues are placed around them` : 'not supplied — cues are NOT voice-aware, check every one under speech'}
+Lead       whooshes start ${Math.round(SFX_LEAD * 1000)}ms before the picture changes
+
+ #   TIME     FRAME  TYPE    LEN    GAIN   HPF     WHY
+${cues
+  .map(
+    (c) =>
+      `${String(c.n).padStart(2, '0')}   ${c.timecode}    ${String(c.atFrame).padStart(5)}  ${c.type.padEnd(7)} ${String(c.durationMs).padStart(4)}ms ${String(c.gainDb).padStart(4)}dB ${String(c.highpassHz).padStart(4)}Hz  ${c.reason}${c.placement !== 'clear' ? ` [${c.placement}]` : ''}${c.file ? `\n                                                  file: ${basename(c.file)}` : ''}`,
+  )
+  .join('\n')}
+
+${moved.length ? `MOVED (would have played under a word)\n${moved.map((m) => `- ${m.type}: ${timecode(m.from)} → ${timecode(m.to)}`).join('\n')}\n` : ''}${dropped.length ? `DROPPED (nowhere clear to put them)\n${dropped.map((d) => `- ${d.type} at ${timecode(d.at)} — ${d.reason}`).join('\n')}\n` : ''}
+HOW THIS WAS BUILT
+- Whooshes lead the picture, impacts land on it, risers only go in pauses.
+- Nothing longer than 0.8s sits under a word unless it is at least 24 dB down.
+- Everything is high-passed off the voice (120-180Hz), except the sub.
+- The SFX bus is ducked off the voice with sidechaincompress — see mix.txt.
+
+BEFORE DELIVERY
+- Measure: voice-vs-mix per 0.5s window; fix any window where SFX is within 12 dB of the voice.
+- Final: -14 LUFS integrated, true peak <= -1 dBTP, one AAC encode at 256k.
+- Ship voice.wav + sfx.wav + this sheet alongside the MP4.
+
+Claude cannot hear any of this. Listen once and send timecoded notes.
+`;
+writeFileSync(join(dir, 'SFX-CUES.txt'), sheet);
+
+const byType = Object.keys(TYPES)
+  .map((t) => `${cues.filter((c) => c.type === t).length} ${t}`)
+  .filter((s) => !s.startsWith('0 '))
+  .join(', ');
+
+console.log(`Cues       ${cues.length} (${byType})`);
+console.log(`Voice      ${speech.length ? `${speech.length} spoken windows — cues placed around them` : 'not supplied — cues are not voice-aware'}`);
+if (moved.length) console.log(`Moved      ${moved.length} cue(s) out from under the voice`);
+if (dropped.length) console.log(`Dropped    ${dropped.length} cue(s) with nowhere clear to sit`);
+console.log(`Files      ${placed.length ? `${placed.length} matched from ${sfxDir}` : 'none matched — pass --sfx <dir> to wire real files'}`);
+console.log(`Written    ${join(dir, 'SFX-CUES.txt')}`);
+console.log('\nThe mix is engineered, not guessed — but only you can hear it. Listen once, send timecodes.');

package/template/scripts/stills.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Render many stills of a composition from one bundle, then tile them into contact sheets for review.
+ *
+ *   node scripts/stills.mjs <CompositionId> [--every=45] [--from=0] [--to=<last>] [--frames=10,200]
+ *                           [--scale=0.4] [--cols=8] [--out=work/stills/<id>]
+ *
+ * Writes s000.jpg, s001.jpg... , sheet-0.jpg, sheet-1.jpg... (cols x 2 per sheet) and frames.txt.
+ */
+import {bundle} from '@remotion/bundler';
+import {getCompositions, openBrowser, renderStill} from '@remotion/renderer';
+import {spawnSync} from 'node:child_process';
+import {mkdirSync, rmSync, writeFileSync} from 'node:fs';
+import {join, resolve} from 'node:path';
+
+const FFMPEG = 'D:\\Tools\\ffmpeg\\bin\\ffmpeg.exe';
+
+const args = process.argv.slice(2);
+const id = args.find((a) => !a.startsWith('--'));
+const opt = (name) => args.find((a) => a.startsWith(`--${name}=`))?.split('=')[1];
+if (!id) {
+  console.error('Usage: node scripts/stills.mjs <CompositionId> [--every=45] [--frames=a,b,c] [--scale=0.4]');
+  process.exit(2);
+}
+const scale = Number(opt('scale') ?? 0.4);
+const cols = Number(opt('cols') ?? 8);
+const out = opt('out') ?? join('work', 'stills', id);
+rmSync(out, {recursive: true, force: true});
+mkdirSync(out, {recursive: true});
+
+const serveUrl = await bundle({entryPoint: resolve('src/index.ts'), publicDir: resolve('assets')});
+const comp = (await getCompositions(serveUrl)).find((c) => c.id === id);
+if (!comp) throw new Error(`No composition ${id}`);
+
+let frames;
+if (opt('frames')) {
+  frames = opt('frames').split(',').map(Number);
+} else {
+  frames = [];
+  const every = Number(opt('every') ?? 45);
+  const to = Number(opt('to') ?? comp.durationInFrames - 1);
+  for (let f = Number(opt('from') ?? 0); f <= to; f += every) frames.push(f);
+}
+
+const browser = await openBrowser('chrome');
+for (const [i, frame] of frames.entries()) {
+  const name = `s${String(i).padStart(3, '0')}.jpg`;
+  await renderStill({composition: comp, serveUrl, frame, output: join(out, name), imageFormat: 'jpeg', scale, puppeteerInstance: browser});
+  process.stdout.write(`${frame} `);
+}
+writeFileSync(join(out, 'frames.txt'), frames.map((f, i) => `s${String(i).padStart(3, '0')} = frame ${f}`).join('\n'));
+
+const perSheet = cols * 2;
+for (let s = 0; s * perSheet < frames.length; s++) {
+  spawnSync(
+    FFMPEG,
+    ['-y', '-loglevel', 'error', '-start_number', String(s * perSheet), '-i', join(out, 's%03d.jpg'), '-frames:v', '1', '-vf', `tile=${cols}x2:padding=6:color=black`, join(out, `sheet-${s}.jpg`)],
+    {stdio: 'inherit'},
+  );
+}
+await browser.close({silent: true});
+// The bundle holds a full copy of assets/ (cutouts are GBs) — never leave it behind.
+rmSync(serveUrl, {recursive: true, force: true});
+console.log(`\n${frames.length} stills and ${Math.ceil(frames.length / perSheet)} sheets -> ${out}`);