@prestyj/editor 0.7.1

package/dist/tools/face-reframe.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const FaceReframeParams: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+    aspect: z.ZodEnum<{
+        "9:16": "9:16";
+        "1:1": "1:1";
+        "4:5": "4:5";
+        "16:9": "16:9";
+    }>;
+    strategy: z.ZodOptional<z.ZodEnum<{
+        face: "face";
+        motion: "motion";
+        static: "static";
+    }>>;
+    sampleFps: z.ZodOptional<z.ZodNumber>;
+    smoothingWindowSec: z.ZodOptional<z.ZodNumber>;
+    videoCodec: z.ZodOptional<z.ZodString>;
+    crf: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * face_reframe — file-only face-tracked vertical reframe. Pairs with
+ * reformat_timeline (NLE-side timeline reflow) for the full short-form
+ * pipeline: NLE picks the timeline geometry, this tool bakes a follow-the-
+ * subject crop into a delivery-ready mp4.
+ */
+export declare function createFaceReframeTool(cwd: string): AgentTool<typeof FaceReframeParams>;
+export {};
+//# sourceMappingURL=face-reframe.d.ts.map

package/dist/tools/face-reframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-reframe.d.ts","sourceRoot":"","sources":["../../src/tools/face-reframe.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAOhD,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;iBA0CrB,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,iBAAiB,CAAC,CAqGtF"}

package/dist/tools/face-reframe.js

@@ -0,0 +1,143 @@
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { analyzeReframe, buildReframeFilter } from "../core/face-reframe.js";
+import { compact, err } from "../core/format.js";
+import { checkFfmpeg, runFfmpeg } from "../core/media/ffmpeg.js";
+import { findPython } from "../core/python.js";
+import { safeOutputPath } from "../core/safe-paths.js";
+const FaceReframeParams = z.object({
+    input: z.string().describe("Source video (relative resolves to cwd)."),
+    output: z
+        .string()
+        .describe("Output mp4 (relative resolves to cwd; sandbox-safe paths only). Re-encoded video; " +
+        "audio is copied through."),
+    aspect: z
+        .enum(["9:16", "1:1", "4:5", "16:9"])
+        .describe("Target aspect ratio. 9:16 for Reels/Shorts/TikTok; 1:1 for Instagram feed; 4:5 for " +
+        "vertical-feed; 16:9 for letterboxing odd footage to delivery. Aspect math is " +
+        "computed against source dimensions."),
+    strategy: z
+        .enum(["face", "motion", "static"])
+        .optional()
+        .describe("Tracking strategy. 'face' (default) follows the largest face per shot via MediaPipe; " +
+        "'static' centre-crops the whole video without analysis (cheap fallback). 'motion' " +
+        "is reserved — currently treated as 'face'."),
+    sampleFps: z
+        .number()
+        .positive()
+        .max(30)
+        .optional()
+        .describe("Frames-per-second to face-detect at. Default 5. Higher = smoother tracking + slower; " +
+        "lower = faster + jumpier. 5 is the sweet spot for talking-head shorts."),
+    smoothingWindowSec: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Smoothing window for the per-shot centre. Default 0.5s. The sidecar uses the median " +
+        "over each shot which already rejects spikes; this knob is informational right now."),
+    videoCodec: z.string().optional().describe("Default libx264."),
+    crf: z.number().int().min(0).max(51).optional().describe("Default 20."),
+});
+/**
+ * face_reframe — file-only face-tracked vertical reframe. Pairs with
+ * reformat_timeline (NLE-side timeline reflow) for the full short-form
+ * pipeline: NLE picks the timeline geometry, this tool bakes a follow-the-
+ * subject crop into a delivery-ready mp4.
+ */
+export function createFaceReframeTool(cwd) {
+    return {
+        name: "face_reframe",
+        description: "File-only face-tracked vertical reframe. Detects shots (PySceneDetect), tracks the " +
+            "largest face per shot (MediaPipe), low-pass smooths the centre, emits an ffmpeg " +
+            "crop filter that follows the subject. Falls back to centre crop when no face " +
+            "detected. Pair with reformat_timeline for the full short-form pipeline. REQUIRES " +
+            "python3 + `pip install opencv-python mediapipe scenedetect numpy` and ffmpeg on " +
+            "PATH. Output is a finished mp4 ready for burn_subtitles / normalize_loudness.",
+        parameters: FaceReframeParams,
+        async execute(args, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            if (!findPython()) {
+                return err("Python 3 not on PATH", "install python3 and: pip install opencv-python mediapipe scenedetect numpy");
+            }
+            try {
+                const inAbs = resolvePath(cwd, args.input);
+                const outAbs = safeOutputPath(cwd, args.output);
+                if (inAbs === outAbs) {
+                    return err("output and input are identical", "use a different output path");
+                }
+                let plan;
+                try {
+                    plan = await analyzeReframe(inAbs, {
+                        signal: ctx.signal,
+                        sampleFps: args.sampleFps,
+                        minDetectionConfidence: 0.5,
+                        smoothingWindowSec: args.smoothingWindowSec,
+                    });
+                }
+                catch (e) {
+                    const msg = e.message;
+                    if (/missing python dep/i.test(msg)) {
+                        return err(msg, "pip install opencv-python mediapipe scenedetect numpy");
+                    }
+                    return err(msg);
+                }
+                if (!plan.shots || plan.shots.length === 0) {
+                    return err("no shots detected and no fallback produced", "verify the input is a readable video file");
+                }
+                if (!plan.sourceWidth || !plan.sourceHeight) {
+                    return err("sidecar returned no source dimensions", "input may not be a video file");
+                }
+                // 'static' strategy bypasses tracking — pin every shot's centre to (0.5, 0.5).
+                const aspect = args.aspect;
+                const strategy = args.strategy ?? "face";
+                const planForFilter = strategy === "static"
+                    ? {
+                        ...plan,
+                        shots: plan.shots.map((s) => ({
+                            ...s,
+                            smoothedX: 0.5,
+                            smoothedY: 0.5,
+                            mode: "static",
+                        })),
+                    }
+                    : plan;
+                const { filter, outWidth, outHeight } = buildReframeFilter(planForFilter, aspect);
+                const codec = args.videoCodec ?? "libx264";
+                const crf = String(args.crf ?? 20);
+                const r = await runFfmpeg(["-i", inAbs, "-vf", filter, "-c:v", codec, "-crf", crf, "-c:a", "copy", outAbs], { signal: ctx.signal });
+                if (r.code !== 0) {
+                    return err(`ffmpeg failed: ${tail(r.stderr)}`);
+                }
+                const faceShots = planForFilter.shots.filter((s) => s.mode === "face").length;
+                const fallbackShots = planForFilter.shots.filter((s) => s.mode === "static").length;
+                return compact({
+                    ok: true,
+                    path: outAbs,
+                    aspect,
+                    outWidth,
+                    outHeight,
+                    shots: planForFilter.shots.length,
+                    faceShots,
+                    fallbackShots,
+                    totalSec: round(plan.totalSec, 3),
+                    sourceWidth: plan.sourceWidth,
+                    sourceHeight: plan.sourceHeight,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+function tail(s) {
+    return s.split("\n").filter(Boolean).slice(-3).join(" | ").slice(-300);
+}
+function round(n, places) {
+    if (!Number.isFinite(n))
+        return n;
+    const m = 10 ** places;
+    return Math.round(n * m) / m;
+}
+//# sourceMappingURL=face-reframe.js.map

package/dist/tools/face-reframe.js.map

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

package/dist/tools/face-reframe.test.d.ts

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

package/dist/tools/face-reframe.test.d.ts.map

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

package/dist/tools/face-reframe.test.js

@@ -0,0 +1,139 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import * as faceCore from "../core/face-reframe.js";
+import * as ffmpegMod from "../core/media/ffmpeg.js";
+import * as pythonMod from "../core/python.js";
+import { createFaceReframeTool } from "./face-reframe.js";
+const ctx = {
+    signal: new AbortController().signal,
+    toolCallId: "t1",
+};
+const samplePlan = {
+    shots: [
+        {
+            startSec: 0,
+            endSec: 2,
+            frames: [],
+            smoothedX: 0.4,
+            smoothedY: 0.5,
+            mode: "face",
+        },
+        {
+            startSec: 2,
+            endSec: 5,
+            frames: [],
+            smoothedX: 0.6,
+            smoothedY: 0.5,
+            mode: "static",
+        },
+    ],
+    totalSec: 5,
+    fps: 30,
+    sourceWidth: 1920,
+    sourceHeight: 1080,
+};
+describe("face_reframe tool", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns ffmpeg-missing error when ffmpeg is absent", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(false);
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "in.mp4", output: "out.mp4", aspect: "9:16" }, ctx);
+        expect(r).toMatch(/^error: ffmpeg not on PATH/);
+    });
+    it("returns python-missing error when findPython fails", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(true);
+        vi.spyOn(pythonMod, "findPython").mockReturnValue(undefined);
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "in.mp4", output: "out.mp4", aspect: "9:16" }, ctx);
+        expect(r).toMatch(/^error:/);
+        expect(r).toMatch(/Python 3 not on PATH/);
+        expect(r).toMatch(/mediapipe/);
+    });
+    it("composes ffmpeg args from the analysis plan", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(true);
+        vi.spyOn(pythonMod, "findPython").mockReturnValue({ cmd: "python3", args: [] });
+        vi.spyOn(faceCore, "analyzeReframe").mockResolvedValue(samplePlan);
+        const ffSpy = vi
+            .spyOn(ffmpegMod, "runFfmpeg")
+            .mockResolvedValue({ code: 0, stdout: "", stderr: "" });
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "in.mp4", output: "out.mp4", aspect: "9:16" }, ctx);
+        expect(typeof r).toBe("string");
+        const parsed = JSON.parse(r);
+        expect(parsed.ok).toBe(true);
+        expect(parsed.aspect).toBe("9:16");
+        expect(parsed.shots).toBe(2);
+        expect(parsed.faceShots).toBe(1);
+        expect(parsed.fallbackShots).toBe(1);
+        expect(parsed.outWidth).toBe(606);
+        expect(parsed.outHeight).toBe(1080);
+        // Inspect ffmpeg invocation.
+        expect(ffSpy).toHaveBeenCalledTimes(1);
+        const ffArgs = ffSpy.mock.calls[0][0];
+        expect(ffArgs).toContain("-i");
+        expect(ffArgs).toContain("/tmp/in.mp4");
+        expect(ffArgs).toContain("-vf");
+        const vfIdx = ffArgs.indexOf("-vf");
+        const vf = ffArgs[vfIdx + 1];
+        expect(vf).toMatch(/^crop=606:1080:x='/);
+        expect(vf).toContain("between(t\\,0\\,2)");
+        expect(vf).toContain("between(t\\,2\\,5)");
+        expect(ffArgs).toContain("-c:a");
+        expect(ffArgs).toContain("copy");
+        expect(ffArgs).toContain("-c:v");
+        expect(ffArgs).toContain("libx264"); // default codec
+        expect(ffArgs).toContain("-crf");
+        expect(ffArgs).toContain("20"); // default crf
+    });
+    it("static strategy ignores per-shot smoothedX and centres every crop", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(true);
+        vi.spyOn(pythonMod, "findPython").mockReturnValue({ cmd: "python3", args: [] });
+        vi.spyOn(faceCore, "analyzeReframe").mockResolvedValue(samplePlan);
+        const ffSpy = vi
+            .spyOn(ffmpegMod, "runFfmpeg")
+            .mockResolvedValue({ code: 0, stdout: "", stderr: "" });
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "in.mp4", output: "out.mp4", aspect: "9:16", strategy: "static" }, ctx);
+        const parsed = JSON.parse(r);
+        expect(parsed.faceShots).toBe(0);
+        expect(parsed.fallbackShots).toBe(2);
+        const vf = ffSpy.mock.calls[0][0][ffSpy.mock.calls[0][0].indexOf("-vf") + 1];
+        // Both shots collapse to the centre X (657 for 1920×1080 → 9:16 crop 606).
+        expect(vf).toContain("\\,657\\,");
+        // No off-centre 4-digit X values from the original plan (e.g. 1314).
+        expect(vf).not.toMatch(/\\,1\d{3}\\,/);
+    });
+    it("propagates ffmpeg failure as err()", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(true);
+        vi.spyOn(pythonMod, "findPython").mockReturnValue({ cmd: "python3", args: [] });
+        vi.spyOn(faceCore, "analyzeReframe").mockResolvedValue(samplePlan);
+        vi.spyOn(ffmpegMod, "runFfmpeg").mockResolvedValue({
+            code: 1,
+            stdout: "",
+            stderr: "Could not open codec\nframe= 0 fps=0\nMaybe try -c:v libx264",
+        });
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "in.mp4", output: "out.mp4", aspect: "9:16" }, ctx);
+        expect(r).toMatch(/^error: ffmpeg failed/);
+        expect(r).toMatch(/Could not open codec|libx264/);
+    });
+    it("propagates a missing-dep sidecar error with the pip-install fix", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(true);
+        vi.spyOn(pythonMod, "findPython").mockReturnValue({ cmd: "python3", args: [] });
+        vi.spyOn(faceCore, "analyzeReframe").mockRejectedValue(new Error("missing python dep: mediapipe; install: pip install opencv-python mediapipe scenedetect numpy"));
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "in.mp4", output: "out.mp4", aspect: "9:16" }, ctx);
+        expect(r).toMatch(/^error:/);
+        expect(r).toMatch(/mediapipe/);
+        expect(r).toMatch(/pip install opencv-python mediapipe scenedetect numpy/);
+    });
+    it("rejects identical input and output paths", async () => {
+        vi.spyOn(ffmpegMod, "checkFfmpeg").mockReturnValue(true);
+        vi.spyOn(pythonMod, "findPython").mockReturnValue({ cmd: "python3", args: [] });
+        const tool = createFaceReframeTool("/tmp");
+        const r = await tool.execute({ input: "x.mp4", output: "x.mp4", aspect: "9:16" }, ctx);
+        expect(r).toMatch(/output and input are identical/);
+    });
+});
+//# sourceMappingURL=face-reframe.test.js.map

package/dist/tools/face-reframe.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-reframe.test.js","sourceRoot":"","sources":["../../src/tools/face-reframe.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC9D,OAAO,KAAK,QAAQ,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,SAAS,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,GAAG,GAAG;IACV,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;IACpC,UAAU,EAAE,IAAI;CACgE,CAAC;AAEnF,MAAM,UAAU,GAAyB;IACvC,KAAK,EAAE;QACL;YACE,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,EAAE;YACV,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,IAAI,EAAE,MAAM;SACb;QACD;YACE,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,CAAC;YACT,MAAM,EAAE,EAAE;YACV,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,IAAI,EAAE,QAAQ;SACf;KACF;IACD,QAAQ,EAAE,CAAC;IACX,GAAG,EAAE,EAAE;IACP,WAAW,EAAE,IAAI;IACjB,YAAY,EAAE,IAAI;CACnB,CAAC;AAEF,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC1D,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EACtD,GAAyC,CAC1C,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;QAClE,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACzD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EACtD,GAAyC,CAC1C,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;QAC1C,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACzD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAChF,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,EAAE;aACb,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC;aAC7B,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAE1D,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EACtD,GAAyC,CAC1C,CAAC;QACF,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAW,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEpC,6BAA6B;QAC7B,MAAM,CAAC,KAAK,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACzC,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QAC3C,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB;QACrD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mEAAmE,EAAE,KAAK,IAAI,EAAE;QACjF,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACzD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAChF,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACnE,MAAM,KAAK,GAAG,EAAE;aACb,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC;aAC7B,iBAAiB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAE1D,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAC1E,GAAyC,CAC1C,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAW,CAAC,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7E,2EAA2E;QAC3E,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAClC,qEAAqE;QACrE,MAAM,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;QAClD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACzD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAChF,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACnE,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,iBAAiB,CAAC;YACjD,IAAI,EAAE,CAAC;YACP,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,8DAA8D;SACvE,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EACtD,GAAyC,CAC1C,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;QAC3C,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,8BAA8B,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iEAAiE,EAAE,KAAK,IAAI,EAAE;QAC/E,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACzD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAChF,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC,iBAAiB,CACpD,IAAI,KAAK,CACP,+FAA+F,CAChG,CACF,CAAC;QACF,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,EACtD,GAAyC,CAC1C,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,uDAAuD,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACzD,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QAChF,MAAM,IAAI,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAC1B,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EACnD,GAAyC,CAC1C,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,gCAAgC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/tools/find-viral-moments.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const FindViralMomentsParams: z.ZodObject<{
+    transcript: z.ZodString;
+    maxClips: z.ZodOptional<z.ZodNumber>;
+    durationRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    scoreThreshold: z.ZodOptional<z.ZodNumber>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * find_viral_moments — long-form transcript → top-N standalone-Shorts
+ * candidates. The Opus ClipAnything / Submagic Magic Clips equivalent.
+ *
+ * Algorithm:
+ *   1. Slide windows of `maxSec*2` (default 120s) with 30s overlap.
+ *   2. ONE LLM call per window proposing up to 3 candidates.
+ *   3. Score each via `score_clip` (transcript-only, cheap path).
+ *   4. Dedup overlaps (>50% → keep higher score).
+ *   5. Sort desc, take top maxClips.
+ */
+export declare function createFindViralMomentsTool(cwd: string): AgentTool<typeof FindViralMomentsParams>;
+export {};
+//# sourceMappingURL=find-viral-moments.d.ts.map

package/dist/tools/find-viral-moments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-viral-moments.d.ts","sourceRoot":"","sources":["../../src/tools/find-viral-moments.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAchD,QAAA,MAAM,sBAAsB;;;;;;iBAwB1B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,sBAAsB,CAAC,CA+HhG"}

package/dist/tools/find-viral-moments.js

@@ -0,0 +1,176 @@
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { scoreClipInternal } from "../core/clip-scoring.js";
+import { compact, err } from "../core/format.js";
+import { buildSlidingWindows, dedupCandidates, normalizeCandidates, proposeCandidates, } from "../core/viral-moments.js";
+import { parseTranscript } from "../core/whisper.js";
+const FindViralMomentsParams = z.object({
+    transcript: z.string().describe("Path to a transcript JSON written by `transcribe`."),
+    maxClips: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .optional()
+        .describe("Top-N to return after dedup. Default 5."),
+    durationRange: z
+        .tuple([z.number().min(1), z.number().min(1)])
+        .optional()
+        .describe("[minSec, maxSec] for accepted clips. Default [20, 45] — Jenny Hoyos's 30–34s sweet " +
+        "spot for Shorts retention (per youtube-algorithm-primer skill, Marketing Examined " +
+        "May 2024). Widen to [20, 60] when the user explicitly wants longer cuts."),
+    scoreThreshold: z
+        .number()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe("Minimum 0-100 score to keep. Default 50 — anything lower won't perform."),
+    model: z.string().optional().describe("OpenAI model. Default gpt-4o-mini."),
+});
+/**
+ * find_viral_moments — long-form transcript → top-N standalone-Shorts
+ * candidates. The Opus ClipAnything / Submagic Magic Clips equivalent.
+ *
+ * Algorithm:
+ *   1. Slide windows of `maxSec*2` (default 120s) with 30s overlap.
+ *   2. ONE LLM call per window proposing up to 3 candidates.
+ *   3. Score each via `score_clip` (transcript-only, cheap path).
+ *   4. Dedup overlaps (>50% → keep higher score).
+ *   5. Sort desc, take top maxClips.
+ */
+export function createFindViralMomentsTool(cwd) {
+    return {
+        name: "find_viral_moments",
+        description: "Find the top N viral-clip candidates inside a long-form transcript. Slides windows " +
+            "over the transcript, proposes 3 candidates per window via LLM, scores each via " +
+            "`score_clip`, dedups overlaps, returns ranked list with suggested title + caption + " +
+            "hook line. The 'long video to Shorts' orchestrator — Opus ClipAnything / Submagic " +
+            "Magic Clips equivalent. Default duration window [20, 45]s targets Jenny Hoyos's " +
+            "30–34s sweet spot. Output feeds `cut_at` + `render_multi_format` directly.",
+        parameters: FindViralMomentsParams,
+        async execute(args, ctx) {
+            try {
+                if (!process.env.OPENAI_API_KEY) {
+                    return err("OPENAI_API_KEY not set", "export OPENAI_API_KEY=...");
+                }
+                const transcriptAbs = resolvePath(cwd, args.transcript);
+                let raw;
+                try {
+                    raw = readFileSync(transcriptAbs, "utf8");
+                }
+                catch (e) {
+                    return err(`cannot read transcript ${transcriptAbs}: ${e.message}`, "verify the transcript JSON exists");
+                }
+                let t;
+                try {
+                    t = parseTranscript(raw);
+                }
+                catch (e) {
+                    return err(e.message);
+                }
+                if (t.segments.length === 0) {
+                    return err("transcript has no segments", "rerun transcribe(...)");
+                }
+                const [minSec, maxSec] = args.durationRange ?? [20, 45];
+                if (maxSec <= minSec)
+                    return err("durationRange[1] must be > durationRange[0]");
+                const maxClips = args.maxClips ?? 5;
+                const threshold = args.scoreThreshold ?? 50;
+                // Build windows: maxSec*2 wide with 30s overlap (or 25% of width
+                // for very small maxSec to avoid degenerate cases).
+                const windowSec = maxSec * 2;
+                const overlapSec = Math.min(30, Math.max(1, windowSec * 0.25));
+                const windows = buildSlidingWindows(t, windowSec, overlapSec);
+                if (windows.length === 0) {
+                    return err("no windows produced", "verify transcript.durationSec > 0");
+                }
+                // Propose candidates per window. One LLM call per window.
+                const proposals = [];
+                for (const w of windows) {
+                    if (ctx.signal?.aborted)
+                        return err("aborted");
+                    try {
+                        const cands = await proposeCandidates(w, {
+                            model: args.model,
+                            durationRange: [minSec, maxSec],
+                            signal: ctx.signal,
+                        });
+                        proposals.push(...cands);
+                    }
+                    catch (e) {
+                        // One bad window shouldn't kill the whole pass — log via
+                        // returning a partial. We surface count of dropped windows
+                        // implicitly through `totalScored`.
+                        void e.message;
+                    }
+                }
+                const normalized = normalizeCandidates(proposals, t.durationSec, minSec, maxSec);
+                if (normalized.length === 0) {
+                    return compact({ candidates: [], totalScored: 0, dropped: 0 });
+                }
+                // Score every candidate via the same engine as score_clip.
+                const scored = [];
+                for (const c of normalized) {
+                    if (ctx.signal?.aborted)
+                        return err("aborted");
+                    try {
+                        const text = sliceText(t, c.startSec, c.endSec);
+                        if (!text)
+                            continue;
+                        const s = await scoreClipInternal(text, c.startSec, c.endSec, [], {
+                            model: args.model,
+                            signal: ctx.signal,
+                        });
+                        scored.push({
+                            ...c,
+                            score: s.score,
+                            hook: s.hook,
+                            flow: s.flow,
+                            engagement: s.engagement,
+                            trend: s.trend,
+                            durationSec: s.durationSec,
+                        });
+                    }
+                    catch (e) {
+                        void e.message;
+                    }
+                }
+                const aboveThreshold = scored.filter((s) => s.score >= threshold);
+                const deduped = dedupCandidates(aboveThreshold);
+                const top = deduped.slice(0, maxClips);
+                return compact({
+                    candidates: top.map((c) => ({
+                        startSec: +c.startSec.toFixed(2),
+                        endSec: +c.endSec.toFixed(2),
+                        durationSec: +c.durationSec.toFixed(2),
+                        score: c.score,
+                        hook: +c.hook.toFixed(2),
+                        flow: +c.flow.toFixed(2),
+                        engagement: +c.engagement.toFixed(2),
+                        trend: +c.trend.toFixed(2),
+                        suggestedTitle: c.suggestedTitle,
+                        suggestedCaption: c.suggestedCaption,
+                        hookLine: c.hookLine,
+                        why: c.why,
+                    })),
+                    totalScored: scored.length,
+                    dropped: scored.length - top.length,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+function sliceText(t, startSec, endSec) {
+    const parts = [];
+    for (const seg of t.segments) {
+        if (seg.end <= startSec || seg.start >= endSec)
+            continue;
+        parts.push(seg.text.trim());
+    }
+    return parts.join(" ").trim();
+}
+//# sourceMappingURL=find-viral-moments.js.map

package/dist/tools/find-viral-moments.js.map

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

package/dist/tools/find-viral-moments.test.d.ts

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

package/dist/tools/find-viral-moments.test.d.ts.map

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