@kenkaiiii/gg-editor 0.1.0

package/dist/core/multicam.d.ts

@@ -0,0 +1,40 @@
+export interface TransientResult {
+    path: string;
+    /** Seconds from file start where the first audible event begins, or null. */
+    transientSec: number | null;
+}
+export interface MulticamSyncResult {
+    /** Path used as the t=0 reference (transient closest to file start). */
+    reference: string;
+    results: Array<{
+        path: string;
+        /** Positive = file starts later than reference. null = no transient detected. */
+        offsetSec: number | null;
+        transientSec: number | null;
+    }>;
+    thresholdDb: number;
+    /** Set if any input had no detectable transient. */
+    warning?: string;
+}
+/**
+ * Detect the first transient (end of leading silence) in a media file.
+ *
+ * Runs `silencedetect` with a strict noise floor and a long min-silence so the
+ * lead-in counts as silence; the first `silence_end` is the first audible event.
+ */
+export declare function detectFirstTransient(inputPath: string, opts?: {
+    thresholdDb?: number;
+    minSilenceSec?: number;
+    signal?: AbortSignal;
+}): Promise<TransientResult>;
+/**
+ * Align 2+ inputs by their first transient. Pick the input with the smallest
+ * transient as reference (transient at t=0 in the synced timeline). Other
+ * offsets = transient[i] - reference.transient.
+ */
+export declare function multicamSync(inputPaths: string[], opts?: {
+    thresholdDb?: number;
+    minSilenceSec?: number;
+    signal?: AbortSignal;
+}): Promise<MulticamSyncResult>;
+//# sourceMappingURL=multicam.d.ts.map

package/dist/core/multicam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multicam.d.ts","sourceRoot":"","sources":["../../src/core/multicam.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,iFAAiF;QACjF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,CAAC,CAAC;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAChF,OAAO,CAAC,eAAe,CAAC,CAyB1B;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAChF,OAAO,CAAC,kBAAkB,CAAC,CA2C7B"}

package/dist/core/multicam.js

@@ -0,0 +1,77 @@
+/**
+ * Multicam clap-sync — first-transient alignment via ffmpeg silencedetect.
+ *
+ * v1 limitation: works only when each take starts with a clap, slate, or sharp
+ * sound louder than the surrounding lead-in silence. For dialogue-only takes
+ * with no slate, this tool can't align — that needs cross-correlation, deferred
+ * to a future v2 (would require an FFT lib or numpy).
+ */
+import { runFfmpeg } from "./media/ffmpeg.js";
+import { parseSilenceDetect } from "./silence.js";
+/**
+ * Detect the first transient (end of leading silence) in a media file.
+ *
+ * Runs `silencedetect` with a strict noise floor and a long min-silence so the
+ * lead-in counts as silence; the first `silence_end` is the first audible event.
+ */
+export async function detectFirstTransient(inputPath, opts = {}) {
+    const thresholdDb = opts.thresholdDb ?? -40;
+    const minSilenceSec = opts.minSilenceSec ?? 0.5;
+    const r = await runFfmpeg([
+        "-i",
+        inputPath,
+        "-af",
+        `silencedetect=noise=${thresholdDb}dB:d=${minSilenceSec}`,
+        "-f",
+        "null",
+        "-",
+    ], { signal: opts.signal });
+    if (r.code !== 0) {
+        return { path: inputPath, transientSec: null };
+    }
+    const ranges = parseSilenceDetect(r.stderr);
+    // The first range's endSec is the first transient (end of lead-in silence).
+    const first = ranges[0];
+    return {
+        path: inputPath,
+        transientSec: first ? first.endSec : null,
+    };
+}
+/**
+ * Align 2+ inputs by their first transient. Pick the input with the smallest
+ * transient as reference (transient at t=0 in the synced timeline). Other
+ * offsets = transient[i] - reference.transient.
+ */
+export async function multicamSync(inputPaths, opts = {}) {
+    if (inputPaths.length === 0) {
+        throw new Error("multicamSync: inputs is empty");
+    }
+    const thresholdDb = opts.thresholdDb ?? -40;
+    const transients = await Promise.all(inputPaths.map((p) => detectFirstTransient(p, {
+        thresholdDb,
+        minSilenceSec: opts.minSilenceSec,
+        signal: opts.signal,
+    })));
+    // Pick reference: smallest finite transient. If all null, fall back to first.
+    const withTransient = transients.filter((t) => t.transientSec !== null);
+    const reference = withTransient.length > 0
+        ? withTransient.reduce((acc, t) => t.transientSec < acc.transientSec ? t : acc)
+        : transients[0];
+    const refSec = reference.transientSec ?? 0;
+    const results = transients.map((t) => ({
+        path: t.path,
+        transientSec: t.transientSec,
+        offsetSec: t.transientSec === null ? null : +(t.transientSec - refSec).toFixed(6),
+    }));
+    const missing = results.filter((r) => r.offsetSec === null);
+    const warning = missing.length > 0
+        ? `no transient detected for ${missing.length} of ${results.length} input(s); manual alignment needed`
+        : undefined;
+    return {
+        reference: reference.path,
+        results,
+        thresholdDb,
+        warning,
+    };
+}
+//# sourceMappingURL=multicam.js.map

package/dist/core/multicam.js.map

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

package/dist/core/multicam.test.d.ts

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

package/dist/core/multicam.test.d.ts.map

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

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/reformat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Aspect-ratio reformat presets for short-form / vertical / square exports.
+ *
+ * Used by the `reformat_timeline` tool to derive the FCPXML format spec
+ * (width × height) for a new timeline. The tool then emits an FCPXML that
+ * imports as a fresh timeline at the target aspect; the user's NLE handles
+ * the actual reframing (Resolve Smart Reframe, Premiere Auto Reframe).
+ *
+ * The chosen base resolutions are the platform-canonical defaults:
+ *   - 9:16  → 1080×1920 (TikTok / Reels / Shorts)
+ *   - 1:1   → 1080×1080 (Instagram feed)
+ *   - 4:5   → 1080×1350 (Instagram portrait feed)
+ *   - 16:9  → 1920×1080 (long-form horizontal)
+ *   - 4:3   → 1440×1080 (legacy / old-school cuts)
+ */
+export type ReformatPreset = "9:16" | "1:1" | "4:5" | "16:9" | "4:3";
+export interface ReformatSpec {
+    preset: ReformatPreset;
+    width: number;
+    height: number;
+    /** Suggested label for use in clip / sequence names. */
+    label: string;
+}
+export declare function reformatSpec(preset: ReformatPreset): ReformatSpec;
+export declare const REFORMAT_PRESETS: ReformatPreset[];
+//# sourceMappingURL=reformat.d.ts.map

package/dist/core/reformat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reformat.d.ts","sourceRoot":"","sources":["../../src/core/reformat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAErE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf;AAUD,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAQjE;AAED,eAAO,MAAM,gBAAgB,EAA2B,cAAc,EAAE,CAAC"}

package/dist/core/reformat.js

@@ -0,0 +1,31 @@
+/**
+ * Aspect-ratio reformat presets for short-form / vertical / square exports.
+ *
+ * Used by the `reformat_timeline` tool to derive the FCPXML format spec
+ * (width × height) for a new timeline. The tool then emits an FCPXML that
+ * imports as a fresh timeline at the target aspect; the user's NLE handles
+ * the actual reframing (Resolve Smart Reframe, Premiere Auto Reframe).
+ *
+ * The chosen base resolutions are the platform-canonical defaults:
+ *   - 9:16  → 1080×1920 (TikTok / Reels / Shorts)
+ *   - 1:1   → 1080×1080 (Instagram feed)
+ *   - 4:5   → 1080×1350 (Instagram portrait feed)
+ *   - 16:9  → 1920×1080 (long-form horizontal)
+ *   - 4:3   → 1440×1080 (legacy / old-school cuts)
+ */
+const PRESETS = {
+    "9:16": { preset: "9:16", width: 1080, height: 1920, label: "Vertical 9:16" },
+    "1:1": { preset: "1:1", width: 1080, height: 1080, label: "Square 1:1" },
+    "4:5": { preset: "4:5", width: 1080, height: 1350, label: "Portrait 4:5" },
+    "16:9": { preset: "16:9", width: 1920, height: 1080, label: "Horizontal 16:9" },
+    "4:3": { preset: "4:3", width: 1440, height: 1080, label: "Classic 4:3" },
+};
+export function reformatSpec(preset) {
+    const spec = PRESETS[preset];
+    if (!spec) {
+        throw new Error(`unknown reformat preset: ${preset}; valid: ${Object.keys(PRESETS).join(", ")}`);
+    }
+    return spec;
+}
+export const REFORMAT_PRESETS = Object.keys(PRESETS);
+//# sourceMappingURL=reformat.js.map

package/dist/core/reformat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reformat.js","sourceRoot":"","sources":["../../src/core/reformat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,MAAM,OAAO,GAAyC;IACpD,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE;IAC7E,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,EAAE;IACxE,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE;IAC1E,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,EAAE;IAC/E,KAAK,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE;CAC1E,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,MAAsB;IACjD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACb,4BAA4B,MAAM,YAAY,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAChF,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAqB,CAAC"}

package/dist/core/reformat.test.d.ts

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

package/dist/core/reformat.test.d.ts.map

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