@prestyj/editor 0.7.1

package/dist/core/multicam.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import * as ffmpeg from "./media/ffmpeg.js";
+import { multicamSync } from "./multicam.js";
+function silenceStderr(endSec) {
+    if (endSec === null)
+        return "";
+    return `[silencedetect @ 0x1] silence_start: 0.0\n[silencedetect @ 0x1] silence_end: ${endSec} | silence_duration: ${endSec}\n`;
+}
+describe("multicamSync", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("picks the input with the smallest transient as reference", async () => {
+        // a=2.0s, b=0.5s, c=1.2s — b should be reference (smallest).
+        const map = { "/a.wav": 2.0, "/b.wav": 0.5, "/c.wav": 1.2 };
+        vi.spyOn(ffmpeg, "runFfmpeg").mockImplementation(async (args) => {
+            const path = args[args.indexOf("-i") + 1];
+            return { code: 0, stdout: "", stderr: silenceStderr(map[path] ?? null) };
+        });
+        const r = await multicamSync(["/a.wav", "/b.wav", "/c.wav"]);
+        expect(r.reference).toBe("/b.wav");
+        expect(r.warning).toBeUndefined();
+        const byPath = Object.fromEntries(r.results.map((x) => [x.path, x.offsetSec]));
+        expect(byPath["/b.wav"]).toBe(0);
+        expect(byPath["/a.wav"]).toBeCloseTo(1.5);
+        expect(byPath["/c.wav"]).toBeCloseTo(0.7);
+    });
+    it("emits a warning and null offset for files with no transient", async () => {
+        const map = { "/x.wav": 1.0, "/y.wav": null };
+        vi.spyOn(ffmpeg, "runFfmpeg").mockImplementation(async (args) => {
+            const path = args[args.indexOf("-i") + 1];
+            return { code: 0, stdout: "", stderr: silenceStderr(map[path] ?? null) };
+        });
+        const r = await multicamSync(["/x.wav", "/y.wav"]);
+        expect(r.reference).toBe("/x.wav");
+        const yResult = r.results.find((x) => x.path === "/y.wav");
+        expect(yResult?.offsetSec).toBeNull();
+        expect(yResult?.transientSec).toBeNull();
+        expect(r.warning).toMatch(/no transient detected for 1 of 2/);
+    });
+    it("trivially handles a single-file input", async () => {
+        vi.spyOn(ffmpeg, "runFfmpeg").mockResolvedValue({
+            code: 0,
+            stdout: "",
+            stderr: silenceStderr(0.8),
+        });
+        const r = await multicamSync(["/solo.wav"]);
+        expect(r.reference).toBe("/solo.wav");
+        expect(r.results).toHaveLength(1);
+        expect(r.results[0].offsetSec).toBe(0);
+    });
+    it("rejects empty input", async () => {
+        await expect(multicamSync([])).rejects.toThrow(/empty/);
+    });
+});
+//# sourceMappingURL=multicam.test.js.map

package/dist/core/multicam.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multicam.test.js","sourceRoot":"","sources":["../../src/core/multicam.test.ts"],"names":[],"mappings":"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"}

package/dist/core/punch-in.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Punch-in (digital zoom on cuts) — the canonical YouTuber trick to
+ * disguise jump cuts on a single-camera talking head. Cut filler →
+ * punch in slightly on the kept side → the head-jerk vanishes.
+ *
+ * We implement this with an ffmpeg `crop` filter whose width / height /
+ * x / y values are EXPRESSIONS that depend on `t` (current frame
+ * timestamp). Outside any punch range, expressions evaluate to a
+ * full-frame crop (no-op). Inside a range, they evaluate to a centered
+ * sub-frame crop, then a `scale` brings it back to the original size.
+ *
+ * One ffmpeg pass, no segmenting + concat — fast and simple.
+ *
+ * The math, for a punch range with zoom Z (>1, e.g. 1.10 = 10% punch):
+ *   crop_w = floor(iw / Z)
+ *   crop_h = floor(ih / Z)
+ *   crop_x = floor((iw - crop_w) / 2)
+ *   crop_y = floor((ih - crop_h) / 2)
+ *
+ * To stitch multiple ranges into a single expression, we wrap each
+ * tier in `if(between(t, a, b), <punched>, <prev>)`, falling back to a
+ * full-frame crop outside any range.
+ *
+ * Pure logic; the tool wrapper handles ffmpeg invocation.
+ */
+export interface PunchInRange {
+    /** Range start (seconds, inclusive). */
+    startSec: number;
+    /** Range end (seconds, inclusive). */
+    endSec: number;
+    /**
+     * Zoom multiplier. 1.10 = 10% punch (subtle, the YouTuber default).
+     * 1.0 = no zoom (effectively skipped). Clamped to [1.0, 2.0].
+     */
+    zoom: number;
+}
+export interface PunchInOptions {
+    /**
+     * Default zoom for ranges where `zoom` is omitted. Default 1.10.
+     * 1.05 is barely perceptible; 1.15 is a clear pop; >1.20 looks like
+     * an effect rather than a hidden cut.
+     */
+    defaultZoom?: number;
+    /**
+     * Optional smoothing window (seconds) at each edge to prevent the
+     * crop from snapping. The crop gradually ramps from 1.0 → zoom over
+     * `rampSec` at the start, and back at the end. Default 0 (instant).
+     * Use ~0.08s for subtle, ~0.15s for a noticeable push-in.
+     */
+    rampSec?: number;
+}
+/**
+ * Build the `-vf` value for ffmpeg that applies all punch ranges in
+ * order. Returns the empty string if there are no ranges (no-op
+ * caller can decide whether to skip ffmpeg altogether).
+ *
+ * The filter is structured as `crop=W:H:X:Y,scale=iw_orig:ih_orig`,
+ * where W/H/X/Y are nested if-expressions evaluated per-frame.
+ */
+export declare function buildPunchInFilter(ranges: PunchInRange[], origWidth: number, origHeight: number, opts?: PunchInOptions): string;
+/**
+ * Auto-derive punch-in ranges from a list of cut points (e.g. the
+ * timestamps of every silence-cut or filler-cut). One short punch
+ * after each cut hides the discontinuity.
+ *
+ * @param cutPoints  Seconds where cuts happen.
+ * @param totalSec   Media duration (so the last range gets clipped).
+ * @param holdSec    How long each punch lasts after the cut. Default 1.5s.
+ * @param zoom       Zoom multiplier. Default 1.10.
+ */
+export declare function punchInsAfterCuts(cutPoints: number[], totalSec: number, holdSec?: number, zoom?: number): PunchInRange[];
+//# sourceMappingURL=punch-in.d.ts.map

package/dist/core/punch-in.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"punch-in.d.ts","sourceRoot":"","sources":["../../src/core/punch-in.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,YAAY,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,cAAmB,GACxB,MAAM,CAqCR;AA+BD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,SAAM,EACb,IAAI,SAAM,GACT,YAAY,EAAE,CAYhB"}

package/dist/core/punch-in.js

@@ -0,0 +1,133 @@
+/**
+ * Punch-in (digital zoom on cuts) — the canonical YouTuber trick to
+ * disguise jump cuts on a single-camera talking head. Cut filler →
+ * punch in slightly on the kept side → the head-jerk vanishes.
+ *
+ * We implement this with an ffmpeg `crop` filter whose width / height /
+ * x / y values are EXPRESSIONS that depend on `t` (current frame
+ * timestamp). Outside any punch range, expressions evaluate to a
+ * full-frame crop (no-op). Inside a range, they evaluate to a centered
+ * sub-frame crop, then a `scale` brings it back to the original size.
+ *
+ * One ffmpeg pass, no segmenting + concat — fast and simple.
+ *
+ * The math, for a punch range with zoom Z (>1, e.g. 1.10 = 10% punch):
+ *   crop_w = floor(iw / Z)
+ *   crop_h = floor(ih / Z)
+ *   crop_x = floor((iw - crop_w) / 2)
+ *   crop_y = floor((ih - crop_h) / 2)
+ *
+ * To stitch multiple ranges into a single expression, we wrap each
+ * tier in `if(between(t, a, b), <punched>, <prev>)`, falling back to a
+ * full-frame crop outside any range.
+ *
+ * Pure logic; the tool wrapper handles ffmpeg invocation.
+ */
+/**
+ * Build the `-vf` value for ffmpeg that applies all punch ranges in
+ * order. Returns the empty string if there are no ranges (no-op
+ * caller can decide whether to skip ffmpeg altogether).
+ *
+ * The filter is structured as `crop=W:H:X:Y,scale=iw_orig:ih_orig`,
+ * where W/H/X/Y are nested if-expressions evaluated per-frame.
+ */
+export function buildPunchInFilter(ranges, origWidth, origHeight, opts = {}) {
+    if (origWidth <= 0 || origHeight <= 0) {
+        throw new Error("origWidth and origHeight must be positive");
+    }
+    const defaultZoom = clampZoom(opts.defaultZoom ?? 1.1);
+    const ramp = Math.max(0, opts.rampSec ?? 0);
+    const cleaned = ranges
+        .map((r) => ({
+        startSec: r.startSec,
+        endSec: r.endSec,
+        zoom: clampZoom(r.zoom || defaultZoom),
+    }))
+        .filter((r) => r.endSec > r.startSec && r.zoom > 1.0001)
+        .sort((a, b) => a.startSec - b.startSec);
+    if (cleaned.length === 0)
+        return "";
+    // We construct one expression for the crop WIDTH and one for HEIGHT.
+    // X/Y are derived as (orig - crop) / 2 inside ffmpeg's expression
+    // language so we don't need to repeat the zoom logic.
+    //
+    // Effective per-range zoom (with ramp):
+    //   rampedZoom(t) = 1 + (Z - 1) * clamp01(min((t - a)/ramp, (b - t)/ramp))
+    //   when ramp > 0; otherwise just Z.
+    const widthExpr = buildSizeExpr(cleaned, "iw", ramp);
+    const heightExpr = buildSizeExpr(cleaned, "ih", ramp);
+    // x,y center the crop. ffmpeg: `(iw-out_w)/2`, `(ih-out_h)/2` — using
+    // the special vars `out_w` / `out_h` that reference the crop's own
+    // width / height expressions.
+    const cropFilter = `crop=w='${widthExpr}':h='${heightExpr}':x='(iw-out_w)/2':y='(ih-out_h)/2'`;
+    // Re-scale the (smaller) crop back to the source resolution so the
+    // output stream stays the same size as the input. Use lanczos for
+    // sharp upscale.
+    const scaleFilter = `scale=${origWidth}:${origHeight}:flags=lanczos`;
+    return `${cropFilter},${scaleFilter}`;
+}
+/**
+ * Build a piecewise expression for either the cropped width or height.
+ * `dim` is the ffmpeg variable for the source size ("iw" / "ih").
+ */
+function buildSizeExpr(ranges, dim, ramp) {
+    // Outside any range, the cropped dimension == source dimension (no-op).
+    let expr = dim;
+    // Build from the LAST range backwards so each `if(cond, then, else)`
+    // wraps the previously-built else-branch.
+    for (let i = ranges.length - 1; i >= 0; i--) {
+        const { startSec, endSec, zoom } = ranges[i];
+        const a = fmt(startSec);
+        const b = fmt(endSec);
+        let zExpr;
+        if (ramp > 0) {
+            // 1 + (Z-1) * clamp01(min((t-a)/ramp, (b-t)/ramp))
+            const r = fmt(ramp);
+            const factor = `clip(min((t-${a})/${r}\\,(${b}-t)/${r})\\,0\\,1)`;
+            zExpr = `(1+${fmt(zoom - 1)}*${factor})`;
+        }
+        else {
+            zExpr = fmt(zoom);
+        }
+        // Cropped dim = source / zoom.
+        const inside = `${dim}/${zExpr}`;
+        expr = `if(between(t\\,${a}\\,${b})\\,${inside}\\,${expr})`;
+    }
+    return expr;
+}
+/**
+ * Auto-derive punch-in ranges from a list of cut points (e.g. the
+ * timestamps of every silence-cut or filler-cut). One short punch
+ * after each cut hides the discontinuity.
+ *
+ * @param cutPoints  Seconds where cuts happen.
+ * @param totalSec   Media duration (so the last range gets clipped).
+ * @param holdSec    How long each punch lasts after the cut. Default 1.5s.
+ * @param zoom       Zoom multiplier. Default 1.10.
+ */
+export function punchInsAfterCuts(cutPoints, totalSec, holdSec = 1.5, zoom = 1.1) {
+    const sorted = [...cutPoints].filter((t) => t >= 0 && t < totalSec).sort((a, b) => a - b);
+    const out = [];
+    for (let i = 0; i < sorted.length; i++) {
+        const start = sorted[i];
+        // Don't run a punch into the next cut.
+        const next = sorted[i + 1] ?? totalSec;
+        const end = Math.min(start + holdSec, next, totalSec);
+        if (end - start < 0.1)
+            continue; // skip tiny/no-op ranges
+        out.push({ startSec: start, endSec: end, zoom });
+    }
+    return out;
+}
+function fmt(n) {
+    if (!Number.isFinite(n))
+        return "0";
+    // Use 4 decimals; trim trailing zeros for shorter expressions.
+    return Number(n.toFixed(4)).toString();
+}
+function clampZoom(z) {
+    if (!Number.isFinite(z))
+        return 1;
+    return Math.max(1.0, Math.min(2.0, z));
+}
+//# sourceMappingURL=punch-in.js.map

package/dist/core/punch-in.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"punch-in.js","sourceRoot":"","sources":["../../src/core/punch-in.ts"],"names":[],"mappings":"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"}

package/dist/core/punch-in.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=punch-in.test.d.ts.map

package/dist/core/punch-in.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"punch-in.test.d.ts","sourceRoot":"","sources":["../../src/core/punch-in.test.ts"],"names":[],"mappings":""}

package/dist/core/punch-in.test.js

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import { buildPunchInFilter, punchInsAfterCuts } from "./punch-in.js";
+describe("buildPunchInFilter", () => {
+    it("returns empty string when there are no ranges", () => {
+        expect(buildPunchInFilter([], 1920, 1080)).toBe("");
+    });
+    it("emits a crop+scale filter for a single range", () => {
+        const f = buildPunchInFilter([{ startSec: 1, endSec: 2, zoom: 1.1 }], 1920, 1080);
+        expect(f).toContain("crop=");
+        expect(f).toContain("scale=1920:1080");
+        expect(f).toContain("between(t");
+        // Centered crop math:
+        expect(f).toContain("(iw-out_w)/2");
+        expect(f).toContain("(ih-out_h)/2");
+        // Inside the range, width = iw / zoom
+        expect(f).toContain("iw/1.1");
+        expect(f).toContain("ih/1.1");
+    });
+    it("nests multiple ranges into a single piecewise expression", () => {
+        const f = buildPunchInFilter([
+            { startSec: 1, endSec: 2, zoom: 1.1 },
+            { startSec: 5, endSec: 6, zoom: 1.2 },
+        ], 1920, 1080);
+        // Both zoom levels appear:
+        expect(f).toContain("iw/1.1");
+        expect(f).toContain("iw/1.2");
+        // And both ranges:
+        expect(f).toContain("between(t\\,1\\,2)");
+        expect(f).toContain("between(t\\,5\\,6)");
+    });
+    it("falls through to a no-op (full source size) outside ranges", () => {
+        const f = buildPunchInFilter([{ startSec: 1, endSec: 2, zoom: 1.1 }], 1920, 1080);
+        // The ELSE branch of the outermost if() should reference iw / ih.
+        // Walk: if(between(t,1,2), iw/1.1, iw)
+        expect(f).toMatch(/iw\/1\.1\\,iw/);
+        expect(f).toMatch(/ih\/1\.1\\,ih/);
+    });
+    it("clamps zoom into [1.0, 2.0]", () => {
+        // 9.0 should clamp to 2.0; 0.5 should clamp to 1.0 (and then be filtered out).
+        const f = buildPunchInFilter([
+            { startSec: 1, endSec: 2, zoom: 9.0 },
+            { startSec: 3, endSec: 4, zoom: 0.5 },
+        ], 1920, 1080);
+        expect(f).toContain("iw/2");
+        // The 0.5-zoom range collapses to a no-op and should be dropped:
+        expect(f).not.toContain("between(t\\,3\\,4)");
+    });
+    it("uses defaultZoom when an explicit zoom is missing or 0", () => {
+        const f = buildPunchInFilter([{ startSec: 1, endSec: 2, zoom: 0 }], 1920, 1080, {
+            defaultZoom: 1.15,
+        });
+        expect(f).toContain("iw/1.15");
+    });
+    it("applies a ramp expression when rampSec > 0", () => {
+        const f = buildPunchInFilter([{ startSec: 1, endSec: 2, zoom: 1.1 }], 1920, 1080, {
+            rampSec: 0.1,
+        });
+        expect(f).toContain("clip(");
+        expect(f).toContain("min(");
+        // Constant zoom term should NOT appear when ramping:
+        expect(f).not.toContain("iw/1.1,");
+    });
+    it("rejects non-positive source dimensions", () => {
+        expect(() => buildPunchInFilter([{ startSec: 0, endSec: 1, zoom: 1.1 }], 0, 1080)).toThrow();
+        expect(() => buildPunchInFilter([{ startSec: 0, endSec: 1, zoom: 1.1 }], 1920, -1)).toThrow();
+    });
+    it("drops zero-duration / inverted ranges", () => {
+        const f = buildPunchInFilter([
+            { startSec: 1, endSec: 1, zoom: 1.1 },
+            { startSec: 5, endSec: 4, zoom: 1.1 },
+            { startSec: 10, endSec: 11, zoom: 1.1 },
+        ], 1920, 1080);
+        expect(f).toContain("between(t\\,10\\,11)");
+        expect(f).not.toContain("between(t\\,1\\,1)");
+        expect(f).not.toContain("between(t\\,5\\,4)");
+    });
+    it("emits ranges sorted by start time even when caller passes them out of order", () => {
+        const f = buildPunchInFilter([
+            { startSec: 5, endSec: 6, zoom: 1.2 },
+            { startSec: 1, endSec: 2, zoom: 1.1 },
+        ], 1920, 1080);
+        // Outer if should be the first sorted range; inner else handles the second.
+        const idx1 = f.indexOf("between(t\\,1\\,2)");
+        const idx5 = f.indexOf("between(t\\,5\\,6)");
+        expect(idx1).toBeGreaterThanOrEqual(0);
+        expect(idx5).toBeGreaterThanOrEqual(0);
+        expect(idx1).toBeLessThan(idx5);
+    });
+});
+describe("punchInsAfterCuts", () => {
+    it("emits a punch range starting at each cut", () => {
+        const ranges = punchInsAfterCuts([2, 5, 9], 12, 1.5, 1.1);
+        expect(ranges).toEqual([
+            { startSec: 2, endSec: 3.5, zoom: 1.1 },
+            { startSec: 5, endSec: 6.5, zoom: 1.1 },
+            { startSec: 9, endSec: 10.5, zoom: 1.1 },
+        ]);
+    });
+    it("never overlaps the next cut", () => {
+        const ranges = punchInsAfterCuts([2, 2.4], 10, 1.5, 1.1);
+        expect(ranges[0].endSec).toBe(2.4);
+        expect(ranges[1].startSec).toBe(2.4);
+    });
+    it("clips the last range at totalSec", () => {
+        const ranges = punchInsAfterCuts([8.5], 9, 1.5, 1.1);
+        expect(ranges[0].endSec).toBe(9);
+    });
+    it("filters out cuts outside [0, totalSec)", () => {
+        const ranges = punchInsAfterCuts([-1, 0, 5, 11, 12], 10);
+        expect(ranges.map((r) => r.startSec)).toEqual([0, 5]);
+    });
+    it("drops sub-100ms residual ranges", () => {
+        // cut at 9.95 with totalSec 10 → 0.05s window — too small.
+        const ranges = punchInsAfterCuts([9.95], 10, 1.5, 1.1);
+        expect(ranges).toEqual([]);
+    });
+});
+//# sourceMappingURL=punch-in.test.js.map

package/dist/core/punch-in.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"punch-in.test.js","sourceRoot":"","sources":["../../src/core/punch-in.test.ts"],"names":[],"mappings":"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"}

package/dist/core/python/beats.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Beat detection sidecar.
+
+Reads JSON on stdin: {"audioPath": "...", "sr": <optional int>}
+Writes JSON on stdout: {"tempo": float, "beats": [seconds...], "durationSec": float}
+
+On error: prints {"error": "...", "trace": "..."} to stdout and exits 1.
+
+Required deps:  pip install librosa numpy soundfile
+"""
+import sys
+import json
+import traceback
+
+
+def main():
+    try:
+        import librosa  # noqa: F401  (heavy import — failure surfaces as ImportError below)
+        import numpy as np
+    except ImportError as e:
+        print(json.dumps({
+            "error": f"missing python dep: {e.name}; install librosa numpy soundfile",
+        }))
+        sys.exit(1)
+
+    raw = sys.stdin.read() or "{}"
+    try:
+        args = json.loads(raw)
+    except Exception as e:
+        print(json.dumps({"error": f"invalid stdin JSON: {e}"}))
+        sys.exit(1)
+
+    audio_path = args.get("audioPath")
+    if not audio_path:
+        print(json.dumps({"error": "missing required arg: audioPath"}))
+        sys.exit(1)
+    sr = args.get("sr")  # may be None — librosa default
+
+    y, sr_used = librosa.load(audio_path, sr=sr, mono=True)
+    duration = float(librosa.get_duration(y=y, sr=sr_used))
+    tempo, beats = librosa.beat.beat_track(y=y, sr=sr_used, units="time")
+    # librosa>=0.10 returns numpy 1d array for tempo; collapse to scalar.
+    if hasattr(tempo, "__len__"):
+        tempo = float(np.atleast_1d(tempo)[0])
+
+    print(json.dumps({
+        "tempo": float(tempo),
+        "beats": [float(b) for b in beats],
+        "durationSec": duration,
+    }))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(json.dumps({
+            "error": str(e),
+            "trace": traceback.format_exc()[-500:],
+        }))
+        sys.exit(1)

package/dist/core/python/face_reframe.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Face-tracked reframe analysis sidecar.
+
+Reads JSON on stdin:
+  {
+    "videoPath": "...",
+    "sampleFps": <float, default 5.0>,
+    "minDetectionConfidence": <float, default 0.5>,
+    "smoothingWindowSec": <float, default 0.5>
+  }
+
+Writes JSON on stdout:
+  {
+    "shots": [{startSec, endSec, frames: [...], smoothedX, smoothedY, mode}],
+    "totalSec": float,
+    "fps": float,
+    "sourceWidth": int,
+    "sourceHeight": int
+  }
+
+On error: prints {"error": "...", "trace": "..."} to stdout and exits 1.
+
+Pipeline:
+  1. PySceneDetect (ContentDetector) -> shot boundaries.
+  2. For each shot, sample at sampleFps and run MediaPipe face_detection
+     (model_selection=1, full-range).
+  3. Pick the largest detection per frame; collect normalized centre.
+  4. Smooth via median (robust to dropouts) per shot. Mark shot as
+     "static" when no detections were found.
+
+Required deps:  pip install opencv-python mediapipe scenedetect numpy
+"""
+import sys
+import json
+import traceback
+
+
+def main():
+    try:
+        import cv2
+        import numpy as np
+        import mediapipe as mp
+        from scenedetect import detect, ContentDetector
+    except ImportError as e:
+        print(json.dumps({
+            "error": (
+                f"missing python dep: {e.name}; "
+                "install: pip install opencv-python mediapipe scenedetect numpy"
+            ),
+        }))
+        sys.exit(1)
+
+    raw = sys.stdin.read() or "{}"
+    try:
+        args = json.loads(raw)
+    except Exception as e:
+        print(json.dumps({"error": f"invalid stdin JSON: {e}"}))
+        sys.exit(1)
+
+    video = args.get("videoPath")
+    if not video:
+        print(json.dumps({"error": "missing required arg: videoPath"}))
+        sys.exit(1)
+    sample_fps = float(args.get("sampleFps", 5.0))
+    min_conf = float(args.get("minDetectionConfidence", 0.5))
+    # smooth_win currently informs window selection; we use a robust median
+    # over all in-shot samples which is tolerant to dropouts.
+    _smooth_win = float(args.get("smoothingWindowSec", 0.5))  # noqa: F841
+
+    cap = cv2.VideoCapture(video)
+    if not cap.isOpened():
+        print(json.dumps({"error": f"cannot open video: {video}"}))
+        sys.exit(1)
+    src_fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+    src_w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+    src_h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+    total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+    duration = total_frames / src_fps if src_fps > 0 else 0.0
+
+    # PySceneDetect — falls back to whole video if it errors.
+    try:
+        scenes = detect(video, ContentDetector(threshold=27))
+        shots = [(s[0].get_seconds(), s[1].get_seconds()) for s in scenes]
+    except Exception:
+        shots = []
+    if not shots:
+        shots = [(0.0, duration)]
+
+    detector = mp.solutions.face_detection.FaceDetection(
+        model_selection=1, min_detection_confidence=min_conf,
+    )
+
+    out_shots = []
+    sample_step = max(1, int(round(src_fps / sample_fps))) if sample_fps > 0 else 1
+    for shot_start, shot_end in shots:
+        frames_data = []
+        f0 = int(shot_start * src_fps)
+        f1 = int(shot_end * src_fps)
+        for f in range(f0, f1, sample_step):
+            cap.set(cv2.CAP_PROP_POS_FRAMES, f)
+            ok, img = cap.read()
+            if not ok:
+                continue
+            t = f / src_fps if src_fps > 0 else 0.0
+            rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+            res = detector.process(rgb)
+            if res.detections:
+                # Pick the largest face (in normalized area).
+                best = max(
+                    res.detections,
+                    key=lambda d: (
+                        d.location_data.relative_bounding_box.width
+                        * d.location_data.relative_bounding_box.height
+                    ),
+                )
+                bb = best.location_data.relative_bounding_box
+                cx = bb.xmin + bb.width / 2
+                cy = bb.ymin + bb.height / 2
+                frames_data.append({
+                    "atSec": t,
+                    "faceCx": float(cx),
+                    "faceCy": float(cy),
+                    "faceW": float(bb.width),
+                    "faceH": float(bb.height),
+                })
+
+        if frames_data:
+            xs = np.array([d["faceCx"] for d in frames_data])
+            ys = np.array([d["faceCy"] for d in frames_data])
+            mode = "face"
+            sx = float(np.median(xs))
+            sy = float(np.median(ys))
+        else:
+            mode = "static"
+            sx, sy = 0.5, 0.5
+        out_shots.append({
+            "startSec": float(shot_start),
+            "endSec": float(shot_end),
+            "frames": frames_data,
+            "smoothedX": sx,
+            "smoothedY": sy,
+            "mode": mode,
+        })
+
+    cap.release()
+    print(json.dumps({
+        "shots": out_shots,
+        "totalSec": float(duration),
+        "fps": float(src_fps),
+        "sourceWidth": src_w,
+        "sourceHeight": src_h,
+    }))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(json.dumps({
+            "error": str(e),
+            "trace": traceback.format_exc()[-500:],
+        }))
+        sys.exit(1)

package/dist/core/python/sidecar-path.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolve the on-disk path of a Python sidecar shipped under `src/core/python/`.
+ *
+ * In `src/` (during tests / dev), `import.meta.url` points inside `src/core/python/`
+ * so the script sits next to this file. In `dist/` (after `tsc`), the build's
+ * post-step copies `src/core/python/` → `dist/core/python/`, so the same
+ * relative resolution works.
+ *
+ * If the script cannot be found we throw — better an explicit error than
+ * silently spawning Python with a non-existent path.
+ */
+export declare function sidecarPath(filename: string): string;
+//# sourceMappingURL=sidecar-path.d.ts.map

package/dist/core/python/sidecar-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sidecar-path.d.ts","sourceRoot":"","sources":["../../../src/core/python/sidecar-path.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUpD"}