creator-editing-studio 1.0.20260930

package/template/scripts/grade.py

@@ -0,0 +1,202 @@
+"""Build a colour-grade LUT that moves footage towards the look of reference images.
+
+Usage (from the project root):
+    python scripts/grade.py <source_frames_dir> <out.cube> <ref.png> [<ref.png> ...]
+        [--tone 0.8] [--tint 0.85] [--sat 0.8] [--greens 0.8] [--strength 1.0] [--report out.json]
+
+Everything happens in CIE Lab, and every step is a function of the pixel colour only, so the whole
+grade bakes into a 33^3 .cube LUT (usable in ffmpeg `lut3d` and Premiere Lumetri):
+
+  1. tone     — contrast shape matched to the references (quantile matching of L), keeping part of the
+                footage's own exposure (EXPOSURE_KEEP) so dusk footage isn't lifted flat.
+  2. tint     — colour of shadows / mids / highlights (split toning), measured on low-to-moderate
+                chroma surfaces, so strongly coloured content (grass, clothes) doesn't leak into the grade.
+  3. sat      — overall saturation towards the references' chroma level.
+  4. greens   — hue and saturation of foliage towards the references' greens (e.g. olive/yellow).
+  Skin (orange hues) is protected: no hue rotation and no desaturation below 95%.
+"""
+
+import argparse
+import json
+import os
+
+import numpy as np
+from PIL import Image
+
+M = np.array([[0.4124564, 0.3575761, 0.1804375], [0.2126729, 0.7151522, 0.0721750], [0.0193339, 0.1191920, 0.9503041]])
+M_INV = np.linalg.inv(M)
+WHITE = np.array([0.95047, 1.0, 1.08883])
+D = 6 / 29
+
+
+def srgb_to_lab(rgb):
+    c = np.where(rgb <= 0.04045, rgb / 12.92, ((rgb + 0.055) / 1.055) ** 2.4)
+    xyz = c @ M.T / WHITE
+    f = np.where(xyz > D**3, np.cbrt(xyz), xyz / (3 * D * D) + 4 / 29)
+    return np.stack([116 * f[..., 1] - 16, 500 * (f[..., 0] - f[..., 1]), 200 * (f[..., 1] - f[..., 2])], axis=-1)
+
+
+def lab_to_srgb(lab):
+    fy = (lab[..., 0] + 16) / 116
+    f = np.stack([fy + lab[..., 1] / 500, fy, fy - lab[..., 2] / 200], axis=-1)
+    xyz = np.where(f > D, f**3, 3 * D * D * (f - 4 / 29)) * WHITE
+    lin = np.clip(xyz @ M_INV.T, 0, 1)
+    return np.clip(np.where(lin <= 0.0031308, lin * 12.92, 1.055 * lin ** (1 / 2.4) - 0.055), 0, 1)
+
+
+def load(path, max_side=640):
+    img = Image.open(path).convert("RGB")
+    img.thumbnail((max_side, max_side))
+    a = np.asarray(img, dtype=np.float64) / 255
+    # Trim uniform borders (letterbox bars, white frames) — they are not part of the look.
+    rows = a.std(axis=(1, 2)) > 0.02
+    cols = a.std(axis=(0, 2)) > 0.02
+    if rows.any() and cols.any():
+        a = a[np.argmax(rows) : len(rows) - np.argmax(rows[::-1]), np.argmax(cols) : len(cols) - np.argmax(cols[::-1])]
+    return a
+
+
+def pixels(paths):
+    lab = np.concatenate([srgb_to_lab(load(p)).reshape(-1, 3) for p in paths])
+    chroma = np.hypot(lab[:, 1], lab[:, 2])
+    # Drop overlay text / UI (pure white or pure black) from the statistics.
+    keep = ~(((lab[:, 0] > 96) & (chroma < 4)) | (lab[:, 0] < 1))
+    return lab[keep]
+
+
+BANDS = (15.0, 45.0, 80.0)  # shadow / mid / highlight centres in L
+NEUTRAL_MAX = 32.0  # chroma below this counts towards the tint estimate
+EXPOSURE_KEEP = 0.45  # 0 = match reference exposure fully, 1 = keep footage exposure
+
+
+def band_weights(L):
+    w = np.stack([np.exp(-0.5 * ((L - c) / 16) ** 2) for c in BANDS], axis=-1)
+    return w / np.maximum(w.sum(axis=-1, keepdims=True), 1e-9)
+
+
+def neutral_tint(lab):
+    """Mean a/b of near-neutral pixels per brightness band (the grade's tint, not the scene's colours)."""
+    chroma = np.hypot(lab[:, 1], lab[:, 2])
+    # Low-to-moderate chroma surfaces carry the grade's tint (sunlit walls, skin highlights); strongly
+    # coloured objects (grass, clothes) are excluded, and lower-chroma pixels count more.
+    sel = chroma < NEUTRAL_MAX
+    n = lab[sel]
+    trust = 1 - chroma[sel] / NEUTRAL_MAX
+    w = band_weights(n[:, 0]) * trust[:, None]
+    return np.array([[np.average(n[:, k], weights=w[:, i] + 1e-9) for k in (1, 2)] for i in range(len(BANDS))])
+
+
+def hue_deg(lab):
+    return np.degrees(np.arctan2(lab[..., 2], lab[..., 1])) % 360
+
+
+GREEN = (95.0, 175.0)
+SKIN = (15.0, 75.0)
+
+
+def greens_stats(lab):
+    h = hue_deg(lab)
+    c = np.hypot(lab[:, 1], lab[:, 2])
+    g = (h > GREEN[0]) & (h < GREEN[1]) & (c > 8)
+    if g.sum() < 200:
+        return None
+    ang = np.radians(h[g])
+    mean_h = np.degrees(np.arctan2(np.average(np.sin(ang), weights=c[g]), np.average(np.cos(ang), weights=c[g]))) % 360
+    return {"hue": float(mean_h), "chroma": float(np.percentile(c[g], 75))}
+
+
+def window(h, lo, hi, soft=15.0):
+    """1 inside [lo, hi], cosine fall-off over `soft` degrees outside."""
+    d = np.maximum(lo - h, 0) + np.maximum(h - hi, 0)
+    return np.where(d >= soft, 0.0, 0.5 + 0.5 * np.cos(np.pi * np.clip(d / soft, 0, 1)))
+
+
+def build(src, tgt, tone, tint, sat, greens):
+    qs = np.linspace(0.5, 99.5, 41)
+    src_q = np.percentile(src[:, 0], qs)
+    tgt_q = np.percentile(tgt[:, 0], qs)
+    src_q = np.maximum.accumulate(src_q + np.arange(len(qs)) * 1e-6)
+    # Match contrast shape, not absolute exposure: pull the target curve part-way back to the
+    # footage's own median, so a dusk shot is not lifted into a flat, washed look.
+    tgt_q = tgt_q - EXPOSURE_KEEP * (np.median(tgt[:, 0]) - np.median(src[:, 0]))
+    tgt_q = np.clip(tgt_q, 0, 100)
+    shift = neutral_tint(tgt) - neutral_tint(src)
+    sat_ratio = float(np.clip(np.percentile(np.hypot(tgt[:, 1], tgt[:, 2]), 85) / np.percentile(np.hypot(src[:, 1], src[:, 2]), 85), 0.7, 1.15))
+    gs, gt = greens_stats(src), greens_stats(tgt)
+    if gs and gt:
+        g_rot = float(np.clip(((gt["hue"] - gs["hue"] + 180) % 360) - 180, -30, 30))
+        g_sat = float(np.clip(gt["chroma"] / gs["chroma"], 0.55, 1.1))
+    else:
+        g_rot, g_sat = 0.0, 1.0
+    params = {"tone_src_q": src_q.tolist(), "tone_tgt_q": tgt_q.tolist(), "tint_shift": shift.tolist(), "sat_ratio": sat_ratio, "green_rot_deg": g_rot, "green_sat": g_sat}
+
+    def apply(lab):
+        L, a, b = lab[..., 0], lab[..., 1], lab[..., 2]
+        # 1. tone
+        L2 = L + tone * (np.interp(L, src_q, tgt_q) - L)
+        h = hue_deg(lab)
+        c = np.hypot(a, b)
+        skin = window(h, *SKIN) * np.clip(c / 12, 0, 1)
+        grn = window(h, *GREEN, soft=20) * np.clip(c / 8, 0, 1)
+        # 3 + 4. saturation (skin never below 95%) and greens
+        s = 1 + sat * (sat_ratio - 1)
+        s = np.where(skin > 0, np.maximum(s, 0.95 * skin + s * (1 - skin)), s)
+        s = s * (1 + greens * grn * (g_sat - 1))
+        rot = np.radians(greens * grn * g_rot)
+        h2 = np.arctan2(b, a) + rot
+        c2 = c * s
+        a2, b2 = c2 * np.cos(h2), c2 * np.sin(h2)
+        # 2. tint (split toning) by the new brightness; skin gets 70% of it
+        w = band_weights(L2)
+        da = (w * shift[:, 0]).sum(axis=-1)
+        db = (w * shift[:, 1]).sum(axis=-1)
+        k = tint * (1 - 0.15 * skin)
+        return np.stack([np.clip(L2, 0, 100), a2 + k * da, b2 + k * db], axis=-1)
+
+    return apply, params
+
+
+def write_cube(path, fn, strength, size=33):
+    g = np.linspace(0, 1, size)
+    b, gg, r = np.meshgrid(g, g, g, indexing="ij")  # red changes fastest in .cube order
+    rgb = np.stack([r, gg, b], axis=-1).reshape(-1, 3)
+    lab = srgb_to_lab(rgb)
+    out = lab_to_srgb(lab + strength * (fn(lab) - lab))
+    with open(path, "w", encoding="ascii") as fh:
+        fh.write(f'TITLE "{os.path.splitext(os.path.basename(path))[0]}"\nLUT_3D_SIZE {size}\nDOMAIN_MIN 0 0 0\nDOMAIN_MAX 1 1 1\n')
+        for v in out:
+            fh.write(f"{v[0]:.6f} {v[1]:.6f} {v[2]:.6f}\n")
+
+
+def main():
+    p = argparse.ArgumentParser()
+    p.add_argument("frames_dir")
+    p.add_argument("out_cube")
+    p.add_argument("refs", nargs="+")
+    p.add_argument("--tone", type=float, default=0.8)
+    p.add_argument("--tint", type=float, default=0.85)
+    p.add_argument("--sat", type=float, default=0.8)
+    p.add_argument("--greens", type=float, default=0.8)
+    p.add_argument("--strength", type=float, default=1.0)
+    p.add_argument("--report")
+    a = p.parse_args()
+    frames = [os.path.join(a.frames_dir, f) for f in sorted(os.listdir(a.frames_dir)) if f.lower().endswith((".png", ".jpg"))]
+    src, tgt = pixels(frames), pixels(a.refs)
+    fn, params = build(src, tgt, a.tone, a.tint, a.sat, a.greens)
+    write_cube(a.out_cube, fn, a.strength)
+    summary = {
+        "source_L_p5_p50_p95": np.percentile(src[:, 0], [5, 50, 95]).round(1).tolist(),
+        "target_L_p5_p50_p95": np.percentile(tgt[:, 0], [5, 50, 95]).round(1).tolist(),
+        "tint_shift_ab_shadow_mid_high": np.round(params["tint_shift"], 2).tolist(),
+        "sat_ratio": round(params["sat_ratio"], 3),
+        "green_rot_deg": round(params["green_rot_deg"], 1),
+        "green_sat": round(params["green_sat"], 3),
+    }
+    print(json.dumps(summary))
+    if a.report:
+        with open(a.report, "w", encoding="utf-8") as fh:
+            json.dump(summary, fh, indent=2)
+
+
+if __name__ == "__main__":
+    main()

package/template/scripts/lib/media.mjs

@@ -0,0 +1,228 @@
+/**
+ * Shared media helpers for the analysis scripts (beats, sync, reference style).
+ * Everything goes through ffmpeg; nothing here needs Python or a GPU.
+ */
+import {spawnSync} from 'node:child_process';
+import {existsSync} from 'node:fs';
+import {createRequire} from 'node:module';
+import {dirname, join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/** The studio root, found from this file rather than from wherever the shell happens to be. */
+const STUDIO = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+/**
+ * Find ffmpeg wherever this machine keeps it, in order of how reliable it is:
+ *
+ *   1. $FFMPEG / $FFPROBE, for anyone who knows exactly what they want.
+ *   2. The ffmpeg-static / ffprobe-static packages, which ship a binary per platform and
+ *      arrive with `npm install`. This is the one that makes a fresh machine just work —
+ *      no Homebrew, no winget, no PATH editing, nothing for anyone to get wrong.
+ *   3. Whatever is on PATH.
+ *   4. The usual install locations per platform.
+ *
+ * Every script goes through this, so a studio behaves the same on a Mac laptop as on a
+ * Windows desktop, and the same for us as for someone who bought it this morning.
+ */
+const require_ = createRequire(import.meta.url);
+
+const fromPackage = (tool) => {
+  try {
+    const mod = require_(`${tool}-static`);
+    const resolved = typeof mod === 'string' ? mod : mod?.path;
+    return resolved && existsSync(resolved) ? resolved : null;
+  } catch {
+    return null; // Not installed — fall through to the system copy.
+  }
+};
+
+const locate = (tool) => {
+  const fromEnv = process.env[tool.toUpperCase()];
+  if (fromEnv) return fromEnv;
+
+  const packaged = fromPackage(tool);
+  if (packaged) return packaged;
+
+  const win = process.platform === 'win32';
+  const exe = win ? `${tool}.exe` : tool;
+
+  // On PATH is the common case once the installer has run.
+  const which = spawnSync(win ? 'where' : 'which', [exe], {encoding: 'utf8'});
+  if (which.status === 0) {
+    const hit = which.stdout.split('\n')[0].trim();
+    if (hit) return hit;
+  }
+
+  const candidates = win
+    ? [`C:\\ffmpeg\\bin\\${exe}`, `D:\\Tools\\ffmpeg\\bin\\${exe}`, `${process.env.LOCALAPPDATA}\\ffmpeg\\bin\\${exe}`]
+    : [`/opt/homebrew/bin/${exe}`, `/usr/local/bin/${exe}`, `/usr/bin/${exe}`, `${process.env.HOME}/.local/bin/${exe}`];
+  for (const c of candidates) if (c && existsSync(c)) return c;
+
+  // Fall back to the bare name so the error says "not found" rather than a wrong path.
+  return exe;
+};
+
+export const FFMPEG = locate('ffmpeg');
+export const FFPROBE = locate('ffprobe');
+
+/**
+ * The Python that has the studio's packages. A virtual environment inside the studio wins,
+ * then $PYTHON, then whatever is on PATH. Mac and Linux answer to `python3`; a bare
+ * `python` there is often Python 2 or nothing at all.
+ */
+export const PYTHON = (() => {
+  if (process.env.PYTHON) return process.env.PYTHON;
+  const win = process.platform === 'win32';
+  // Resolved against the studio, not the cwd: run any of these scripts from another folder
+  // and a cwd-relative path silently misses the venv, falls through to whatever python is
+  // on PATH, and dies with ModuleNotFoundError as though nothing had ever been installed.
+  const venv = win ? join(STUDIO, '.venv', 'Scripts', 'python.exe') : join(STUDIO, '.venv', 'bin', 'python3');
+  if (existsSync(venv)) return venv;
+  for (const name of win ? ['python.exe', 'python3.exe'] : ['python3', 'python']) {
+    const which = spawnSync(win ? 'where' : 'which', [name], {encoding: 'utf8'});
+    if (which.status === 0) {
+      const hit = which.stdout.split('\n')[0].trim();
+      if (hit) return hit;
+    }
+  }
+  return win ? 'python' : 'python3';
+})();
+
+export function run(bin, args, opts = {}) {
+  const r = spawnSync(bin, args, {encoding: 'utf8', maxBuffer: 1024 * 1024 * 256, ...opts});
+  return {ok: r.status === 0, out: r.stdout || '', err: r.stderr || '', status: r.status};
+}
+
+export function probe(path) {
+  const r = run(FFPROBE, [
+    '-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', path,
+  ]);
+  if (!r.ok) return null;
+  try {
+    const data = JSON.parse(r.out);
+    const v = (data.streams || []).find((s) => s.codec_type === 'video');
+    const a = (data.streams || []).find((s) => s.codec_type === 'audio');
+    const [n, d] = String(v?.r_frame_rate || '0/1').split('/').map(Number);
+    return {
+      duration: Number(data.format?.duration || 0),
+      width: v?.width ?? 0,
+      height: v?.height ?? 0,
+      fps: d ? n / d : 0,
+      hasAudio: Boolean(a),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Decode any media's audio to mono float32 samples at the given rate. */
+export function decodePcm(path, rate = 22050) {
+  const r = spawnSync(
+    FFMPEG,
+    ['-v', 'error', '-i', path, '-vn', '-ac', '1', '-ar', String(rate), '-f', 'f32le', '-'],
+    {maxBuffer: 1024 * 1024 * 512, encoding: 'buffer'},
+  );
+  if (r.status !== 0 || !r.stdout?.length) return null;
+  const buf = r.stdout;
+  const usable = buf.length - (buf.length % 4);
+  return new Float32Array(buf.buffer, buf.byteOffset, usable / 4);
+}
+
+/** In-place iterative radix-2 FFT. re/im are Float64Array of length 2^k. */
+export function fft(re, im) {
+  const n = re.length;
+  for (let i = 1, j = 0; i < n; i++) {
+    let bit = n >> 1;
+    for (; j & bit; bit >>= 1) j ^= bit;
+    j ^= bit;
+    if (i < j) {
+      [re[i], re[j]] = [re[j], re[i]];
+      [im[i], im[j]] = [im[j], im[i]];
+    }
+  }
+  for (let len = 2; len <= n; len <<= 1) {
+    const ang = (-2 * Math.PI) / len;
+    const wr = Math.cos(ang);
+    const wi = Math.sin(ang);
+    for (let i = 0; i < n; i += len) {
+      let cr = 1;
+      let ci = 0;
+      for (let k = 0; k < len / 2; k++) {
+        const ur = re[i + k];
+        const ui = im[i + k];
+        const vr = re[i + k + len / 2] * cr - im[i + k + len / 2] * ci;
+        const vi = re[i + k + len / 2] * ci + im[i + k + len / 2] * cr;
+        re[i + k] = ur + vr;
+        im[i + k] = ui + vi;
+        re[i + k + len / 2] = ur - vr;
+        im[i + k + len / 2] = ui - vi;
+        const ncr = cr * wr - ci * wi;
+        ci = cr * wi + ci * wr;
+        cr = ncr;
+      }
+    }
+  }
+}
+
+/**
+ * Onset strength over time (spectral flux): how much new energy arrives in each
+ * short window. This is the signal every beat and cut detector is built on.
+ */
+export function onsetEnvelope(samples, rate, {frameSize = 1024, hop = 512} = {}) {
+  const frames = Math.max(0, Math.floor((samples.length - frameSize) / hop));
+  const env = new Float64Array(frames);
+  const window = new Float64Array(frameSize);
+  for (let i = 0; i < frameSize; i++) window[i] = 0.5 - 0.5 * Math.cos((2 * Math.PI * i) / (frameSize - 1));
+  let prev = new Float64Array(frameSize / 2);
+  const re = new Float64Array(frameSize);
+  const im = new Float64Array(frameSize);
+  for (let f = 0; f < frames; f++) {
+    const off = f * hop;
+    for (let i = 0; i < frameSize; i++) {
+      re[i] = samples[off + i] * window[i];
+      im[i] = 0;
+    }
+    fft(re, im);
+    let flux = 0;
+    const mag = new Float64Array(frameSize / 2);
+    for (let b = 0; b < frameSize / 2; b++) {
+      const m = Math.sqrt(re[b] * re[b] + im[b] * im[b]);
+      mag[b] = m;
+      const diff = m - prev[b];
+      if (diff > 0) flux += diff;
+    }
+    env[f] = flux;
+    prev = mag;
+  }
+  return {env, hopSeconds: hop / rate};
+}
+
+/** Loudness envelope, used for lining two recordings up against each other. */
+export function energyEnvelope(samples, rate, hop = 256) {
+  const frames = Math.floor(samples.length / hop);
+  const env = new Float64Array(frames);
+  for (let f = 0; f < frames; f++) {
+    let sum = 0;
+    for (let i = 0; i < hop; i++) {
+      const s = samples[f * hop + i];
+      sum += s * s;
+    }
+    env[f] = Math.sqrt(sum / hop);
+  }
+  return {env, hopSeconds: hop / rate};
+}
+
+export const mean = (a) => (a.length ? a.reduce((x, y) => x + y, 0) / a.length : 0);
+export const median = (a) => {
+  if (!a.length) return 0;
+  const s = [...a].sort((x, y) => x - y);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+export const fmt = (n, d = 2) => Number(n).toFixed(d);
+export const timecode = (sec) => {
+  const s = Math.max(0, sec);
+  const mm = String(Math.floor(s / 60)).padStart(2, '0');
+  const ss = String(Math.floor(s % 60)).padStart(2, '0');
+  return `${mm}:${ss}`;
+};

package/template/scripts/lib/media.py

@@ -0,0 +1,99 @@
+"""
+Shared tool resolution for the Python helpers.
+
+The Node side has lib/media.mjs; this is its twin, and it exists for the same reason:
+every script that shells out to ffmpeg must ask *here* where ffmpeg is, never hardcode a
+path. Seven scripts once carried `D:\\Tools\\ffmpeg\\bin\\ffmpeg.exe`, which meant the
+whole Python half of the studio was dead on any machine that was not one specific Windows
+desktop. A studio that only runs on its author's computer is not a product.
+
+Resolution order, most explicit first:
+  1. $FFMPEG / $FFPROBE, for anyone who knows exactly what they want
+  2. the ffmpeg-static / ffprobe-static binaries that arrive with `npm install`
+  3. whatever is on PATH
+  4. the usual install locations per platform
+"""
+
+import os
+import platform
+import shutil
+from pathlib import Path
+
+_IS_WIN = platform.system() == "Windows"
+_EXE = ".exe" if _IS_WIN else ""
+
+# Repo root, from scripts/lib/media.py
+_ROOT = Path(__file__).resolve().parent.parent.parent
+
+
+def _from_node_modules(tool: str):
+    """The per-platform binary npm installs. Present in every studio after setup."""
+    pkg = _ROOT / "node_modules" / f"{tool}-static"
+    if not pkg.is_dir():
+        return None
+    # ffmpeg-static puts the binary at the package root; ffprobe-static nests it per platform.
+    direct = pkg / f"{tool}{_EXE}"
+    if direct.is_file():
+        return str(direct)
+    for found in pkg.rglob(f"{tool}{_EXE}"):
+        if found.is_file():
+            return str(found)
+    return None
+
+
+def _candidates(tool: str):
+    if _IS_WIN:
+        return [
+            rf"C:\ffmpeg\bin\{tool}{_EXE}",
+            rf"D:\Tools\ffmpeg\bin\{tool}{_EXE}",
+            os.path.join(os.environ.get("LOCALAPPDATA", ""), "ffmpeg", "bin", f"{tool}{_EXE}"),
+        ]
+    return [
+        f"/opt/homebrew/bin/{tool}",
+        f"/usr/local/bin/{tool}",
+        f"/usr/bin/{tool}",
+        os.path.expanduser(f"~/.local/bin/{tool}"),
+    ]
+
+
+def locate(tool: str) -> str:
+    from_env = os.environ.get(tool.upper())
+    if from_env:
+        return from_env
+
+    packaged = _from_node_modules(tool)
+    if packaged:
+        return packaged
+
+    on_path = shutil.which(tool)
+    if on_path:
+        return on_path
+
+    for candidate in _candidates(tool):
+        if candidate and Path(candidate).is_file():
+            return candidate
+
+    # Fall back to the bare name so the error reads "not found" rather than a wrong path.
+    return tool
+
+
+FFMPEG = locate("ffmpeg")
+FFPROBE = locate("ffprobe")
+
+
+def use_certifi() -> None:
+    """
+    Point urllib at certifi's root certificates.
+
+    torch.hub downloads model weights with urllib, which on a python.org macOS build has
+    no root certificates at all — so transcription dies with CERTIFICATE_VERIFY_FAILED
+    partway through, after the slow part has already succeeded. Call this before importing
+    torch in any script that downloads a model.
+    """
+    try:
+        import certifi
+    except ImportError:
+        return
+    bundle = certifi.where()
+    os.environ.setdefault("SSL_CERT_FILE", bundle)
+    os.environ.setdefault("REQUESTS_CA_BUNDLE", bundle)

package/template/scripts/make_cutout.py

@@ -0,0 +1,68 @@
+"""Build a transparent cutout of the subject for a frame range of a paired clip.
+
+Usage (from the project root):
+    python scripts/make_cutout.py <original> <greenscreen> <out_dir> <first_frame> <last_frame>
+
+The green-screen clip is used ONLY for the matte (alpha). Colour comes from the original clip, so no
+green ever reaches the subject's edges. Writes RGBA PNGs named f<frame>.png (absolute source frame
+numbers) so compositions can map composition frames to cutout frames directly.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+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
+
+
+
+W, H, FPS = 1920, 1080, 30
+
+
+def read_frames(path: str, first: int, count: int):
+    proc = subprocess.Popen(
+        [FFMPEG, "-v", "error", "-ss", f"{first / FPS:.6f}", "-i", path, "-frames:v", str(count),
+         "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+        stdout=subprocess.PIPE,
+    )
+    size = W * H * 3
+    for _ in range(count):
+        buf = proc.stdout.read(size)
+        if len(buf) < size:
+            break
+        yield np.frombuffer(buf, np.uint8).reshape(H, W, 3)
+    proc.stdout.close()
+    proc.wait()
+
+
+def matte(green: np.ndarray) -> np.ndarray:
+    """Alpha 0..1 from how green each pixel is, relative to the flat background green."""
+    g = green.astype(np.float32)
+    greenness = g[..., 1] - np.maximum(g[..., 0], g[..., 2])
+    background = np.median(greenness[greenness > 60]) if (greenness > 60).any() else 150.0
+    lo, hi = 0.2 * background, 0.7 * background
+    t = np.clip((greenness - lo) / (hi - lo), 0, 1)
+    alpha = 1 - t * t * (3 - 2 * t)  # smoothstep: soft, stable edge
+    # Choke by 1px so the background never leaks in, then feather lightly.
+    choked = np.minimum.reduce([alpha, np.roll(alpha, 1, 0), np.roll(alpha, -1, 0), np.roll(alpha, 1, 1), np.roll(alpha, -1, 1)])
+    feathered = (choked * 4 + np.roll(choked, 1, 0) + np.roll(choked, -1, 0) + np.roll(choked, 1, 1) + np.roll(choked, -1, 1)) / 8
+    return feathered
+
+
+def main() -> None:
+    original, greenscreen, out_dir, first, last = sys.argv[1], sys.argv[2], Path(sys.argv[3]), int(sys.argv[4]), int(sys.argv[5])
+    out_dir.mkdir(parents=True, exist_ok=True)
+    count = last - first + 1
+    for offset, (rgb, green) in enumerate(zip(read_frames(original, first, count), read_frames(greenscreen, first, count))):
+        alpha = (matte(green) * 255).round().astype(np.uint8)
+        rgba = np.dstack([rgb, alpha])
+        Image.fromarray(rgba, "RGBA").save(out_dir / f"f{first + offset}.png", compress_level=1)
+    print(f"wrote {count} frames to {out_dir}")
+
+
+if __name__ == "__main__":
+    main()