@prestyj/editor 0.7.1

package/dist/tools/score-clip.test.js

@@ -0,0 +1,110 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createScoreClipTool, sliceTranscriptText } from "./score-clip.js";
+const ctx = {
+    signal: new AbortController().signal,
+    toolCallId: "t1",
+};
+function writeTranscript(dir, payload) {
+    const p = join(dir, "t.json");
+    writeFileSync(p, JSON.stringify(payload), "utf8");
+    return p;
+}
+describe("score_clip tool", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        delete process.env.OPENAI_API_KEY;
+    });
+    it("has a non-empty description naming the next-call hooks", () => {
+        const tool = createScoreClipTool("/tmp");
+        expect(tool.description.length).toBeGreaterThan(80);
+        expect(tool.description).toMatch(/find_viral_moments|virality/i);
+    });
+    it("errors when OPENAI_API_KEY is missing", async () => {
+        delete process.env.OPENAI_API_KEY;
+        const tool = createScoreClipTool("/tmp");
+        const r = await tool.execute({ transcript: "no.json", startSec: 0, endSec: 10 }, ctx);
+        expect(r).toMatch(/^error:.*OPENAI_API_KEY/);
+    });
+    it("errors when endSec <= startSec", async () => {
+        process.env.OPENAI_API_KEY = "k";
+        const tool = createScoreClipTool("/tmp");
+        const r = await tool.execute({ transcript: "no.json", startSec: 5, endSec: 5 }, ctx);
+        expect(r).toMatch(/^error:.*startSec/);
+    });
+    it("errors when transcript file is missing", async () => {
+        process.env.OPENAI_API_KEY = "k";
+        const tool = createScoreClipTool("/tmp");
+        const r = await tool.execute({ transcript: "no/such/file.json", startSec: 0, endSec: 10 }, ctx);
+        expect(r).toMatch(/^error:.*cannot read/);
+    });
+    it("errors on transcript with no segments", async () => {
+        process.env.OPENAI_API_KEY = "k";
+        const dir = mkdtempSync(join(tmpdir(), "gg-sc-"));
+        writeTranscript(dir, { language: "en", durationSec: 10, segments: [] });
+        const tool = createScoreClipTool(dir);
+        const r = await tool.execute({ transcript: "t.json", startSec: 0, endSec: 5 }, ctx);
+        expect(r).toMatch(/^error:.*no segments/);
+    });
+    it("returns a JSON-shaped success when LLM responds correctly", async () => {
+        process.env.OPENAI_API_KEY = "k";
+        const dir = mkdtempSync(join(tmpdir(), "gg-sc-"));
+        writeTranscript(dir, {
+            language: "en",
+            durationSec: 60,
+            segments: [
+                { start: 0, end: 30, text: "this is a strong hook line about money" },
+                { start: 30, end: 60, text: "and the payoff lands cleanly" },
+            ],
+        });
+        vi.stubGlobal("fetch", vi.fn(async () => ({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                choices: [
+                    {
+                        message: {
+                            content: JSON.stringify({
+                                hook: 0.9,
+                                flow: 0.7,
+                                engagement: 0.8,
+                                trend: 0.6,
+                                why: "tight",
+                            }),
+                        },
+                    },
+                ],
+            }),
+            text: async () => "",
+        })));
+        const tool = createScoreClipTool(dir);
+        const r = await tool.execute({ transcript: "t.json", startSec: 0, endSec: 60 }, ctx);
+        const parsed = JSON.parse(r);
+        expect(parsed.score).toBeGreaterThan(0);
+        expect(parsed.score).toBeLessThanOrEqual(100);
+        expect(parsed.hook).toBe(0.9);
+        expect(parsed.durationSec).toBe(60);
+        expect(parsed.why).toBeDefined();
+    });
+});
+describe("sliceTranscriptText", () => {
+    it("includes overlapping segments and trims", () => {
+        const text = sliceTranscriptText({
+            language: "en",
+            durationSec: 30,
+            segments: [
+                { start: 0, end: 10, text: "  alpha " },
+                { start: 10, end: 20, text: " beta" },
+                { start: 20, end: 30, text: "gamma" },
+            ],
+        }, 5, 18);
+        // overlaps [0,10] and [10,20]; not [20,30]
+        expect(text).toBe("alpha beta");
+    });
+    it("returns empty when nothing overlaps", () => {
+        expect(sliceTranscriptText({ language: "en", durationSec: 10, segments: [{ start: 0, end: 5, text: "x" }] }, 6, 10)).toBe("");
+    });
+});
+//# sourceMappingURL=score-clip.test.js.map

package/dist/tools/score-clip.test.js.map

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

package/dist/tools/score-shot.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const ScoreShotParams: z.ZodObject<{
+    input: z.ZodString;
+    times: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    intervalSec: z.ZodOptional<z.ZodNumber>;
+    startSec: z.ZodOptional<z.ZodNumber>;
+    endSec: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        high: "high";
+    }>>;
+    model: z.ZodOptional<z.ZodString>;
+    maxFrames: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createScoreShotTool(cwd: string): AgentTool<typeof ScoreShotParams>;
+export {};
+//# sourceMappingURL=score-shot.d.ts.map

package/dist/tools/score-shot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-shot.d.ts","sourceRoot":"","sources":["../../src/tools/score-shot.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,QAAA,MAAM,eAAe;;;;;;;;;;;;iBA4BnB,CAAC;AAEH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,eAAe,CAAC,CA0FlF"}

package/dist/tools/score-shot.js

@@ -0,0 +1,127 @@
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err, summarizeList } from "../core/format.js";
+import { extractAtInterval, extractAtTimes } from "../core/frames.js";
+import { checkFfmpeg, probeMedia } from "../core/media/ffmpeg.js";
+import { scoreFrames } from "../core/vision.js";
+const ScoreShotParams = z.object({
+    input: z.string().describe("Video file path (relative resolves to cwd)."),
+    /**
+     * Either provide explicit timestamps (precise, one ffmpeg call per frame)
+     * or an interval (fast, single ffmpeg pass). One is required.
+     */
+    times: z
+        .array(z.number().min(0))
+        .optional()
+        .describe("Specific seconds to sample. Use for targeted inspection."),
+    intervalSec: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Sample every N seconds. Use for whole-video coverage."),
+    startSec: z.number().min(0).optional(),
+    endSec: z.number().min(0).optional(),
+    detail: z
+        .enum(["low", "high"])
+        .optional()
+        .describe("Vision detail. low ≈ 85 tok/img (cheap), high ≈ 700 tok/img (more accurate)."),
+    model: z.string().optional().describe("OpenAI model id (default gpt-4o-mini)."),
+    maxFrames: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Hard cap on frames sent (default 30). Agent should respect cost."),
+});
+export function createScoreShotTool(cwd) {
+    return {
+        name: "score_shot",
+        description: "AI vision: rate frames 0-10 on composition, focus, subject clarity, energy. " +
+            "Use to find best/worst shots, identify blurry takes, or pick hero frames. " +
+            "Either pass `times` for targeted inspection OR `intervalSec` for whole-video coverage. " +
+            "Default returns top/worst 5 + per-frame compact list. Requires OPENAI_API_KEY.",
+        parameters: ScoreShotParams,
+        async execute(args, ctx) {
+            try {
+                if (!checkFfmpeg())
+                    return err("ffmpeg not on PATH", "install ffmpeg");
+                if (!process.env.OPENAI_API_KEY) {
+                    return err("OPENAI_API_KEY not set", "export OPENAI_API_KEY=...");
+                }
+                const { input, times, intervalSec, detail, model, maxFrames = 30 } = args;
+                if (!times && !intervalSec) {
+                    return err("provide either `times` or `intervalSec`", "e.g. intervalSec=30 or times=[10,45,90]");
+                }
+                const abs = resolvePath(cwd, input);
+                const probe = probeMedia(abs);
+                if (!probe)
+                    return err(`probe failed for ${abs}`);
+                const startSec = args.startSec ?? 0;
+                const endSec = args.endSec ?? probe.durationSec;
+                const window = Math.max(0, endSec - startSec);
+                if (window <= 0)
+                    return err("endSec must be > startSec");
+                // Frame extraction
+                let frames;
+                if (times && times.length > 0) {
+                    const filtered = times.filter((t) => t >= startSec && t < endSec).slice(0, maxFrames);
+                    if (filtered.length === 0)
+                        return err("no times fall within [startSec, endSec)");
+                    frames = await extractAtTimes(abs, filtered, {
+                        maxWidth: 1280,
+                        signal: ctx.signal,
+                    });
+                }
+                else {
+                    // Auto-cap interval if it would produce > maxFrames
+                    let effectiveInterval = intervalSec;
+                    const wouldProduce = Math.floor(window / effectiveInterval);
+                    if (wouldProduce > maxFrames) {
+                        effectiveInterval = window / maxFrames;
+                    }
+                    // extractAtInterval samples relative to file 0; we need to slice the
+                    // window by adjusting input. For simplicity, sample whole file then
+                    // filter to [startSec, endSec). For long videos with small windows,
+                    // ffmpeg input -ss/-t would be faster — defer optimisation.
+                    const all = await extractAtInterval(abs, effectiveInterval, probe.durationSec, {
+                        maxWidth: 1280,
+                        signal: ctx.signal,
+                    });
+                    frames = all.filter((f) => f.atSec >= startSec && f.atSec < endSec);
+                    if (frames.length > maxFrames)
+                        frames = frames.slice(0, maxFrames);
+                }
+                if (frames.length === 0)
+                    return err("no frames extracted");
+                // Score
+                const scores = await scoreFrames(frames, {
+                    model,
+                    detail,
+                    signal: ctx.signal,
+                });
+                // Sort + summarize
+                const sorted = [...scores].sort((a, b) => b.score - a.score);
+                const top = sorted.slice(0, 5).map(roundShot);
+                const worst = sorted.slice(-5).reverse().map(roundShot); // worst first
+                const all = scores.map(roundShot);
+                const allSummary = summarizeList(all, 30);
+                return compact({
+                    frames: scores.length,
+                    window: { startSec, endSec },
+                    top,
+                    worst,
+                    ...(allSummary.omitted > 0
+                        ? { omitted: allSummary.omitted, head: allSummary.head, tail: allSummary.tail }
+                        : { all }),
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+function roundShot(s) {
+    return { at: +s.atSec.toFixed(2), score: s.score, why: s.why };
+}
+//# sourceMappingURL=score-shot.js.map

package/dist/tools/score-shot.js.map

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

package/dist/tools/search-tools.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+/**
+ * search_tools — meta-tool. With ~85+ named tools the agent can wind up
+ * scanning the system prompt to remember a tool's exact name; this is
+ * a token-cheap shortcut: pass a query, get back the top matches with
+ * their one-line descriptions.
+ *
+ * The factory receives a *getter* so we can reflect over the live tool
+ * registry as it stands at agent-construction time. We avoid a circular
+ * import by accepting the tool list directly.
+ */
+declare const SearchToolsParams: z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export interface SearchableTool {
+    name: string;
+    description: string;
+}
+/**
+ * Score a tool against a query. Higher = better match. Pure function so the
+ * algorithm can be tuned + tested without booting the agent.
+ *
+ * Heuristic:
+ *   +5 per query word that appears in the tool name
+ *   +1 per query word that appears in the description
+ *   +3 if the query is a substring of the name
+ *   normalize: lowercase, strip non-alphanumerics
+ */
+export declare function scoreToolMatch(query: string, tool: SearchableTool): number;
+export declare function createSearchToolsTool(getTools: () => SearchableTool[]): AgentTool<typeof SearchToolsParams>;
+export {};
+//# sourceMappingURL=search-tools.d.ts.map

package/dist/tools/search-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-tools.d.ts","sourceRoot":"","sources":["../../src/tools/search-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;;;;;;;;GASG;AAEH,QAAA,MAAM,iBAAiB;;;iBASrB,CAAC;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,MAAM,CAe1E;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,cAAc,EAAE,GAC/B,SAAS,CAAC,OAAO,iBAAiB,CAAC,CAkCrC"}

package/dist/tools/search-tools.js

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+/**
+ * search_tools — meta-tool. With ~85+ named tools the agent can wind up
+ * scanning the system prompt to remember a tool's exact name; this is
+ * a token-cheap shortcut: pass a query, get back the top matches with
+ * their one-line descriptions.
+ *
+ * The factory receives a *getter* so we can reflect over the live tool
+ * registry as it stands at agent-construction time. We avoid a circular
+ * import by accepting the tool list directly.
+ */
+const SearchToolsParams = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("What you're looking for. Free text — matches against tool names AND descriptions. " +
+        "E.g. 'silence', 'youtube metadata', 'caption emoji'."),
+    limit: z.number().int().min(1).max(20).optional().describe("Max results. Default 8."),
+});
+/**
+ * Score a tool against a query. Higher = better match. Pure function so the
+ * algorithm can be tuned + tested without booting the agent.
+ *
+ * Heuristic:
+ *   +5 per query word that appears in the tool name
+ *   +1 per query word that appears in the description
+ *   +3 if the query is a substring of the name
+ *   normalize: lowercase, strip non-alphanumerics
+ */
+export function scoreToolMatch(query, tool) {
+    const q = query.toLowerCase().trim();
+    if (q.length === 0)
+        return 0;
+    const nameLc = tool.name.toLowerCase();
+    const descLc = tool.description.toLowerCase();
+    let score = 0;
+    if (nameLc.includes(q.replace(/\s+/g, "_")))
+        score += 3;
+    if (nameLc.includes(q))
+        score += 3;
+    const words = q.split(/[^a-z0-9]+/).filter((w) => w.length >= 2);
+    for (const w of words) {
+        if (nameLc.includes(w))
+            score += 5;
+        if (descLc.includes(w))
+            score += 1;
+    }
+    return score;
+}
+export function createSearchToolsTool(getTools) {
+    return {
+        name: "search_tools",
+        description: "Find tools by query — fuzzy-matches against names and descriptions. Use when you need a " +
+            "capability and aren't sure which tool exposes it. Returns top matches with their one-line " +
+            "descriptions. Cheap (no LLM, no I/O). Token-savvy alternative to re-scanning the system " +
+            "prompt.",
+        parameters: SearchToolsParams,
+        async execute({ query, limit }) {
+            try {
+                const tools = getTools().filter((t) => t.name !== "search_tools");
+                const max = Math.min(limit ?? 8, 20);
+                const scored = tools
+                    .map((t) => ({ tool: t, score: scoreToolMatch(query, t) }))
+                    .filter((s) => s.score > 0)
+                    .sort((a, b) => b.score - a.score)
+                    .slice(0, max);
+                if (scored.length === 0) {
+                    return compact({ matches: [], note: "no tools matched — try a broader query" });
+                }
+                return compact({
+                    matches: scored.map((s) => ({
+                        name: s.tool.name,
+                        description: s.tool.description,
+                        score: s.score,
+                    })),
+                    total: scored.length,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=search-tools.js.map

package/dist/tools/search-tools.js.map

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

package/dist/tools/search-tools.test.d.ts

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

package/dist/tools/search-tools.test.d.ts.map

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

package/dist/tools/search-tools.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { createSearchToolsTool, scoreToolMatch } from "./search-tools.js";
+const FAKE_TOOLS = [
+    { name: "detect_silence", description: "ffmpeg silencedetect → frame-aligned KEEP ranges" },
+    { name: "trim_dead_air", description: "Trim leading/trailing or all silence in one call" },
+    { name: "write_srt", description: "SubRip caption writer (sentence + word-level)" },
+    { name: "burn_subtitles", description: "Hardcode .srt or .ass into a video" },
+    {
+        name: "generate_youtube_metadata",
+        description: "Title, description, tags, chapters from a transcript",
+    },
+];
+const ctx = {
+    signal: new AbortController().signal,
+    toolCallId: "t1",
+};
+describe("scoreToolMatch", () => {
+    it("ranks exact name substring highest", () => {
+        expect(scoreToolMatch("silence", FAKE_TOOLS[0])).toBeGreaterThan(scoreToolMatch("silence", FAKE_TOOLS[2]));
+    });
+    it("returns 0 when no overlap", () => {
+        expect(scoreToolMatch("rocket", FAKE_TOOLS[0])).toBe(0);
+    });
+    it("rewards multi-word queries", () => {
+        const single = scoreToolMatch("youtube", FAKE_TOOLS[4]);
+        const multi = scoreToolMatch("youtube metadata", FAKE_TOOLS[4]);
+        expect(multi).toBeGreaterThan(single);
+    });
+    it("handles empty query", () => {
+        expect(scoreToolMatch("", FAKE_TOOLS[0])).toBe(0);
+    });
+});
+describe("search_tools tool", () => {
+    const tool = createSearchToolsTool(() => FAKE_TOOLS);
+    it("returns matches in score order", async () => {
+        const r = await tool.execute({ query: "silence" }, ctx);
+        expect(typeof r).toBe("string");
+        const parsed = JSON.parse(r);
+        expect(parsed.matches[0].name).toBe("detect_silence");
+    });
+    it("limits results", async () => {
+        const r = await tool.execute({ query: "the" }, ctx);
+        const parsed = JSON.parse(r);
+        expect(parsed.matches.length).toBeLessThanOrEqual(8);
+    });
+    it("returns empty matches with a note on miss", async () => {
+        const r = await tool.execute({ query: "blockchain ethereum" }, ctx);
+        const parsed = JSON.parse(r);
+        expect(parsed.matches).toEqual([]);
+        expect(parsed.note).toBeTruthy();
+    });
+    it("excludes itself from results", async () => {
+        const tools = [...FAKE_TOOLS, { name: "search_tools", description: "Find tools by query" }];
+        const t = createSearchToolsTool(() => tools);
+        const r = await t.execute({ query: "tools" }, ctx);
+        const parsed = JSON.parse(r);
+        expect(parsed.matches.find((m) => m.name === "search_tools")).toBeUndefined();
+    });
+});
+//# sourceMappingURL=search-tools.test.js.map

package/dist/tools/search-tools.test.js.map

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

package/dist/tools/set-clip-speed.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+import type { VideoHost } from "../core/hosts/types.js";
+declare const SetClipSpeedParams: z.ZodObject<{
+    clipId: z.ZodString;
+    speed: z.ZodNumber;
+}, z.core.$strip>;
+export declare function createSetClipSpeedTool(host: VideoHost): AgentTool<typeof SetClipSpeedParams>;
+export {};
+//# sourceMappingURL=set-clip-speed.d.ts.map

package/dist/tools/set-clip-speed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-clip-speed.d.ts","sourceRoot":"","sources":["../../src/tools/set-clip-speed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,QAAA,MAAM,kBAAkB;;;iBAMtB,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,kBAAkB,CAAC,CAiB5F"}

package/dist/tools/set-clip-speed.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { err } from "../core/format.js";
+const SetClipSpeedParams = z.object({
+    clipId: z.string().min(1).describe("Clip id from get_timeline."),
+    speed: z
+        .number()
+        .positive()
+        .describe("Speed multiplier. 1=100%, 0.5=slow-mo (50%), 2=fast (200%)."),
+});
+export function createSetClipSpeedTool(host) {
+    return {
+        name: "set_clip_speed",
+        description: "Retime a clip on the active timeline. 0.5 = half-speed slow-mo, 2 = double-time. " +
+            "Useful for highlight reels, vlog energy bumps, and B-roll inserts in podcasts. " +
+            "If the host's API rejects, fall back to FCPXML rebuild with explicit timeMap.",
+        parameters: SetClipSpeedParams,
+        async execute({ clipId, speed }) {
+            try {
+                await host.setClipSpeed(clipId, speed);
+                return "ok";
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=set-clip-speed.js.map

package/dist/tools/set-clip-speed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-clip-speed.js","sourceRoot":"","sources":["../../src/tools/set-clip-speed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAGxC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAChE,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,6DAA6D,CAAC;CAC3E,CAAC,CAAC;AAEH,MAAM,UAAU,sBAAsB,CAAC,IAAe;IACpD,OAAO;QACL,IAAI,EAAE,gBAAgB;QACtB,WAAW,EACT,mFAAmF;YACnF,iFAAiF;YACjF,+EAA+E;QACjF,UAAU,EAAE,kBAAkB;QAC9B,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE;YAC7B,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;gBACvC,OAAO,IAAI,CAAC;YACd,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,GAAG,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/set-clip-volume.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+import type { VideoHost } from "../core/hosts/types.js";
+declare const SetClipVolumeParams: z.ZodObject<{
+    clipId: z.ZodString;
+    volumeDb: z.ZodNumber;
+}, z.core.$strip>;
+export declare function createSetClipVolumeTool(host: VideoHost): AgentTool<typeof SetClipVolumeParams>;
+export {};
+//# sourceMappingURL=set-clip-volume.d.ts.map

package/dist/tools/set-clip-volume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-clip-volume.d.ts","sourceRoot":"","sources":["../../src/tools/set-clip-volume.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,QAAA,MAAM,mBAAmB;;;iBAOvB,CAAC;AAEH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,CAAC,OAAO,mBAAmB,CAAC,CAwB9F"}

package/dist/tools/set-clip-volume.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+const SetClipVolumeParams = z.object({
+    clipId: z.string().min(1).describe("Clip id from get_timeline."),
+    volumeDb: z
+        .number()
+        .min(-60)
+        .max(24)
+        .describe("Gain in dB. 0 = unchanged, -6 = quieter, +3 = louder. Hard limits ±60/24 dB."),
+});
+export function createSetClipVolumeTool(host) {
+    return {
+        name: "set_clip_volume",
+        description: "Set a clip's audio gain in dB (Resolve only — Premiere unsupported). " +
+            "Standard use: even out level differences across speakers in an interview before " +
+            "loudness normalization. ±3 dB is the typical nudge range; ±10+ usually means the " +
+            "underlying audio needs cleanup or replacement instead.",
+        parameters: SetClipVolumeParams,
+        async execute({ clipId, volumeDb }) {
+            if (!host.setClipVolume) {
+                return err(`${host.name} does not support set_clip_volume`, "use Resolve for clip-level volume; Premiere requires manual mixer adjustments");
+            }
+            try {
+                await host.setClipVolume(clipId, volumeDb);
+                return compact({ ok: true, clipId, volumeDb });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=set-clip-volume.js.map

package/dist/tools/set-clip-volume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-clip-volume.js","sourceRoot":"","sources":["../../src/tools/set-clip-volume.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAGjD,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAChE,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,CAAC;SACR,GAAG,CAAC,EAAE,CAAC;SACP,QAAQ,CAAC,8EAA8E,CAAC;CAC5F,CAAC,CAAC;AAEH,MAAM,UAAU,uBAAuB,CAAC,IAAe;IACrD,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,uEAAuE;YACvE,kFAAkF;YAClF,mFAAmF;YACnF,wDAAwD;QAC1D,UAAU,EAAE,mBAAmB;QAC/B,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE;YAChC,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACxB,OAAO,GAAG,CACR,GAAG,IAAI,CAAC,IAAI,mCAAmC,EAC/C,+EAA+E,CAChF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;gBAC3C,OAAO,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;YACjD,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,GAAG,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/tools/set-primary-correction.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+import type { VideoHost } from "../core/hosts/types.js";
+declare const SetPrimaryCorrectionParams: z.ZodObject<{
+    clipId: z.ZodString;
+    slope: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    offset: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    power: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+    saturation: z.ZodOptional<z.ZodNumber>;
+    nodeIndex: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createSetPrimaryCorrectionTool(host: VideoHost): AgentTool<typeof SetPrimaryCorrectionParams>;
+export {};
+//# sourceMappingURL=set-primary-correction.d.ts.map

package/dist/tools/set-primary-correction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"set-primary-correction.d.ts","sourceRoot":"","sources":["../../src/tools/set-primary-correction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAMxD,QAAA,MAAM,0BAA0B;;;;;;;iBAO9B,CAAC;AAEH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,SAAS,GACd,SAAS,CAAC,OAAO,0BAA0B,CAAC,CAgC9C"}