creator-editing-studio 1.0.20260930

package/template/scripts/beats.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * Beat map for a music track, so cuts can land on the beat.
+ *
+ *   npm run beats -- <audio-or-video> [--project <name>] [--min 60] [--max 190]
+ *
+ * Writes work/<project>/beats.json (or next to the file) with:
+ *   bpm, beatSeconds, downbeatSeconds, onsetSeconds, and the same in frames at 25/30/60fps.
+ *
+ * How it works: spectral flux gives an onset strength curve, autocorrelation of that curve
+ * gives the tempo, then we slide a grid at that tempo to the phase that lands on the most
+ * energy. No Python, no model — just ffmpeg and maths.
+ */
+import {existsSync, mkdirSync, writeFileSync} from 'node:fs';
+import {basename, extname, join} from 'node:path';
+import {decodePcm, fmt, median, onsetEnvelope, probe} from './lib/media.mjs';
+
+const args = process.argv.slice(2);
+const file = args.find((a) => !a.startsWith('--'));
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+};
+
+if (!file || !existsSync(file)) {
+  console.error('Usage: npm run beats -- <audio-or-video> [--project <name>] [--min 60] [--max 190]');
+  process.exit(2);
+}
+
+const RATE = 22050;
+const minBpm = Number(flag('min', 60));
+const maxBpm = Number(flag('max', 190));
+const project = flag('project', null);
+
+const info = probe(file);
+const samples = decodePcm(file, RATE);
+if (!samples || samples.length < RATE) {
+  console.error('No usable audio in that file.');
+  process.exit(1);
+}
+
+const {env, hopSeconds} = onsetEnvelope(samples, RATE);
+
+// Smooth a little, then subtract a moving median so a loud section doesn't hide the beats in a quiet one.
+const smooth = new Float64Array(env.length);
+for (let i = 0; i < env.length; i++) {
+  smooth[i] = (env[Math.max(0, i - 1)] + env[i] + env[Math.min(env.length - 1, i + 1)]) / 3;
+}
+const detrended = new Float64Array(env.length);
+const W = Math.round(0.5 / hopSeconds);
+for (let i = 0; i < smooth.length; i++) {
+  const from = Math.max(0, i - W);
+  const to = Math.min(smooth.length, i + W);
+  detrended[i] = Math.max(0, smooth[i] - median(Array.from(smooth.slice(from, to))));
+}
+
+/* ---------------------------------------------------------------- tempo */
+
+const lagFor = (bpm) => Math.round(60 / bpm / hopSeconds);
+const minLag = lagFor(maxBpm);
+const maxLag = lagFor(minBpm);
+let bestLag = minLag;
+let bestScore = -1;
+const scores = [];
+for (let lag = minLag; lag <= maxLag; lag++) {
+  let sum = 0;
+  for (let i = 0; i + lag < detrended.length; i++) sum += detrended[i] * detrended[i + lag];
+  const score = sum / (detrended.length - lag);
+  scores.push({lag, score});
+  if (score > bestScore) {
+    bestScore = score;
+    bestLag = lag;
+  }
+}
+
+/**
+ * Autocorrelation alone confuses a tempo with its half and double. Settle it by
+ * laying each candidate grid over the actual hits and keeping the one that lands on them.
+ */
+const phaseFor = (lag) => {
+  let phase = 0;
+  let best = -1;
+  for (let p = 0; p < lag; p++) {
+    let sum = 0;
+    for (let i = p; i < detrended.length; i += lag) sum += detrended[i];
+    if (sum > best) {
+      best = sum;
+      phase = p;
+    }
+  }
+  return phase;
+};
+
+const peakForOnsets = Math.max(...detrended);
+const onsetIdx = [];
+for (let i = 1; i < detrended.length - 1; i++) {
+  if (detrended[i] > peakForOnsets * 0.18 && detrended[i] >= detrended[i - 1] && detrended[i] > detrended[i + 1]) {
+    if (!onsetIdx.length || (i - onsetIdx[onsetIdx.length - 1]) * hopSeconds > 0.09) onsetIdx.push(i);
+  }
+}
+
+const duration = info?.duration || samples.length / RATE;
+const TOL = 0.07;
+const onsetTimes = onsetIdx.map((i) => i * hopSeconds);
+
+/**
+ * Least-squares fit of period and phase to the onsets a grid already lands on.
+ * The analysis hop is ~23ms, so an integer lag can only ever approximate the real
+ * period — which matters twice: it drifts across a long track, and (worse) it makes a
+ * true period that falls between two hops score lower than its own double, which may sit
+ * exactly on one. Refine before comparing, or the tempo comes back halved.
+ */
+const refit = (periodSeconds, phaseSeconds) => {
+  const xs = [];
+  const ys = [];
+  for (const t of onsetTimes) {
+    const k = Math.round((t - phaseSeconds) / periodSeconds);
+    if (Math.abs(t - (phaseSeconds + k * periodSeconds)) <= TOL) {
+      xs.push(k);
+      ys.push(t);
+    }
+  }
+  if (xs.length < 4) return {period: periodSeconds, phase: phaseSeconds};
+  const n = xs.length;
+  const sx = xs.reduce((a, b) => a + b, 0);
+  const sy = ys.reduce((a, b) => a + b, 0);
+  const sxx = xs.reduce((a, b) => a + b * b, 0);
+  const sxy = xs.reduce((a, b, i) => a + b * ys[i], 0);
+  const denom = n * sxx - sx * sx;
+  if (denom === 0) return {period: periodSeconds, phase: phaseSeconds};
+  const slope = (n * sxy - sx * sy) / denom;
+  let intercept = (sy - slope * sx) / n;
+  if (!(slope > 0.2 && slope < 2)) return {period: periodSeconds, phase: phaseSeconds};
+  while (intercept - slope >= 0) intercept -= slope;
+  return {period: slope, phase: intercept};
+};
+
+/**
+ * One pass only refines what it already matches, so a seed that is 2% out drifts past the
+ * tolerance after a few beats and the fit gives up on its own. Iterating lets each pass
+ * match more of the track than the last, until the period stops moving.
+ */
+const refitToConvergence = (periodSeconds, phaseSeconds, passes = 6) => {
+  let p = periodSeconds;
+  let ph = phaseSeconds;
+  for (let i = 0; i < passes; i++) {
+    const next = refit(p, ph);
+    if (Math.abs(next.period - p) < 1e-5) return next;
+    p = next.period;
+    ph = next.phase;
+  }
+  return {period: p, phase: ph};
+};
+
+const onsetSorted = [...onsetTimes].sort((a, b) => a - b);
+const onsetNear = (t) => {
+  let lo = 0;
+  let hi = onsetSorted.length - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (onsetSorted[mid] < t) lo = mid + 1;
+    else hi = mid;
+  }
+  return (
+    (onsetSorted[lo] !== undefined && Math.abs(onsetSorted[lo] - t) <= TOL) ||
+    (onsetSorted[lo - 1] !== undefined && Math.abs(onsetSorted[lo - 1] - t) <= TOL)
+  );
+};
+
+/** Reward grids that land on hits, punish grids with lots of empty beats. */
+const scoreGrid = (period, phase) => {
+  let hit = 0;
+  let grid = 0;
+  for (let t = phase; t <= duration; t += period) {
+    grid++;
+    if (onsetNear(t)) hit++;
+  }
+  if (!grid) return -1;
+  return hit / onsetTimes.length - 0.35 * (1 - hit / grid);
+};
+
+/**
+ * A candidate period can only be a whole analysis hop (~23ms), which at 120 BPM is a 2%
+ * error — enough that the grid walks off the beat within a few bars and scores worse than
+ * its own half, whose longer period happens to divide the hop more cleanly. That is how a
+ * tempo comes back halved. So search a continuous window around each candidate instead of
+ * trusting the integer lag, and let the best (period, phase) pair represent it.
+ */
+const gridScore = (lag) => {
+  const seed = lag * hopSeconds;
+  const span = seed * 0.05;
+  const step = seed * 0.002;
+  let best = {lag, period: seed, phase: 0, score: -1};
+  for (let p = seed - span; p <= seed + span; p += step) {
+    if (p <= 0) continue;
+    for (let ph = 0; ph < p; ph += 0.01) {
+      const score = scoreGrid(p, ph);
+      if (score > best.score) best = {lag, period: p, phase: ph, score};
+    }
+  }
+  // Now that the period is close, the beat-index correspondence is right and the fit lands.
+  const fitted = refitToConvergence(best.period, best.phase);
+  const fittedScore = scoreGrid(fitted.period, fitted.phase);
+  return fittedScore >= best.score ? {lag, ...fitted, score: fittedScore} : best;
+};
+
+/**
+ * Autocorrelation is one opinion about the tempo; the spacing between the hits themselves
+ * is another, and it is the one that survives a track whose strongest periodicity is not
+ * its beat. Offer both — plus each one's half and double — and let the grid score decide.
+ */
+const gaps = [];
+for (let i = 1; i < onsetTimes.length; i++) gaps.push(onsetTimes[i] - onsetTimes[i - 1]);
+const gapLag = gaps.length ? Math.max(1, Math.round(median(gaps) / hopSeconds)) : bestLag;
+
+const candidates = [...new Set([Math.round(bestLag / 2), bestLag, bestLag * 2, Math.round(gapLag / 2), gapLag, gapLag * 2])]
+  .filter((lag) => lag >= minLag && lag <= maxLag)
+  .map(gridScore);
+const chosen = candidates.reduce((best, c) => (c.score > best.score ? c : best), candidates[0]);
+bestLag = chosen.lag;
+
+// One more fit on the winner, so beat 400 is as accurate as beat 4.
+const {period: beatPeriod, phase: phaseSeconds} = refitToConvergence(chosen.period, chosen.phase);
+const bpm = 60 / beatPeriod;
+
+const beats = [];
+for (let t = phaseSeconds; t <= duration; t += beatPeriod) beats.push(Number(t.toFixed(3)));
+
+// Downbeats: the strongest of every four beats decides where bar one starts.
+let barPhase = 0;
+let barScore = -1;
+for (let p = 0; p < 4; p++) {
+  let sum = 0;
+  for (let i = p; i < beats.length; i += 4) {
+    const idx = Math.round(beats[i] / hopSeconds);
+    sum += detrended[idx] || 0;
+  }
+  if (sum > barScore) {
+    barScore = sum;
+    barPhase = p;
+  }
+}
+const downbeats = beats.filter((_, i) => (i - barPhase) % 4 === 0);
+
+/* ---------------------------------------------------------------- onsets (hits, not grid) */
+
+const onsets = onsetIdx.map((i) => Number((i * hopSeconds).toFixed(3)));
+
+/* ---------------------------------------------------------------- write */
+
+const frames = (list, fps) => list.map((t) => Math.round(t * fps));
+const out = {
+  source: file,
+  durationSeconds: Number(duration.toFixed(3)),
+  bpm: Number(bpm.toFixed(2)),
+  beatSeconds: beats,
+  downbeatSeconds: downbeats,
+  onsetSeconds: onsets,
+  frames: {25: frames(beats, 25), 30: frames(beats, 30), 60: frames(beats, 60)},
+  downbeatFrames: {25: frames(downbeats, 25), 30: frames(downbeats, 30), 60: frames(downbeats, 60)},
+};
+
+const dir = project ? join('work', project) : join('work', 'beats');
+mkdirSync(dir, {recursive: true});
+const outPath = join(dir, `${basename(file, extname(file))}.beats.json`);
+writeFileSync(outPath, JSON.stringify(out, null, 2));
+
+console.log(`Tempo      ${fmt(bpm, 1)} BPM  (beat every ${fmt(beatPeriod, 3)}s)`);
+console.log(`Beats      ${beats.length}`);
+console.log(`Downbeats  ${downbeats.length} (bar starts at ${fmt(downbeats[0] ?? 0, 2)}s)`);
+console.log(`Hits       ${onsets.length} onsets`);
+console.log(`Written    ${outPath}`);
+console.log('\nCut on downbeats for a calm edit, on beats for a fast one, on hits for accents.');

package/template/scripts/blur_regions.py

@@ -0,0 +1,40 @@
+"""Bake blurred regions (brand names, logos, personal names) into copies of screenshots.
+
+Usage (from the project root):
+    python scripts/blur_regions.py assets/projects/<video>/screenshots/blur-regions.json
+
+JSON: {"<source file next to the json>": {"out": "<name>.png", "regions": [[x0, y0, x1, y1], ...]}}
+Coordinates are in the source image's own pixels. Outputs go to the sibling processed/ folder
+(assets/projects/<video>/processed/).
+Blurring is baked in (not done live) so it is identical on every frame and costs nothing to render.
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFilter
+
+def main() -> None:
+    config_path = Path(sys.argv[1])
+    config = json.load(open(config_path, encoding="utf-8"))
+    SRC = config_path.parent
+    OUT = SRC.parent / "processed"
+    OUT.mkdir(parents=True, exist_ok=True)
+    for source, spec in config.items():
+        image = Image.open(SRC / source).convert("RGB")
+        for x0, y0, x1, y1 in spec["regions"]:
+            box = (x0, y0, x1, y1)
+            patch = image.crop(box)
+            # Pixelate then blur: shapes of bold wordmarks stay unreadable even when zoomed in.
+            small = patch.resize((max(1, (x1 - x0) // 16), max(1, (y1 - y0) // 16)), Image.BILINEAR)
+            patch = small.resize(patch.size, Image.BILINEAR).filter(ImageFilter.GaussianBlur(radius=9))
+            mask = Image.new("L", patch.size, 0)
+            ImageDraw.Draw(mask).rounded_rectangle((0, 0, patch.size[0] - 1, patch.size[1] - 1), radius=min(patch.size) // 3, fill=255)
+            image.paste(patch, box, mask.filter(ImageFilter.GaussianBlur(radius=2)))
+        image.save(OUT / spec["out"], optimize=True)
+        print(f"{source} -> {OUT / spec['out']} ({len(spec['regions'])} regions)")
+
+
+if __name__ == "__main__":
+    main()

package/template/scripts/check_pair.py

@@ -0,0 +1,90 @@
+"""Check that a green-screen clip is frame-aligned with its original.
+
+Usage (from the project root):
+    python scripts/check_pair.py <original> <greenscreen> [--samples 7]
+
+At several points through the clip, compares the subject pixels of green-screen frame K with
+original frames K-2..K+2. The offset with the smallest difference is the alignment; it must be the
+same at every sample (otherwise the clips drift).
+"""
+
+import argparse
+import json
+import subprocess
+
+import numpy as np
+import sys as _sys, pathlib as _pl
+_sys.path.insert(0, str(_pl.Path(__file__).resolve().parent / 'lib'))
+from media import FFMPEG, FFPROBE  # resolved per platform - never hardcode a tool path
+
+
+
+
+OFFSETS = range(-2, 3)
+
+
+def probe(path):
+    out = subprocess.run(
+        [FFPROBE, "-v", "error", "-select_streams", "v:0", "-count_frames",
+         "-show_entries", "stream=width,height,r_frame_rate,nb_read_frames", "-of", "json", path],
+        capture_output=True, text=True, check=True,
+    )
+    s = json.loads(out.stdout)["streams"][0]
+    num, den = s["r_frame_rate"].split("/")
+    return int(s["width"]), int(s["height"]), float(num) / float(den), int(s["nb_read_frames"])
+
+
+def frames(path, start, count, width, height, fps):
+    out = subprocess.run(
+        [FFMPEG, "-v", "error", "-ss", f"{start / fps:.6f}", "-i", path, "-frames:v", str(count),
+         "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+        capture_output=True, check=True,
+    )
+    data = np.frombuffer(out.stdout, dtype=np.uint8)
+    return data.reshape(-1, height, width, 3).astype(np.float32)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("original")
+    parser.add_argument("greenscreen")
+    parser.add_argument("--samples", type=int, default=7)
+    args = parser.parse_args()
+
+    w1, h1, fps1, n1 = probe(args.original)
+    w2, h2, fps2, n2 = probe(args.greenscreen)
+    print(f"original:    {w1}x{h1} @ {fps1:.3f}fps, {n1} frames")
+    print(f"greenscreen: {w2}x{h2} @ {fps2:.3f}fps, {n2} frames")
+    if (w1, h1) != (w2, h2) or abs(fps1 - fps2) > 1e-3:
+        print("MISMATCH: resolution or frame rate differ")
+        return
+
+    last = min(n1, n2) - 3
+    points = np.linspace(3, last, args.samples).astype(int)
+    results = []
+    for k in points:
+        green = frames(args.greenscreen, k, 1, w2, h2, fps2)[0]
+        r, g, b = green[..., 0], green[..., 1], green[..., 2]
+        background = (g > 120) & (g > r * 1.35) & (g > b * 1.35)
+        subject = ~background
+        # Erode the subject mask so blended edge pixels don't bias the comparison.
+        for _ in range(4):
+            subject = subject & np.roll(subject, 1, 0) & np.roll(subject, -1, 0) & np.roll(subject, 1, 1) & np.roll(subject, -1, 1)
+        coverage = subject.mean()
+        originals = frames(args.original, k + OFFSETS.start, len(OFFSETS), w1, h1, fps1)
+        diffs = {off: float(np.abs(originals[i][subject] - green[subject]).mean()) for i, off in enumerate(OFFSETS) if i < len(originals)}
+        best = min(diffs, key=diffs.get)
+        results.append(best)
+        pretty = "  ".join(f"{off:+d}:{d:5.2f}" for off, d in diffs.items())
+        print(f"frame {k:5d} ({k / fps1:6.2f}s) subject {coverage:5.1%}  best offset {best:+d}   [{pretty}]")
+
+    if len(set(results)) == 1:
+        off = results[0]
+        print(f"\nRESULT: aligned with a constant offset of {off:+d} frame(s)"
+              + (" — perfect." if off == 0 else " — shift the green-screen clip to match."))
+    else:
+        print(f"\nRESULT: offsets vary {sorted(set(results))} — clips drift; re-export both from the same timeline.")
+
+
+if __name__ == "__main__":
+    main()

package/template/scripts/doctor.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * Does this machine actually have everything the studio claims to do?
+ *
+ *   npm run doctor
+ *
+ * This exists because a working setup went quiet. WhisperX had been installed and used
+ * (there are words.json files from a fortnight earlier), then the Python environment
+ * underneath it was emptied, and nothing noticed until a job needed a transcript. The
+ * code was fine the whole time. The environment was not, and there was no way to tell
+ * except by running something and watching it fail.
+ *
+ * So this checks CAPABILITIES rather than files: it runs the binaries, imports the
+ * modules, and reports what you can and cannot do right now. A capability that is
+ * missing is reported with the command that fixes it, because "not installed" with no
+ * next step is what turns a five-minute problem into a phone call.
+ *
+ * Exit code is 0 when everything the studio needs for a render is present, 1 when
+ * something core is broken. Optional pieces report but never fail the run.
+ */
+import {execFileSync} from 'node:child_process';
+import {existsSync, readdirSync} from 'node:fs';
+import {join, dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+// fileURLToPath, not URL.pathname: a path with a space in it comes back percent-encoded
+// from pathname, so every existsSync below silently answers false and the report claims
+// a working studio is broken.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const VENV = process.platform === 'win32'
+  ? join(ROOT, '.venv', 'Scripts', 'python.exe')
+  : join(ROOT, '.venv', 'bin', 'python');
+
+const results = [];
+const record = (area, name, ok, detail, fix, core = true) =>
+  results.push({area, name, ok, detail, fix, core});
+
+const tryRun = (bin, args, pick = (s) => s.trim().split('\n')[0]) => {
+  try {
+    return {ok: true, out: pick(execFileSync(bin, args, {encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']}))};
+  } catch (e) {
+    return {ok: false, out: (e.stderr || e.message || '').toString().trim().split('\n')[0]};
+  }
+};
+
+/* ------------------------------------------------------------------ the engine */
+const node = process.versions.node;
+const nodeMajor = Number(node.split('.')[0]);
+record('engine', 'Node', nodeMajor >= 20, `v${node}`, 'Install the LTS build from nodejs.org');
+
+const hasModules = existsSync(join(ROOT, 'node_modules', 'remotion'));
+const pkgCount = existsSync(join(ROOT, 'node_modules')) ? readdirSync(join(ROOT, 'node_modules')).length : 0;
+record('engine', 'Video engine', hasModules, hasModules ? `${pkgCount} packages` : 'node_modules/remotion missing', 'npm install');
+
+/* ------------------------------------------------------------- media handling */
+let FFMPEG = 'ffmpeg', FFPROBE = 'ffprobe';
+try {
+  const media = await import('./lib/media.mjs');
+  FFMPEG = media.FFMPEG;
+  FFPROBE = media.FFPROBE;
+} catch { /* fall back to PATH and let the run below report it */ }
+
+for (const [name, bin] of [['ffmpeg', FFMPEG], ['ffprobe', FFPROBE]]) {
+  const r = tryRun(bin, ['-version']);
+  record('media', name, r.ok, r.ok ? r.out.split(' ').slice(0, 3).join(' ') : 'not runnable',
+    'Set $FFMPEG / $FFPROBE, or install ffmpeg so it is on PATH');
+}
+
+/* ------------------------------------------------------ the transcriber (optional) */
+const venvOk = existsSync(VENV);
+record('transcriber', 'Python 3.11/3.12 venv', venvOk, venvOk ? VENV.replace(ROOT, '.') : '.venv missing',
+  'py -3.12 -m venv .venv   (3.13+ will not build WhisperX)', false);
+
+if (venvOk) {
+  const ver = tryRun(VENV, ['-c', 'import sys;print(sys.version.split()[0])']);
+  const minor = Number((ver.out || '0.0').split('.')[1]);
+  record('transcriber', 'Python version', ver.ok && (minor === 11 || minor === 12),
+    ver.out, 'Rebuild the venv with python 3.11 or 3.12', false);
+
+  // Every module the Python half imports, not just the headline one.
+  for (const mod of ['whisperx', 'torch', 'numpy', 'PIL', 'certifi']) {
+    const r = tryRun(VENV, ['-c', `import ${mod}`], () => 'ok');
+    record('transcriber', mod, r.ok, r.ok ? 'ok' : 'not importable',
+      '.venv/Scripts/pip install -r requirements.txt', false);
+  }
+}
+
+/* ------------------------------------------------- the python half, script by script */
+if (venvOk) {
+  // Importing whisperx is not the same as the scripts running. Compile each one, which
+  // catches a missing dependency or a syntax error without doing any of the slow work.
+  const py = readdirSync(join(ROOT, 'scripts')).filter((f) => f.endsWith('.py'));
+  const bad = [];
+  for (const f of py) {
+    const r = tryRun(VENV, ['-m', 'py_compile', join(ROOT, 'scripts', f)], () => 'ok');
+    if (!r.ok) bad.push(f);
+  }
+  record('transcriber', 'Python scripts', bad.length === 0,
+    bad.length ? `${bad.join(', ')} will not compile` : `${py.length} compile clean`,
+    '.venv/Scripts/pip install -r requirements.txt', false);
+}
+
+/* ----------------------------------------------------------------------- brand */
+const tokens = existsSync(join(ROOT, 'src', 'design', 'tokens.ts'));
+record('brand', 'Design tokens', tokens, tokens ? 'src/design/tokens.ts' : 'missing',
+  'Restore src/design/tokens.ts, which is where the whole look lives');
+
+// A missing font file does not fail a render: it silently swaps in a fallback, and the
+// video comes out looking almost right, which is worse than an error.
+const fontDir = join(ROOT, 'assets', 'fonts');
+const fonts = existsSync(fontDir) ? readdirSync(fontDir).filter((f) => /\.(ttf|otf|woff2?)$/i.test(f)) : [];
+record('brand', 'Fonts', fonts.length > 0,
+  fonts.length ? `${fonts.length} file(s): ${fonts.slice(0, 2).join(', ')}` : 'assets/fonts is empty',
+  'Put the brand font files back in assets/fonts, or a render falls back to a system face');
+
+/* --------------------------------------------------------------------- report */
+const W = 22;
+let lastArea = '';
+for (const r of results) {
+  if (r.area !== lastArea) { console.log(`\n${r.area.toUpperCase()}`); lastArea = r.area; }
+  const mark = r.ok ? '  ok  ' : (r.core ? ' FAIL ' : ' --   ');
+  console.log(`${mark} ${r.name.padEnd(W)} ${r.detail}`);
+  if (!r.ok) console.log(`       ${''.padEnd(W)} fix: ${r.fix}`);
+}
+
+const brokenCore = results.filter((r) => !r.ok && r.core);
+const brokenOpt = results.filter((r) => !r.ok && !r.core);
+
+console.log('\n' + '-'.repeat(64));
+if (!brokenCore.length && !brokenOpt.length) {
+  console.log('Everything is present. You can cut, render and caption.');
+} else if (!brokenCore.length) {
+  console.log(`Rendering works. ${brokenOpt.length} optional piece(s) missing:`);
+  console.log(`  ${[...new Set(brokenOpt.map((r) => r.fix))].join('\n  ')}`);
+  console.log('Without these: no word-level captions, no auto cut detection, no green-screen cutouts.');
+} else {
+  console.log(`${brokenCore.length} thing(s) needed for a render are missing. Fix these first:`);
+  console.log(`  ${[...new Set(brokenCore.map((r) => r.fix))].join('\n  ')}`);
+}
+
+process.exit(brokenCore.length ? 1 : 0);

package/template/scripts/find_cuts.py

@@ -0,0 +1,45 @@
+"""Find jump cuts in a talking-head clip (frames where the picture jumps instead of moving).
+
+Usage (from the project root):
+    python scripts/find_cuts.py <video> <out.json>
+
+Writes a JSON array of frame numbers: each is the first frame AFTER a cut. Used to
+ - punch in/out on each cut (the Stage `punchIns` prop), so cuts read as intentional camera changes
+ - tell motion-check these changes are in the footage (--allow-file)
+"""
+
+import json
+import subprocess
+import sys
+
+import numpy as np
+import sys as _sys, pathlib as _pl
+_sys.path.insert(0, str(_pl.Path(__file__).resolve().parent / 'lib'))
+from media import FFMPEG, FFPROBE  # resolved per platform - never hardcode a tool path
+
+
+
+def main() -> None:
+    video, out_path = sys.argv[1], sys.argv[2]
+    raw = subprocess.run(
+        [FFMPEG, "-v", "error", "-i", video, "-vf", "scale=320:180", "-f", "rawvideo", "-pix_fmt", "gray", "-"],
+        capture_output=True,
+        check=True,
+    ).stdout
+    frames = np.frombuffer(raw, np.uint8).reshape(-1, 180, 320).astype(np.float32)
+    change = np.abs(np.diff(frames, axis=0)).mean(axis=(1, 2))
+    typical = float(np.median(change))
+
+    cuts = []
+    for i in range(2, len(change) - 2):
+        neighbours = float(np.median(np.concatenate([change[i - 2 : i], change[i + 1 : i + 3]])))
+        # A cut: one transition far larger than both the clip's typical motion and its neighbours.
+        if change[i] > 6 and change[i] > 4 * max(neighbours, typical):
+            cuts.append(i + 1)
+
+    json.dump(cuts, open(out_path, "w"), indent=0)
+    print(f"{len(cuts)} cuts -> {out_path}: {cuts}")
+
+
+if __name__ == "__main__":
+    main()