creator-editing-studio 1.3.5 → 1.3.7

package/template/preview/server.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * The live preview inside a Claude chat (an MCP App) — part of the studio.
+ *
+ * WHY THE PAGE CARRIES EVERYTHING. In the Claude desktop app the in-chat player cannot call this server
+ * back ("IPC not available for MCP tool call", tested 2026-10-17) and cannot fetch from the computer
+ * ("Failed to fetch", 2026-10-16). What it can do: show the page this server hands over when the preview
+ * opens, and send messages into the chat. So each time the preview opens, the page arrives with the
+ * compiled edit and small preview copies of the footage already inside it.
+ *
+ * THE LOOP. The person types a change under a beat → the player sends it into the chat → Claude edits
+ * that beat → Claude calls preview_edit again → the updated preview opens below. Every open saves a copy
+ * of the video's folder first, so preview_undo can put the last change back exactly.
+ *
+ * Which video: preview_edit({video}) — or current.json (written by use.mjs) when it is called without one. Nothing listens on any port. stdout belongs to the MCP
+ * protocol: every log goes to stderr.
+ */
+import {cpSync, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {registerAppResource, registerAppTool, RESOURCE_MIME_TYPE} from '@modelcontextprotocol/ext-apps/server';
+import {z} from 'zod';
+import {buildManifest, compileEdit, configFor, HERE, playerHtml, SRC} from './lib.mjs';
+
+const CONFIG = join(HERE, 'current.json');
+const cfg = () => JSON.parse(readFileSync(CONFIG, 'utf8'));
+const log = (...a) => console.error('[live-preview]', ...a);
+const SNAPS = (project) => join(HERE, '.snapshots', project);
+const videoDir = (project) => join(SRC, 'videos', project);
+
+/* ----------------------------------------------------------------------------- versions (for Undo) */
+
+/** A fingerprint of the video's folder, so opening the preview twice without a change saves nothing. */
+const fingerprint = (dir) =>
+  readdirSync(dir, {recursive: true})
+    .map(String)
+    .sort()
+    .map((f) => {
+      const st = statSync(join(dir, f));
+      return st.isFile() ? `${f}:${st.size}:${st.mtimeMs}` : '';
+    })
+    .join('|');
+const sigFile = (project, v) => join(SNAPS(project), String(v), '.sig');
+
+const versions = (project) =>
+  existsSync(SNAPS(project))
+    ? readdirSync(SNAPS(project))
+        .map(Number)
+        .filter((v) => Number.isFinite(v) && existsSync(sigFile(project, v)))
+        .sort((a, b) => a - b)
+    : [];
+
+/** Save the video's folder as the next version if it changed since the last one. Returns the current version. */
+function saveVersion(project) {
+  const dir = videoDir(project);
+  const list = versions(project);
+  const last = list.at(-1);
+  const sig = fingerprint(dir);
+  if (last !== undefined && readFileSync(sigFile(project, last), 'utf8') === sig) return last;
+  const v = (last ?? 0) + 1;
+  cpSync(dir, join(SNAPS(project), String(v)), {recursive: true});
+  // The fingerprint of the live folder as it was saved (the copy's own file dates differ).
+  writeFileSync(sigFile(project, v), sig);
+  for (const old of list.slice(0, Math.max(0, list.length - 40))) rmSync(join(SNAPS(project), String(old)), {recursive: true, force: true});
+  return v;
+}
+
+/* ----------------------------------------------------------------------------- the page */
+
+let uiHtml = '';
+let uiSig = '';
+const media = new Map(); // hash → data URL, so unchanged footage is encoded once
+
+/** The player page with the current edit and its footage inside it. */
+async function page() {
+  const c = cfg();
+  const UI = join(HERE, 'ui');
+  const sig = existsSync(UI) ? readdirSync(UI).map((f) => `${f}:${statSync(join(UI, f)).mtimeMs}`).join('|') : 'built';
+  if (sig !== uiSig) [uiHtml, uiSig] = [await playerHtml(), sig];
+
+  const version = saveVersion(c.project);
+  let code = null;
+  let error = null;
+  try {
+    code = await compileEdit(c);
+  } catch (e) {
+    error = String(e.message ?? e);
+  }
+  const files = {};
+  for (const a of buildManifest(c)) {
+    if (!media.has(a.hash)) {
+      // Remotion's font loader reads the type from the text after the last dot, so fonts get it as a fragment.
+      const ext = /\.(ttf|otf|woff2?)$/i.exec(a.name)?.[1];
+      media.set(a.hash, `data:${a.mime};base64,${readFileSync(a.file).toString('base64')}${ext ? `#.${ext}` : ''}`);
+    }
+    files[a.name] = media.get(a.hash);
+  }
+  const data = {version, canUndo: versions(c.project).length > 1, project: c.project, edit: c.edit, composition: c.composition, error, code, files};
+  const html = uiHtml.replace('<head>', `<head><script>window.__LP_DATA=${JSON.stringify(data).replace(/</g, '\\u003c')}</script>`);
+  log(`page for ${c.project} version ${version}: ${(html.length / 1e6).toFixed(1)} MB${error ? ' (the edit does not compile)' : ''}`);
+  return html;
+}
+
+/* ----------------------------------------------------------------------------- MCP */
+
+const URI = 'ui://editing-os/live-preview.html';
+const server = new McpServer({name: 'editing-os-live-preview', version: '0.1.0'});
+
+registerAppTool(
+  server,
+  'preview_edit',
+  {
+    title: 'Live preview',
+    description:
+      'Show the live preview of the current edit inside the chat: the video plays with the beats beside it, and a change box under every beat. Nothing is rendered. ' +
+      'OPEN IT YOURSELF as a step of the work — right after the person approves the plan, and again after every change you make to the edit — never wait to be asked. ' +
+      'Changes typed in the preview arrive as chat messages: change only that beat in the edit file, then call preview_edit again so the updated preview appears. ' +
+      'Render the final video only when they press "Render final video", and give the estimated render time only then.',
+    inputSchema: {video: z.string().optional().describe('The video folder name (src/videos/<video>). Needed the first time for each video.')},
+    _meta: {ui: {resourceUri: URI}},
+  },
+  async ({video}) => {
+    if (video) writeFileSync(CONFIG, JSON.stringify(configFor(video), null, 2) + '\n');
+    if (!existsSync(CONFIG)) return {content: [{type: 'text', text: 'Which video? Call preview_edit with {video: "<folder name in src/videos>"}.'}], isError: true};
+    const c = cfg();
+    const v = saveVersion(c.project);
+    return {content: [{type: 'text', text: `Live preview of ${c.project} (version ${v}) is showing in the chat.`}], structuredContent: {project: c.project, version: v}};
+  },
+);
+
+server.registerTool(
+  'preview_undo',
+  {
+    title: 'Undo the last preview change',
+    description: 'Put the edit back exactly as it was before the last change. Use it when the person presses Undo in the preview, then call preview_edit to show it.',
+  },
+  async () => {
+    const c = cfg();
+    const list = versions(c.project);
+    if (list.length < 2) return {content: [{type: 'text', text: 'Nothing to undo — this is the first version of the edit.'}], isError: true};
+    const [prev, last] = list.slice(-2);
+    const dir = videoDir(c.project);
+    const from = join(SNAPS(c.project), String(prev));
+    for (const f of readdirSync(dir)) rmSync(join(dir, f), {recursive: true, force: true});
+    cpSync(from, dir, {recursive: true});
+    rmSync(join(dir, '.sig'), {force: true});
+    rmSync(join(SNAPS(c.project), String(last)), {recursive: true, force: true});
+    // The restored folder is version `prev` again; remember its new fingerprint so it is not saved twice.
+    writeFileSync(sigFile(c.project, prev), fingerprint(dir));
+    log(`undo: ${c.project} back to version ${prev}`);
+    return {content: [{type: 'text', text: `Undone — ${c.project} is back to version ${prev}. Call preview_edit to show it.`}]};
+  },
+);
+
+registerAppResource(server, 'Live preview', URI, {description: 'Player and beat breakdown for the current edit'}, async () => ({
+  contents: [{uri: URI, mimeType: RESOURCE_MIME_TYPE, text: await page(), _meta: {ui: {prefersBorder: false}}}],
+}));
+
+await server.connect(new StdioServerTransport());
+log('MCP server ready');

package/template/preview/use.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Point the live preview at a video (preview_edit({video}) does the same).
+ *
+ *   node preview/use.mjs <name>
+ *
+ * Writes current.json from the video's own folder (see configFor in lib.mjs); the running preview server
+ * watches that file and switches over by itself. The online preview uses publish.mjs instead.
+ */
+import {writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {configFor, HERE} from './lib.mjs';
+
+try {
+  const config = configFor(process.argv[2]);
+  if (!config.stems.voice) console.warn('warning: no voice stem found — the preview will play silent');
+  writeFileSync(join(HERE, 'current.json'), JSON.stringify(config, null, 2) + '\n');
+  console.log(JSON.stringify(config, null, 2));
+} catch (e) {
+  console.error(String(e.message ?? e));
+  process.exit(1);
+}

package/template/requirements.txt

@@ -1,23 +1,27 @@
-# The Python half of the studio: transcription, word alignment, cut detection,
-# green-screen cutouts and colour grading.
-#
-#   python -m venv .venv
-#   .venv/bin/pip install -r requirements.txt        (Windows: .venv\Scripts\pip)
-#
-# Python 3.11 or 3.12. Not 3.13+ — WhisperX's dependencies do not support it yet, and the
-# failure is a wall of build errors rather than a clear message.
-#
-# certifi is not optional on macOS: torch downloads the alignment model with urllib, which
-# on a python.org build has no root certificates at all.
-
-whisperx==3.8.6
-# BiRefNet, for cutting the subject out of ordinary footage so text can sit behind them.
-# MIT licensed and self-hosted: nothing uploads, and there is no per-video cost.
-transformers>=4.44
-timm>=1.0
-einops>=0.8
-kornia>=0.7
-torch>=2.2
-numpy>=1.26
-Pillow>=10.0
-certifi>=2024.2.2
+# The Python half of the studio: transcription, word alignment, cut detection,
+# green-screen cutouts and colour grading.
+#
+#   python -m venv .venv
+#   .venv/bin/pip install -r requirements.txt        (Windows: .venv\Scripts\pip)
+#
+# Python 3.11 or 3.12. Not 3.13+ — WhisperX's dependencies do not support it yet, and the
+# failure is a wall of build errors rather than a clear message.
+#
+# certifi is not optional on macOS: torch downloads the alignment model with urllib, which
+# on a python.org build has no root certificates at all.
+
+whisperx==3.8.6
+# BiRefNet, for cutting the subject out of ordinary footage so text can sit behind them.
+# MIT licensed and self-hosted: nothing uploads, and there is no per-video cost.
+transformers>=4.44
+timm>=1.0
+einops>=0.8
+kornia>=0.7
+torch>=2.2
+numpy>=1.26
+Pillow>=10.0
+certifi>=2024.2.2
+
+# Motion tracking (scripts/track_head.py): optical-flow tracking of the speaker's head, so text can ride
+# with it. Headless build: no GUI libraries, works on servers and Macs alike. Only used when asked for.
+opencv-python-headless>=4.9

package/template/scripts/align-script.py

@@ -0,0 +1,138 @@
+"""Word timings from a script you already have: match each word of an .srt to the audio.
+
+Usage (from the project root):
+    python scripts/align-script.py <media> <script.srt> --language ml [--project name]
+
+Writes work/<project>/<clip>/words.json in the same shape as transcribe.py, so everything downstream
+works unchanged.
+
+WHY THIS EXISTS. For Indian languages, speech recognition is the weak link: on a Malayalam take the
+small Whisper model ignored the speech and invented English, and even large models misspell names and
+loanwords. When the creator already has the script (or a corrected .srt), the words are known — only
+their timing is not. Forced alignment (wav2vec2, per language) answers exactly that, and it is far more
+reliable than recognition: it cannot invent words, it only places the ones it is given.
+
+The .srt timings only need to be roughly right — each line is aligned inside its own window, padded a
+little either side, so a line timed a few hundred milliseconds off still lands correctly.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys as _sys
+import time
+from pathlib import Path
+
+_sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+from media import FFMPEG, use_certifi  # noqa: E402
+from languages import lang, load_aligner, studio_language  # noqa: E402
+
+_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"]
+use_certifi()
+
+import whisperx  # noqa: E402
+
+TIME = re.compile(r"(\d+):(\d+):(\d+)[,.](\d+)\s*-->\s*(\d+):(\d+):(\d+)[,.](\d+)")
+
+
+def read_srt(path: Path):
+    """Cues as {start, end, text}. Tolerates a missing end on the last cue (a cut-off file)."""
+    cues = []
+    for block in re.split(r"\n\s*\n", path.read_text(encoding="utf-8-sig").strip()):
+        lines = [l.strip() for l in block.splitlines() if l.strip()]
+        for i, line in enumerate(lines):
+            m = TIME.search(line)
+            if m:
+                h1, m1, s1, ms1, h2, m2, s2, ms2 = map(int, m.groups())
+                text = " ".join(lines[i + 1 :]).strip()
+                if text:
+                    cues.append({"start": h1 * 3600 + m1 * 60 + s1 + ms1 / 1000, "end": h2 * 3600 + m2 * 60 + s2 + ms2 / 1000, "text": text})
+                break
+    return cues
+
+
+def main() -> None:
+    for stream in (_sys.stdout, _sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("media")
+    parser.add_argument("srt")
+    parser.add_argument("--language", default=None, help="e.g. ml, hi, ta, en. Default: the language chosen at setup")
+    parser.add_argument("--project", default=None)
+    parser.add_argument("--whole", action="store_true", help="ignore the cue times; align the whole script against the whole clip")
+    parser.add_argument("--pad", type=float, default=0.6, help="seconds of slack around each cue")
+    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()
+
+    cues = read_srt(Path(args.srt))
+    if not cues:
+        raise SystemExit("no cues found in the .srt")
+    audio = whisperx.load_audio(str(media))
+    duration = len(audio) / 16000
+
+    # Pad each cue a little past its own times, even into a neighbour's window: hand-made .srt cues often
+    # start a few hundred ms after the speech does, and a window clipped to the cue pins those first
+    # words onto its edge (they show up with a score near 0 at exactly the cue start).
+    segments = []
+    if args.whole:
+        # One window over the whole clip: the cue times are not trusted at all, only the words and their order.
+        segments = [{"start": 0.0, "end": duration, "text": " ".join(c["text"] for c in cues)}]
+    for c in ([] if args.whole else cues):
+        lo = max(0.0, c["start"] - args.pad)
+        hi = min(duration, c["end"] + args.pad)
+        segments.append({"start": lo, "end": max(hi, lo + 0.2), "text": c["text"]})
+
+    args.language = lang(args.language or studio_language() or "en")["code"]
+    align_model, metadata = load_aligner(whisperx, args.language)
+    if align_model is None:
+        raise SystemExit(f"No word-timing model for '{args.language}', so a script cannot be matched to the audio. Transcribe instead: python scripts/transcribe.py <media>")
+    aligned = whisperx.align(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": args.language,
+        "model": f"forced-alignment:{metadata.get('language', args.language)} from {Path(args.srt).name}",
+        "durationSec": round(duration, 3),
+        "scriptCoversSec": round(cues[-1]["end"], 3),
+        "text": " ".join(c["text"] for c in cues),
+        "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]
+    weak = [f'{w["word"]}@{w["start"]}' for w in words if w["score"] is not None and w["score"] < 0.15]
+    if weak:
+        print(f"low-confidence words (check by ear): {', '.join(weak)}")
+    print(f"cues: {len(cues)} | words: {len(words)} | unplaced: {len(unplaced)} {unplaced if unplaced else ''}")
+    if cues[-1]["end"] < duration - 1:
+        print(f"note: the script ends at {cues[-1]['end']:.1f}s but the video runs to {duration:.1f}s")
+    print(f"wrote {out_file} in {time.time() - started:.0f}s")
+
+
+if __name__ == "__main__":
+    main()

package/template/scripts/check_pair.py

@@ -1,90 +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()
+"""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()