creator-editing-studio 1.0.20260930

package/template/scripts/sync-audio.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * Line two recordings up by their sound.
+ *
+ *   npm run sync -- <clip-a> <clip-b> [--fps 30] [--max 30]
+ *
+ * Use it for: a clip-on mic recorded separately, a second camera angle, or a green-screen
+ * twin that started a moment late. Prints the offset in seconds and frames, and the exact
+ * ffmpeg line to apply it.
+ *
+ * How: match the loudness shape of both recordings (coarse), then match the waveform itself
+ * around that point (fine). Accurate to a handful of milliseconds on real audio.
+ */
+import {existsSync} from 'node:fs';
+import {decodePcm, energyEnvelope, fmt, probe} from './lib/media.mjs';
+
+const args = process.argv.slice(2);
+// Positional file arguments only: skip every --flag and the value that follows it.
+const files = [];
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('--')) { i++; continue; }
+  files.push(args[i]);
+}
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 && args[i + 1] ? Number(args[i + 1]) : fallback;
+};
+
+if (files.length < 2 || !files.slice(0, 2).every((f) => existsSync(f))) {
+  console.error('Usage: npm run sync -- <clip-a> <clip-b> [--fps 30] [--max 30]');
+  process.exit(2);
+}
+
+const [fileA, fileB] = files;
+const fps = flag('fps', 30);
+const maxShift = flag('max', 30); // seconds to search either way
+
+const COARSE_RATE = 8000;
+const COARSE_HOP = 256;
+const FINE_RATE = 22050;
+
+const a = decodePcm(fileA, COARSE_RATE);
+const b = decodePcm(fileB, COARSE_RATE);
+if (!a || !b) {
+  console.error('One of those files has no usable audio.');
+  process.exit(1);
+}
+
+const norm = (env) => {
+  const m = env.reduce((x, y) => x + y, 0) / env.length;
+  const out = new Float64Array(env.length);
+  for (let i = 0; i < env.length; i++) out[i] = env[i] - m;
+  return out;
+};
+
+const ea = norm(energyEnvelope(a, COARSE_RATE, COARSE_HOP).env);
+const eb = norm(energyEnvelope(b, COARSE_RATE, COARSE_HOP).env);
+const hopSeconds = COARSE_HOP / COARSE_RATE;
+
+/** Normalised correlation of two series at a given lag (b shifted by `lag` frames). */
+function correlate(x, y, lag) {
+  const start = Math.max(0, -lag);
+  const end = Math.min(x.length, y.length - lag);
+  if (end - start < 20) return -1;
+  let num = 0;
+  let dx = 0;
+  let dy = 0;
+  for (let i = start; i < end; i++) {
+    const xv = x[i];
+    const yv = y[i + lag];
+    num += xv * yv;
+    dx += xv * xv;
+    dy += yv * yv;
+  }
+  return dx && dy ? num / Math.sqrt(dx * dy) : -1;
+}
+
+const maxLag = Math.round(maxShift / hopSeconds);
+let bestLag = 0;
+let bestScore = -1;
+for (let lag = -maxLag; lag <= maxLag; lag++) {
+  const score = correlate(ea, eb, lag);
+  if (score > bestScore) {
+    bestScore = score;
+    bestLag = lag;
+  }
+}
+const coarseSeconds = bestLag * hopSeconds;
+
+/* ---------------------------------------------------------------- fine pass on the waveform */
+
+let offsetSeconds = coarseSeconds;
+const fa = decodePcm(fileA, FINE_RATE);
+const fb = decodePcm(fileB, FINE_RATE);
+if (fa && fb) {
+  const centre = Math.round(coarseSeconds * FINE_RATE);
+  const window = Math.round(hopSeconds * 2 * FINE_RATE);
+  const step = Math.max(1, Math.round(FINE_RATE / 4000)); // ~0.25ms resolution
+  let fineBest = centre;
+  let fineScore = -1;
+  for (let lag = centre - window; lag <= centre + window; lag += step) {
+    const score = correlate(fa, fb, lag);
+    if (score > fineScore) {
+      fineScore = score;
+      fineBest = lag;
+    }
+  }
+  if (fineScore > 0) offsetSeconds = fineBest / FINE_RATE;
+}
+
+const infoA = probe(fileA);
+const infoB = probe(fileB);
+const frames = offsetSeconds * fps;
+const confidence = bestScore > 0.75 ? 'strong' : bestScore > 0.45 ? 'usable' : 'weak — check it by ear';
+
+console.log(`A  ${fileA}  (${fmt(infoA?.duration ?? 0, 2)}s)`);
+console.log(`B  ${fileB}  (${fmt(infoB?.duration ?? 0, 2)}s)`);
+console.log('');
+if (Math.abs(offsetSeconds) < 0.005) {
+  console.log('These are already in sync.');
+} else if (offsetSeconds > 0) {
+  // B's content arrives later than A's: skip the head of B.
+  console.log(`B starts ${fmt(offsetSeconds, 3)}s LATER than A  (${fmt(frames, 1)} frames at ${fps}fps)`);
+  console.log(`Trim B:    -ss ${fmt(offsetSeconds, 3)} -i "${fileB}"`);
+  console.log(`In the edit: start B at frame ${Math.round(frames)} of its own timeline.`);
+} else {
+  console.log(`B starts ${fmt(-offsetSeconds, 3)}s EARLIER than A  (${fmt(-frames, 1)} frames at ${fps}fps)`);
+  console.log(`Trim A:    -ss ${fmt(-offsetSeconds, 3)} -i "${fileA}"`);
+  console.log(`In the edit: start A at frame ${Math.round(-frames)} of its own timeline.`);
+}
+console.log(`\nMatch     ${fmt(bestScore, 3)} (${confidence})`);
+if (infoA && infoB && Math.abs((infoA.fps || 0) - (infoB.fps || 0)) > 0.02) {
+  console.log(`Careful:  different frame rates (${fmt(infoA.fps, 2)} vs ${fmt(infoB.fps, 2)}). Conform both before using this offset.`);
+}

package/template/scripts/transcribe.py

@@ -0,0 +1,103 @@
+"""Word-level transcript for a clip: WhisperX transcription + wav2vec2 forced alignment.
+
+Usage (from the project root):
+    python scripts/transcribe.py <media> [--language en] [--model small]
+
+Writes work/<clip-name>/words.json. Models are cached under the studio's .models folder.
+Words the aligner cannot place (often digits like "186%") keep start/end = null and must be
+fixed against the script before building the spine.
+"""
+
+import argparse
+import json
+import os
+import time
+from pathlib import Path
+
+import sys as _sys  # noqa: E402
+_sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+from media import FFMPEG, use_certifi  # noqa: E402
+
+# Models are large; cache them inside the studio so they survive and are easy to find.
+_MODELS = Path(__file__).resolve().parent.parent / ".models"
+os.environ.setdefault("HF_HOME", str(_MODELS / "huggingface"))
+os.environ.setdefault("TORCH_HOME", str(_MODELS / "torch"))
+os.environ["PATH"] = str(Path(FFMPEG).parent) + os.pathsep + os.environ["PATH"]
+
+# torch.hub fetches the word-alignment model with urllib, which on a python.org macOS
+# build has no root certificates — transcription then dies with CERTIFICATE_VERIFY_FAILED
+# after the slow part has already succeeded. Must run before torch is imported.
+use_certifi()
+
+try:
+    import whisperx  # noqa: E402  (must import after the cache/PATH/cert setup above)
+except ModuleNotFoundError as exc:  # pragma: no cover
+    # Run with the wrong interpreter and the bare error reads as "never installed", which
+    # sends you off to fix the wrong thing. Say which python is running and what to do.
+    _venv = Path(__file__).resolve().parent.parent / ".venv"
+    _venv_py = _venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python3")
+    print(f"Cannot import {exc.name}.", file=_sys.stderr)
+    print(f"  running: {_sys.executable}  (python {_sys.version.split()[0]})", file=_sys.stderr)
+    if _venv_py.exists():
+        print(f"  the studio's environment is at {_venv_py}", file=_sys.stderr)
+        print("  run the transcriber with that python, or use: npm run prep", file=_sys.stderr)
+    else:
+        print("  the studio has no .venv yet. Build one with python 3.11 or 3.12:", file=_sys.stderr)
+        print("    py -3.12 -m venv .venv", file=_sys.stderr)
+        print("    .venv/Scripts/python.exe -m pip install -r requirements.txt", file=_sys.stderr)
+    print("  see what you have with: npm run doctor", file=_sys.stderr)
+    raise SystemExit(2)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("media")
+    parser.add_argument("--language", default=None, help="e.g. en, hi. Detected when omitted.")
+    parser.add_argument("--project", default=None, help="Video project name: writes to work/<project>/<clip>/")
+    parser.add_argument("--model", default="small", help="Whisper size: small (fast on CPU) or medium (more accurate)")
+    args = parser.parse_args()
+
+    media = Path(args.media)
+    out_dir = (Path("work") / args.project / media.stem) if args.project else (Path("work") / media.stem)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    started = time.time()
+
+    audio = whisperx.load_audio(str(media))
+    model = whisperx.load_model(args.model, device="cpu", compute_type="int8", language=args.language)
+    result = model.transcribe(audio, batch_size=4, language=args.language)
+    language = result["language"]
+
+    align_model, metadata = whisperx.load_align_model(language_code=language, device="cpu")
+    aligned = whisperx.align(result["segments"], align_model, metadata, audio, device="cpu", return_char_alignments=False)
+
+    words = []
+    for segment in aligned["segments"]:
+        for w in segment.get("words", []):
+            words.append(
+                {
+                    "word": w["word"],
+                    "start": round(w["start"], 3) if "start" in w else None,
+                    "end": round(w["end"], 3) if "end" in w else None,
+                    "score": round(w["score"], 3) if "score" in w else None,
+                }
+            )
+
+    output = {
+        "source": str(media),
+        "language": language,
+        "model": args.model,
+        "durationSec": round(len(audio) / 16000, 3),
+        "text": " ".join(s["text"].strip() for s in aligned["segments"]),
+        "words": words,
+    }
+    out_file = out_dir / "words.json"
+    out_file.write_text(json.dumps(output, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    unplaced = [w["word"] for w in words if w["start"] is None]
+    print(f"language: {language} | words: {len(words)} | unplaced: {len(unplaced)} {unplaced if unplaced else ''}")
+    print(f"text: {output['text']}")
+    print(f"wrote {out_file} in {time.time() - started:.0f}s")
+
+
+if __name__ == "__main__":
+    main()

package/template/scripts/trim.mjs

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+/**
+ * Silence + filler trim, with automatic punch-ins.
+ *
+ *   npm run trim -- <video> [--project <name>] [--words work/<n>/<stem>/words.json]
+ *                  [--min-silence 0.35] [--pad 0.08] [--floor <dBFS>] [--fps 30]
+ *                  [--write <out.mp4>]
+ *
+ * Talking-head footage is mostly waiting: breaths, resets, the half second before a
+ * sentence starts. This finds those gaps, removes them, and — because every removal
+ * leaves a jump cut — assigns each surviving segment a different framing so the cut
+ * reads as a deliberate punch-in instead of a splice.
+ *
+ * Writes work/<project>/<stem>.trim.json + .md:
+ *   keep[]      the segments that survive, each with its framing (Stage scale + shift)
+ *   removed[]   what went, and why (silence / filler)
+ *   punchIns[]  the frame of every join and the framing change across it
+ *   ffmpeg      select/aselect expressions, if you want to cut the file directly
+ *
+ * The voice is never processed here — segments are copied, not filtered. With --write
+ * the file is encoded once (law: at most one encode), and the cut list is what the
+ * composition should consume so the final render encodes the voice only that once.
+ *
+ * Detection is energy-based: an adaptive floor from the recording itself, hysteresis so
+ * a comma is not a cut, then padding so words keep their attack and tail. No model.
+ */
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {basename, extname, join} from 'node:path';
+import {FFMPEG, decodePcm, energyEnvelope, fmt, probe, run, timecode} 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].startsWith('--') ? args[i + 1] : fallback;
+};
+const has = (name) => args.includes(`--${name}`);
+
+if (!file || !existsSync(file)) {
+  console.error('Usage: npm run trim -- <video> [--project <name>] [--words <words.json>] [--min-silence 0.35] [--pad 0.08] [--write out.mp4]');
+  process.exit(2);
+}
+
+const RATE = 22050;
+const project = flag('project', null);
+const fps = Number(flag('fps', 30));
+const minSilence = Number(flag('min-silence', 0.35));
+const pad = Number(flag('pad', 0.08));
+const floorOverride = has('floor') ? Number(flag('floor', -38)) : null;
+const wordsPath = flag('words', null);
+const writePath = flag('write', 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 duration = info?.duration || samples.length / RATE;
+
+/* ---------------------------------------------------------------- level over time */
+
+const {env, hopSeconds} = energyEnvelope(samples, RATE, 256);
+const db = new Float64Array(env.length);
+for (let i = 0; i < env.length; i++) db[i] = 20 * Math.log10(env[i] + 1e-9);
+
+const percentile = (arr, p) => {
+  const s = Array.from(arr).sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.max(0, Math.round((p / 100) * (s.length - 1))))];
+};
+
+const noiseFloorDb = percentile(db, 10);
+const speechPeakDb = percentile(db, 95);
+/**
+ * Sit the gate between the room and the voice: well above the floor, well under the
+ * peaks. Whichever of those two is stricter wins, so a noisy room does not open the
+ * gate and a quiet, close-mic'd take does not clip its own word endings.
+ */
+const thresholdDb =
+  floorOverride ?? Math.min(Math.max(noiseFloorDb + 9, speechPeakDb - 28), speechPeakDb - 14);
+
+/* ---------------------------------------------------------------- speech regions */
+
+const loud = new Uint8Array(db.length);
+for (let i = 0; i < db.length; i++) loud[i] = db[i] > thresholdDb ? 1 : 0;
+
+const toRegions = (mask, want) => {
+  const out = [];
+  let start = -1;
+  for (let i = 0; i < mask.length; i++) {
+    if (mask[i] === want && start < 0) start = i;
+    if ((mask[i] !== want || i === mask.length - 1) && start >= 0) {
+      out.push({from: start, to: i});
+      start = -1;
+    }
+  }
+  return out;
+};
+
+// Close short gaps first: a gap between two words is not a cut, only a gap between thoughts is.
+const gapFrames = Math.round(minSilence / hopSeconds);
+for (const gap of toRegions(loud, 0)) {
+  if (gap.to - gap.from < gapFrames && gap.from > 0 && gap.to < loud.length - 1) {
+    for (let i = gap.from; i <= gap.to; i++) loud[i] = 1;
+  }
+}
+// Then drop specks of "speech" too short to be a word — a chair creak, a mouth click.
+const minSpeechFrames = Math.round(0.12 / hopSeconds);
+for (const seg of toRegions(loud, 1)) {
+  if (seg.to - seg.from < minSpeechFrames) for (let i = seg.from; i <= seg.to; i++) loud[i] = 0;
+}
+
+let keep = toRegions(loud, 1).map((r) => ({
+  start: Math.max(0, r.from * hopSeconds - pad),
+  end: Math.min(duration, r.to * hopSeconds + pad),
+}));
+
+/* ---------------------------------------------------------------- filler words */
+
+const FILLERS = new Set(['um', 'umm', 'uhm', 'uh', 'uhh', 'er', 'erm', 'ah', 'ahh', 'hmm', 'mmm', 'eh', 'mm']);
+const removedFillers = [];
+
+if (wordsPath && existsSync(wordsPath)) {
+  let words = [];
+  try {
+    const raw = JSON.parse(readFileSync(wordsPath, 'utf8'));
+    words = (Array.isArray(raw) ? raw : raw.words || []).map((w) => ({
+      text: String(w.text ?? w.word ?? ''),
+      start: Number(w.start),
+      end: Number(w.end),
+    }));
+  } catch {
+    console.error(`Could not read ${wordsPath} — skipping filler removal.`);
+  }
+  const hits = words.filter(
+    (w) => Number.isFinite(w.start) && Number.isFinite(w.end) && FILLERS.has(w.text.toLowerCase().replace(/[^a-z]/g, '')),
+  );
+  for (const w of hits) {
+    const from = w.start - 0.02;
+    const to = w.end + 0.02;
+    const next = [];
+    for (const seg of keep) {
+      if (to <= seg.start || from >= seg.end) {
+        next.push(seg);
+        continue;
+      }
+      if (from > seg.start) next.push({start: seg.start, end: from});
+      if (to < seg.end) next.push({start: to, end: seg.end});
+    }
+    keep = next;
+    removedFillers.push({start: Number(from.toFixed(3)), end: Number(to.toFixed(3)), word: w.text});
+  }
+}
+
+// Padding and filler splits can leave overlaps or slivers. Merge, then drop anything too short to read.
+keep.sort((a, b) => a.start - b.start);
+const merged = [];
+for (const seg of keep) {
+  const last = merged[merged.length - 1];
+  if (last && seg.start <= last.end + 0.001) last.end = Math.max(last.end, seg.end);
+  else merged.push({...seg});
+}
+keep = merged.filter((s) => s.end - s.start >= 0.15);
+
+if (!keep.length) {
+  console.error('Everything was gated out. The recording is quieter than expected — pass --floor <dBFS> to set the gate by hand.');
+  process.exit(1);
+}
+
+/* ---------------------------------------------------------------- punch-ins */
+
+/**
+ * Every removal leaves a jump cut, so every cut gets a new framing. The pattern never
+ * repeats a framing across a join and never sits on one size for long. Scale stays at
+ * or above 1 — a punch-in pushes in, it never pulls back past the frame edge.
+ */
+const FRAMING = {
+  wide: {scale: 1.0, shiftYPct: 0},
+  mid: {scale: 1.09, shiftYPct: -1.5},
+  close: {scale: 1.2, shiftYPct: -3.2},
+};
+const PATTERN = ['wide', 'close', 'mid', 'close', 'wide', 'mid'];
+
+const segments = keep.map((seg, i) => {
+  const name = PATTERN[i % PATTERN.length];
+  return {
+    index: i,
+    start: Number(seg.start.toFixed(3)),
+    end: Number(seg.end.toFixed(3)),
+    seconds: Number((seg.end - seg.start).toFixed(3)),
+    framing: name,
+    ...FRAMING[name],
+  };
+});
+
+// Timeline positions after the gaps close.
+let cursor = 0;
+for (const s of segments) {
+  s.atSeconds = Number(cursor.toFixed(3));
+  s.atFrame = Math.round(cursor * fps);
+  s.durationFrames = Math.round(s.seconds * fps);
+  cursor += s.seconds;
+}
+const newDuration = cursor;
+
+const punchIns = segments.slice(1).map((s, i) => ({
+  atSeconds: s.atSeconds,
+  atFrame: s.atFrame,
+  from: segments[i].framing,
+  to: s.framing,
+  scale: s.scale,
+  shiftYPct: s.shiftYPct,
+}));
+
+/* ---------------------------------------------------------------- what went */
+
+const removed = [];
+let prevEnd = 0;
+for (const s of keep) {
+  if (s.start - prevEnd > 0.001) {
+    removed.push({start: Number(prevEnd.toFixed(3)), end: Number(s.start.toFixed(3)), seconds: Number((s.start - prevEnd).toFixed(3)), kind: 'silence'});
+  }
+  prevEnd = s.end;
+}
+if (duration - prevEnd > 0.001) {
+  removed.push({start: Number(prevEnd.toFixed(3)), end: Number(duration.toFixed(3)), seconds: Number((duration - prevEnd).toFixed(3)), kind: 'tail'});
+}
+for (const f of removedFillers) {
+  const hit = removed.find((r) => Math.abs(r.start - f.start) < 0.05);
+  if (hit) hit.kind = `filler "${f.word.trim()}"`;
+}
+
+const saved = duration - newDuration;
+
+/* ---------------------------------------------------------------- what other gates would find */
+
+/**
+ * The gate is the one judgement call in here, and it is invisible unless we show it. A
+ * take that comes back barely trimmed is usually just tightly delivered — but it can also
+ * mean the gate sat under the breaths. This says which, without anyone having to guess.
+ *
+ * Raising it finds more pauses and eventually starts eating quiet word endings, so the
+ * default stays conservative: damaging the voice is a worse failure than leaving a pause.
+ */
+const gateTable = [-50, -45, -40, -37, -34, -31, -28]
+  .concat(Math.round(thresholdDb * 10) / 10)
+  .sort((a, b) => a - b)
+  .filter((v, i, arr) => arr.indexOf(v) === i)
+  .map((th) => {
+    let gaps = 0;
+    let total = 0;
+    let run = 0;
+    for (let i = 0; i < db.length; i++) {
+      if (db[i] <= th) run++;
+      else {
+        if (run * hopSeconds >= minSilence) {
+          gaps++;
+          total += run * hopSeconds;
+        }
+        run = 0;
+      }
+    }
+    if (run * hopSeconds >= minSilence) {
+      gaps++;
+      total += run * hopSeconds;
+    }
+    return {th, gaps, total};
+  });
+
+/* ---------------------------------------------------------------- ffmpeg */
+
+const between = keep.map((s) => `between(t,${fmt(s.start, 3)},${fmt(s.end, 3)})`).join('+');
+const vf = `select='${between}',setpts=N/FRAME_RATE/TB`;
+const af = `aselect='${between}',asetpts=N/SR/TB`;
+
+/* ---------------------------------------------------------------- write */
+
+const stem = basename(file, extname(file));
+const dir = project ? join('work', project) : join('work', 'trim');
+mkdirSync(dir, {recursive: true});
+
+const out = {
+  source: file,
+  fps,
+  durationSeconds: Number(duration.toFixed(3)),
+  newDurationSeconds: Number(newDuration.toFixed(3)),
+  savedSeconds: Number(saved.toFixed(3)),
+  gate: {
+    thresholdDb: Number(thresholdDb.toFixed(1)),
+    noiseFloorDb: Number(noiseFloorDb.toFixed(1)),
+    speechPeakDb: Number(speechPeakDb.toFixed(1)),
+    minSilence,
+    pad,
+  },
+  keep: segments,
+  removed,
+  punchIns,
+  ffmpeg: {vf, af},
+};
+
+const jsonPath = join(dir, `${stem}.trim.json`);
+writeFileSync(jsonPath, JSON.stringify(out, null, 2));
+
+const md = `# Trim — ${stem}
+
+- **Was** ${fmt(duration, 2)}s → **now** ${fmt(newDuration, 2)}s (**${fmt(saved, 2)}s removed**, ${fmt((saved / duration) * 100, 0)}%)
+- **Segments kept:** ${segments.length} · **cuts created:** ${punchIns.length}
+- **Gate:** ${fmt(thresholdDb, 1)} dBFS (room floor ${fmt(noiseFloorDb, 1)}, voice peaks ${fmt(speechPeakDb, 1)})
+- **Filler words removed:** ${removedFillers.length || '—'}${removedFillers.length ? ` (${removedFillers.map((f) => f.word.trim()).join(', ')})` : ''}
+
+## Cut list
+
+| # | source in → out | length | on timeline | framing |
+|---|---|---|---|---|
+${segments.map((s) => `| ${String(s.index + 1).padStart(2, '0')} | ${timecode(s.start)} → ${timecode(s.end)} | ${fmt(s.seconds, 2)}s | ${timecode(s.atSeconds)} (f${s.atFrame}) | ${s.framing} ×${fmt(s.scale, 2)} |`).join('\n')}
+
+## Punch-ins
+
+Every join below is a jump cut. The framing changes across it, so it reads as a push-in.
+Zoom through each one (Stage \`cutZoom\`) — never leave a bare splice.
+
+${punchIns.length ? punchIns.map((p) => `- frame ${p.atFrame} (${timecode(p.atSeconds)}): ${p.from} → **${p.to}** (×${fmt(p.scale, 2)}, shift ${fmt(p.shiftYPct, 1)}%)`).join('\n') : '- none — the take had no gaps worth cutting.'}
+
+## Removed
+
+${removed.map((r) => `- ${timecode(r.start)} → ${timecode(r.end)} (${fmt(r.seconds, 2)}s) — ${r.kind}`).join('\n')}
+
+## The gate
+
+Used **${fmt(thresholdDb, 1)} dBFS**${floorOverride === null ? ' (chosen from this recording)' : ' (set by hand with --floor)'}.
+If the trim looks too light, the take is probably just tightly delivered — this says so either way.
+Raising the gate finds more pauses and eventually starts eating quiet word endings, so it is
+deliberately conservative. Override with \`--floor <dBFS>\`.
+
+| gate | pauses ≥ ${minSilence}s | total |
+|---|---|---|
+${gateTable.map((g) => `| ${fmt(g.th, 1)} dBFS${Math.abs(g.th - thresholdDb) < 0.05 ? ' ← used' : ''} | ${g.gaps} | ${fmt(g.total, 1)}s |`).join('\n')}
+
+## Using it
+
+The cut list is the deliverable: feed \`keep[]\` to the composition so the voice is encoded
+once, at final render. To cut the file directly for a preview:
+
+\`\`\`
+ffmpeg -i "${file}" -vf "${vf}" -af "${af}" -c:v libx264 -crf 18 -c:a aac -b:a 256k out.mp4
+\`\`\`
+`;
+writeFileSync(join(dir, `${stem}.trim.md`), md);
+
+if (writePath) {
+  console.log('Encoding trimmed file (one encode, voice not otherwise processed)...');
+  const r = run(FFMPEG, ['-y', '-v', 'error', '-i', file, '-vf', vf, '-af', af, '-c:v', 'libx264', '-crf', '18', '-preset', 'slow', '-c:a', 'aac', '-b:a', '256k', writePath]);
+  if (!r.ok) {
+    console.error(r.err.trim() || 'ffmpeg failed');
+    process.exit(1);
+  }
+  console.log(`Written    ${writePath}`);
+}
+
+console.log(`Was        ${fmt(duration, 2)}s`);
+console.log(`Now        ${fmt(newDuration, 2)}s  (${fmt(saved, 2)}s removed, ${fmt((saved / duration) * 100, 0)}%)`);
+console.log(`Segments   ${segments.length} kept, ${punchIns.length} punch-in(s)`);
+console.log(`Gate       ${fmt(thresholdDb, 1)} dBFS (floor ${fmt(noiseFloorDb, 1)}, peaks ${fmt(speechPeakDb, 1)})`);
+if (saved / duration < 0.05) {
+  const louder = gateTable.filter((g) => g.th > thresholdDb && g.gaps > removed.length);
+  console.log(
+    louder.length
+      ? `           Barely trimmed — either the take is tight, or the gate sat under the breaths.\n           A gate of ${fmt(louder[0].th, 0)} dBFS would find ${louder[0].gaps} pauses (${fmt(louder[0].total, 1)}s): --floor ${fmt(louder[0].th, 0)}`
+      : '           Barely trimmed, and no higher gate finds more — this take is genuinely tight.',
+  );
+}
+if (removedFillers.length) console.log(`Fillers    ${removedFillers.map((f) => f.word.trim()).join(', ')}`);
+console.log(`Written    ${jsonPath}`);
+console.log('\nEvery join is a jump cut — zoom through each one. The punch-in list says which way.');

package/template/src/Root.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import {Composition} from 'remotion';
+import {FILM_TEST_FRAMES, FilmTest} from './compositions/FilmTest';
+import {PRESET_TEST_FRAMES, PresetTest} from './compositions/PresetTest';
+import {LAYOUT} from './design/tokens';
+import {Sample, SAMPLE_FRAMES} from './videos/sample/Sample';
+
+/**
+ * Every video you make gets registered here. `npm run studio` shows this list.
+ *
+ * PresetTest and FilmTest are reference compositions, not videos — they show every
+ * transition and every film look side by side so you can judge them against each other
+ * and pick one by name. Leave them; they cost nothing and they are how you decide.
+ */
+export const RemotionRoot: React.FC = () => (
+  <>
+    <Composition
+      id="Sample"
+      component={Sample}
+      durationInFrames={SAMPLE_FRAMES}
+      fps={LAYOUT.fps}
+      width={LAYOUT.width}
+      height={LAYOUT.height}
+    />
+    <Composition
+      id="PresetTest"
+      component={PresetTest}
+      durationInFrames={PRESET_TEST_FRAMES}
+      fps={LAYOUT.fps}
+      width={LAYOUT.width}
+      height={LAYOUT.height}
+    />
+    <Composition
+      id="FilmTest"
+      component={FilmTest}
+      durationInFrames={FILM_TEST_FRAMES}
+      fps={LAYOUT.fps}
+      width={LAYOUT.width}
+      height={LAYOUT.height}
+    />
+  </>
+);

package/template/src/components/BrandBackground.tsx

@@ -0,0 +1,22 @@
+import React from 'react';
+import {AbsoluteFill} from 'remotion';
+import {BACKGROUND} from '../design/tokens';
+
+/** Cream base, soft accent glow, faint fading grid — the site's hero treatment adapted for vertical video. */
+export const BrandBackground: React.FC = () => {
+  const {gridLine, gridSize, gridLineWidth, gridMask} = BACKGROUND;
+  const lines = (angle: number) =>
+    `repeating-linear-gradient(${angle}deg, ${gridLine} 0 ${gridLineWidth}px, transparent ${gridLineWidth}px ${gridSize}px)`;
+
+  return (
+    <AbsoluteFill style={{background: BACKGROUND.creamGlow}}>
+      <AbsoluteFill
+        style={{
+          backgroundImage: `${lines(0)}, ${lines(90)}`,
+          maskImage: gridMask,
+          WebkitMaskImage: gridMask,
+        }}
+      />
+    </AbsoluteFill>
+  );
+};