@prestyj/editor 0.7.1

package/dist/tools/cut-filler-words.js

@@ -0,0 +1,182 @@
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, extname, join, resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { buildEdl } from "../core/edl.js";
+import { DEFAULT_FILLERS, detectFillerRanges, keepRangesFromFillers, keepRangesToFrameRanges, keepRangesToTimelineCuts, summarizeFillers, } from "../core/filler-words.js";
+import { compact, err } from "../core/format.js";
+import { probeMedia } from "../core/media/ffmpeg.js";
+import { safeOutputPath } from "../core/safe-paths.js";
+import { parseTranscript } from "../core/whisper.js";
+const CutFillerWordsParams = z.object({
+    transcript: z
+        .string()
+        .describe("Path to a transcript JSON written by `transcribe(wordTimestamps=true)`. Must include " +
+        "word-level timings — without them this tool can't locate the fillers. Returns an error otherwise."),
+    sourceVideo: z
+        .string()
+        .describe("The video the transcript was made from. Used as the source media in the emitted EDL " +
+        "(reel name + frame rate detection)."),
+    fillers: z
+        .array(z.string())
+        .optional()
+        .describe(`Custom filler vocabulary (case-insensitive, supports multi-word phrases). Defaults to ` +
+        `[${DEFAULT_FILLERS.join(", ")}]. Override when the speaker's verbal tics differ — ` +
+        `e.g. ["right?", "obviously"].`),
+    aggressiveSingleWords: z
+        .boolean()
+        .optional()
+        .describe("When true (tool default), include ambiguous single-word fillers (like, so, actually, " +
+        "basically, literally, honestly, right). When false, only the safe-list (um/uh/er/hmm/" +
+        "you know/i mean/kind of/sort of) is matched — useful when the speaker uses these " +
+        "words substantively. The underlying detectFillerRanges() library defaults to false; " +
+        "this tool preserves the historical aggressive=true behavior for the end user."),
+    paddingStartMs: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Lead-in padding so the cut doesn't clip the previous word's tail. Default 20ms."),
+    paddingEndMs: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Lead-out padding so the cut doesn't clip the next word's head. Default 20ms."),
+    mergeGapMs: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Adjacent fillers within this gap merge into one cut (avoids 3-frame keep clips). Default 150ms."),
+    edlOutput: z
+        .string()
+        .optional()
+        .describe("Path for the emitted .edl file (relative resolves to cwd). Defaults to a tempfile."),
+    reel: z
+        .string()
+        .optional()
+        .describe("EDL reel name. Default = source video basename without extension (truncated to 8 chars)."),
+    frameRate: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Override frame rate. Auto-detected from probe if omitted; 30 if probe fails."),
+    /**
+     * Returns the EDL path + summary stats but does NOT call import_edl.
+     * The agent typically chains this tool to `import_edl(path)` separately
+     * (so the user can review filler choices first).
+     */
+    dryRun: z
+        .boolean()
+        .optional()
+        .describe("If true (default), return the EDL path + stats without importing. The agent should " +
+        "surface stats to the user before calling import_edl. Pass false to skip the review step."),
+});
+/**
+ * cut_filler_words — the canonical "podcast / interview / vlog" cleanup
+ * step. Read a word-timestamped transcript, find every filler-word
+ * range, emit an EDL of KEEP ranges, write it, return stats.
+ *
+ * The agent's job is then to surface the stats ("removed 47 fillers,
+ * 8.3s total — top: um (24), uh (15)"), wait for user OK, then call
+ * import_edl(path) to apply the cuts.
+ */
+export function createCutFillerWordsTool(cwd) {
+    return {
+        name: "cut_filler_words",
+        description: "Detect and remove filler words ('um', 'uh', 'you know', 'i mean', …) from a " +
+            "word-timestamped transcript. Emits an EDL of KEEP ranges (the parts to keep, with " +
+            "small padding so cuts don't clip syllables). REQUIRES word-level timings — call " +
+            "transcribe(wordTimestamps=true) first. Returns {path, stats, keeps, timelineCutPoints}; " +
+            "⚠️ pass `timelineCutPoints` (NOT source transcript timestamps) to add_sfx_to_timeline / " +
+            "add_sfx_at_cuts — those tools work in TIMELINE space, and source-space points drift after " +
+            "every cut. Agent should " +
+            "show the stats to the user, then import_edl(path) when approved. The single biggest " +
+            "creator-time-saver on long-form talking-head content.",
+        parameters: CutFillerWordsParams,
+        async execute(args) {
+            try {
+                const transcriptAbs = resolvePath(cwd, args.transcript);
+                const sourceAbs = resolvePath(cwd, args.sourceVideo);
+                let raw;
+                try {
+                    raw = readFileSync(transcriptAbs, "utf8");
+                }
+                catch (e) {
+                    return err(`cannot read transcript ${transcriptAbs}: ${e.message}`, "verify the transcript JSON exists");
+                }
+                let transcript;
+                try {
+                    transcript = parseTranscript(raw);
+                }
+                catch (e) {
+                    return err(e.message, "regenerate via transcribe(wordTimestamps=true)");
+                }
+                const hasWords = transcript.segments.some((s) => Array.isArray(s.words) && s.words.length > 0);
+                if (!hasWords) {
+                    return err("transcript has no word-level timings", "rerun transcribe(wordTimestamps=true) — without word timings we can't locate fillers");
+                }
+                const fillers = detectFillerRanges(transcript, {
+                    fillers: args.fillers,
+                    // Tool default is true (aggressive) to preserve existing user behavior;
+                    // the underlying library now defaults to false (conservative).
+                    aggressiveSingleWords: args.aggressiveSingleWords ?? true,
+                    paddingStartMs: args.paddingStartMs,
+                    paddingEndMs: args.paddingEndMs,
+                    mergeGapMs: args.mergeGapMs,
+                });
+                const probe = probeMedia(sourceAbs);
+                const totalSec = probe?.durationSec ?? transcript.durationSec;
+                const fps = args.frameRate ?? probe?.frameRate ?? 30;
+                const keeps = keepRangesFromFillers(fillers, totalSec);
+                const frameKeeps = keepRangesToFrameRanges(keeps, fps);
+                // Timeline-space cut points: where each junction lands AFTER the
+                // EDL is imported. Pass these to add_sfx_to_timeline /
+                // add_sfx_at_cuts — NOT the source-space filler timestamps.
+                const timelineCutPoints = keepRangesToTimelineCuts(keeps);
+                if (frameKeeps.length === 0) {
+                    return err("no keep ranges produced — fillers may cover the entire transcript", "broaden vocabulary or check word timings");
+                }
+                const reelName = args.reel ?? basename(sourceAbs, extname(sourceAbs)).replace(/[^A-Za-z0-9_]/g, "_");
+                const edl = buildEdl({
+                    title: `${basename(sourceAbs)} (filler-cut)`,
+                    frameRate: fps,
+                    events: frameKeeps.map((k) => ({
+                        reel: reelName,
+                        track: "B",
+                        sourceInFrame: k.startFrame,
+                        sourceOutFrame: k.endFrame,
+                        clipName: basename(sourceAbs),
+                    })),
+                });
+                const outAbs = args.edlOutput
+                    ? safeOutputPath(cwd, args.edlOutput)
+                    : join(mkdtempSync(join(tmpdir(), "gg-fillercut-")), "fillers.edl");
+                if (args.edlOutput)
+                    mkdirSync(dirname(outAbs), { recursive: true });
+                writeFileSync(outAbs, edl, "utf8");
+                const stats = summarizeFillers(fillers);
+                const dryRun = args.dryRun ?? true;
+                return compact({
+                    path: outAbs,
+                    dryRun,
+                    stats,
+                    keeps: keeps.length,
+                    fps,
+                    totalSec,
+                    // TIMELINE-space cut points (one per junction between keeps). Use
+                    // these for add_sfx_to_timeline / add_sfx_at_cuts. Source-space
+                    // timestamps from the transcript would drift after each cut.
+                    timelineCutPoints,
+                    // Surface a short list so the agent can quote it back to the user.
+                    sample: fillers.slice(0, 10).map((f) => ({
+                        atSec: +f.startSec.toFixed(2),
+                        text: f.text,
+                    })),
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=cut-filler-words.js.map

package/dist/tools/cut-filler-words.js.map

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

package/dist/tools/detect-silence.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const DetectSilenceParams: z.ZodObject<{
+    input: z.ZodString;
+    noiseDb: z.ZodOptional<z.ZodNumber>;
+    minDurationSec: z.ZodOptional<z.ZodNumber>;
+    paddingSec: z.ZodOptional<z.ZodNumber>;
+    returnKeeps: z.ZodOptional<z.ZodBoolean>;
+    frameRate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createDetectSilenceTool(cwd: string): AgentTool<typeof DetectSilenceParams>;
+export {};
+//# sourceMappingURL=detect-silence.d.ts.map

package/dist/tools/detect-silence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-silence.d.ts","sourceRoot":"","sources":["../../src/tools/detect-silence.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAShD,QAAA,MAAM,mBAAmB;;;;;;;iBA4BvB,CAAC;AAEH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,mBAAmB,CAAC,CAmF1F"}

package/dist/tools/detect-silence.js

@@ -0,0 +1,98 @@
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err, summarizeList } from "../core/format.js";
+import { checkFfmpeg, probeMedia, runFfmpeg } from "../core/media/ffmpeg.js";
+import { keepRangesFromSilences, parseSilenceDetect, silencesToFrameRanges, } from "../core/silence.js";
+const DetectSilenceParams = z.object({
+    input: z.string().describe("Media file (video or audio). ffmpeg reads the audio stream."),
+    noiseDb: z
+        .number()
+        .optional()
+        .describe("Threshold in dB below which is silent (default -30, more negative = stricter)."),
+    minDurationSec: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Minimum silence length to report (default 0.5s)."),
+    paddingSec: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Padding around keep-ranges so cuts don't slice syllables (default 0.1s)."),
+    returnKeeps: z
+        .boolean()
+        .optional()
+        .describe("If true (default), return KEEP ranges (the inverse) plus frame-aligned versions — " +
+        "feed straight into write_edl. If false, return raw silence ranges only."),
+    frameRate: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Used to add frame-aligned ranges. Auto-detected from probe if omitted."),
+});
+export function createDetectSilenceTool(cwd) {
+    return {
+        name: "detect_silence",
+        description: "Find silent regions in an audio/video file via ffmpeg silencedetect. " +
+            "Default returns KEEP ranges (the parts to keep, with optional padding) plus frame-aligned " +
+            "versions ready for write_edl. " +
+            "Workflow: probe_media → detect_silence → write_edl(events=keeps) → import_edl.",
+        parameters: DetectSilenceParams,
+        async execute({ input, noiseDb = -30, minDurationSec = 0.5, paddingSec = 0.1, returnKeeps = true, frameRate, }, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            const abs = resolvePath(cwd, input);
+            // Probe for fps + duration. fps is needed for frame alignment; duration
+            // closes any unterminated trailing silence the filter omits.
+            const probe = probeMedia(abs);
+            if (!probe)
+                return err(`probe failed for ${abs}`, "verify file exists and is media");
+            const fps = frameRate ?? probe.frameRate ?? 30;
+            const totalSec = probe.durationSec;
+            // Run silencedetect. "-f null -" discards output; the filter writes to stderr.
+            const r = await runFfmpeg([
+                "-i",
+                abs,
+                "-af",
+                `silencedetect=noise=${noiseDb}dB:d=${minDurationSec}`,
+                "-f",
+                "null",
+                "-",
+            ], { signal: ctx.signal });
+            if (r.code !== 0) {
+                return err(`ffmpeg exited ${r.code}`, "check input file is valid media");
+            }
+            const silences = parseSilenceDetect(r.stderr, totalSec);
+            if (!returnKeeps) {
+                const summary = summarizeList(silences, 30);
+                return compact({
+                    ranges: silences,
+                    totalSec,
+                    fps,
+                    count: summary.total,
+                    omitted: summary.omitted,
+                    ...(summary.omitted > 0 ? { head: summary.head, tail: summary.tail } : {}),
+                });
+            }
+            const keeps = keepRangesFromSilences(silences, totalSec, paddingSec);
+            const keepFrames = silencesToFrameRanges(keeps, fps);
+            // Pair keep seconds with their frame-aligned versions for direct EDL use.
+            const events = keeps.map((k, i) => ({
+                startSec: k.startSec,
+                endSec: k.endSec,
+                startFrame: keepFrames[i]?.startFrame ?? 0,
+                endFrame: keepFrames[i]?.endFrame ?? 0,
+            }));
+            const summary = summarizeList(events, 30);
+            return compact({
+                totalSec,
+                fps,
+                silences: silences.length,
+                keeps: summary.total,
+                omitted: summary.omitted,
+                ...(summary.omitted > 0 ? { head: summary.head, tail: summary.tail } : { events }),
+            });
+        },
+    };
+}
+//# sourceMappingURL=detect-silence.js.map

package/dist/tools/detect-silence.js.map

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

package/dist/tools/detect-speaker-changes.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const DetectSpeakerChangesParams: z.ZodObject<{
+    path: z.ZodString;
+    minGapSec: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createDetectSpeakerChangesTool(cwd: string): AgentTool<typeof DetectSpeakerChangesParams>;
+export {};
+//# sourceMappingURL=detect-speaker-changes.d.ts.map

package/dist/tools/detect-speaker-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-speaker-changes.d.ts","sourceRoot":"","sources":["../../src/tools/detect-speaker-changes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,QAAA,MAAM,0BAA0B;;;iBAO9B,CAAC;AAEH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,MAAM,GACV,SAAS,CAAC,OAAO,0BAA0B,CAAC,CA2B9C"}

package/dist/tools/detect-speaker-changes.js

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err, summarizeList } from "../core/format.js";
+import { detectSpeakerChanges } from "../core/speaker-changes.js";
+import { parseTranscript } from "../core/whisper.js";
+const DetectSpeakerChangesParams = z.object({
+    path: z.string().describe("Transcript JSON file (output of `transcribe`)."),
+    minGapSec: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Minimum silence gap to flag as a candidate speaker change. Default 1.5s."),
+});
+export function createDetectSpeakerChangesTool(cwd) {
+    return {
+        name: "detect_speaker_changes",
+        description: "Heuristic v1: silence-gap candidates for speaker boundaries. Returns inter-segment " +
+            "gaps > minGapSec as CANDIDATES — not assignments. Reasonable for fast-cut interview " +
+            "audio with clear handoffs; UNRELIABLE for natural overlap, rapid back-and-forth, or " +
+            "single-speaker monologues with dramatic pauses. For real diarization, run the audio " +
+            "through whisperx/AssemblyAI first and import that transcript instead — read_transcript " +
+            "supports a `speaker` filter when the JSON includes labels.",
+        parameters: DetectSpeakerChangesParams,
+        async execute({ path, minGapSec }) {
+            try {
+                const abs = resolvePath(cwd, path);
+                const t = parseTranscript(readFileSync(abs, "utf8"));
+                const candidates = detectSpeakerChanges(t, { minGapSec });
+                const s = summarizeList(candidates, 30);
+                return compact({
+                    total: s.total,
+                    minGapSec: minGapSec ?? 1.5,
+                    ...(s.omitted > 0 ? { head: s.head, tail: s.tail, omitted: s.omitted } : { candidates }),
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=detect-speaker-changes.js.map

package/dist/tools/detect-speaker-changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-speaker-changes.js","sourceRoot":"","sources":["../../src/tools/detect-speaker-changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;IAC3E,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,EAAE;SACV,QAAQ,CAAC,0EAA0E,CAAC;CACxF,CAAC,CAAC;AAEH,MAAM,UAAU,8BAA8B,CAC5C,GAAW;IAEX,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,qFAAqF;YACrF,sFAAsF;YACtF,sFAAsF;YACtF,sFAAsF;YACtF,yFAAyF;YACzF,4DAA4D;QAC9D,UAAU,EAAE,0BAA0B;QACtC,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;YAC/B,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBACnC,MAAM,CAAC,GAAG,eAAe,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;gBACrD,MAAM,UAAU,GAAG,oBAAoB,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC1D,MAAM,CAAC,GAAG,aAAa,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;gBACxC,OAAO,OAAO,CAAC;oBACb,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,SAAS,EAAE,SAAS,IAAI,GAAG;oBAC3B,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;iBACzF,CAAC,CAAC;YACL,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/duck-audio.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const DuckAudioParams: z.ZodObject<{
+    voice: z.ZodString;
+    background: z.ZodString;
+    output: z.ZodString;
+    threshold: z.ZodOptional<z.ZodNumber>;
+    ratio: z.ZodOptional<z.ZodNumber>;
+    attackMs: z.ZodOptional<z.ZodNumber>;
+    releaseMs: z.ZodOptional<z.ZodNumber>;
+    voiceGain: z.ZodOptional<z.ZodNumber>;
+    bgGain: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createDuckAudioTool(cwd: string): AgentTool<typeof DuckAudioParams>;
+export {};
+//# sourceMappingURL=duck-audio.d.ts.map

package/dist/tools/duck-audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duck-audio.d.ts","sourceRoot":"","sources":["../../src/tools/duck-audio.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,QAAA,MAAM,eAAe;;;;;;;;;;iBA+BnB,CAAC;AAEH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,eAAe,CAAC,CAkClF"}

package/dist/tools/duck-audio.js

@@ -0,0 +1,73 @@
+import { mkdirSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+import { duckAudio } from "../core/ducking.js";
+import { checkFfmpeg } from "../core/media/ffmpeg.js";
+const DuckAudioParams = z.object({
+    voice: z.string().describe("Voice / dialogue track (audio or video file)."),
+    background: z.string().describe("Music or ambient track to duck."),
+    output: z.string().describe("Mixed output path."),
+    threshold: z
+        .number()
+        .min(0)
+        .max(1)
+        .optional()
+        .describe("Sidechain threshold (linear amplitude, 0-1). Voice ABOVE this triggers ducking. " +
+        "Default 0.02 matches typical dialogue average energy. Try 0.012 for very quiet voices, " +
+        "0.05 if music keeps ducking on background noise."),
+    ratio: z
+        .number()
+        .min(1)
+        .optional()
+        .describe("Compression ratio. Default 8 (heavy duck — typical podcast)."),
+    attackMs: z.number().min(0).optional().describe("Attack in ms. Default 5."),
+    releaseMs: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Release in ms. Default 250 — music breathes back gradually."),
+    voiceGain: z.number().min(0).optional().describe("Voice level multiplier. Default 1."),
+    bgGain: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Background level multiplier (pre-duck). Default 1."),
+});
+export function createDuckAudioTool(cwd) {
+    return {
+        name: "duck_audio",
+        description: "Sidechain ducking: lower a music/ambient track when voice is present (then bring it " +
+            "back when silent). Standard podcast/YouTube technique. Defaults are tuned for spoken " +
+            "voice over music. Output is a single mixed audio file. Run AFTER take selection / " +
+            "filler removal but BEFORE normalize_loudness.",
+        parameters: DuckAudioParams,
+        async execute(args, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            try {
+                const voiceAbs = resolvePath(cwd, args.voice);
+                const bgAbs = resolvePath(cwd, args.background);
+                const outAbs = resolvePath(cwd, args.output);
+                if (voiceAbs === outAbs || bgAbs === outAbs) {
+                    return err("output path collides with an input", "use a different output path");
+                }
+                mkdirSync(dirname(outAbs), { recursive: true });
+                const r = await duckAudio(voiceAbs, bgAbs, outAbs, {
+                    threshold: args.threshold,
+                    ratio: args.ratio,
+                    attackMs: args.attackMs,
+                    releaseMs: args.releaseMs,
+                    voiceGain: args.voiceGain,
+                    bgGain: args.bgGain,
+                    signal: ctx.signal,
+                });
+                return compact({ ok: true, path: r.output });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=duck-audio.js.map

package/dist/tools/duck-audio.js.map

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

package/dist/tools/extract-audio.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const ExtractAudioParams: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+    sampleRate: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createExtractAudioTool(cwd: string): AgentTool<typeof ExtractAudioParams>;
+export {};
+//# sourceMappingURL=extract-audio.d.ts.map

package/dist/tools/extract-audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-audio.d.ts","sourceRoot":"","sources":["../../src/tools/extract-audio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,QAAA,MAAM,kBAAkB;;;;iBAItB,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,kBAAkB,CAAC,CA0BxF"}

package/dist/tools/extract-audio.js

@@ -0,0 +1,36 @@
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { clip, err } from "../core/format.js";
+import { checkFfmpeg, runFfmpeg } from "../core/media/ffmpeg.js";
+import { safeOutputPath } from "../core/safe-paths.js";
+const ExtractAudioParams = z.object({
+    input: z.string(),
+    output: z.string().describe(".wav recommended for downstream analysis."),
+    sampleRate: z.number().int().optional().describe("Default 16000 (whisper-friendly)."),
+});
+export function createExtractAudioTool(cwd) {
+    return {
+        name: "extract_audio",
+        description: "Extract a video's audio as mono WAV (default 16kHz). First step for transcription, " +
+            "silence detection, or audio analysis.",
+        parameters: ExtractAudioParams,
+        async execute({ input, output, sampleRate = 16000 }, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            try {
+                const inAbs = resolvePath(cwd, input);
+                const outAbs = safeOutputPath(cwd, output);
+                const r = await runFfmpeg(["-i", inAbs, "-vn", "-ac", "1", "-ar", String(sampleRate), "-c:a", "pcm_s16le", outAbs], { signal: ctx.signal });
+                if (r.code !== 0) {
+                    const tail = r.stderr.split("\n").filter(Boolean).slice(-3).join(" | ");
+                    return err(`ffmpeg exited ${r.code}: ${clip(tail, 200)}`);
+                }
+                return `ok:${outAbs}`;
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=extract-audio.js.map

package/dist/tools/extract-audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-audio.js","sourceRoot":"","sources":["../../src/tools/extract-audio.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IACxE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;CACtF,CAAC,CAAC;AAEH,MAAM,UAAU,sBAAsB,CAAC,GAAW;IAChD,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,WAAW,EACT,qFAAqF;YACrF,uCAAuC;QACzC,UAAU,EAAE,kBAAkB;QAC9B,KAAK,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,GAAG,KAAK,EAAE,EAAE,GAAG;YACtD,IAAI,CAAC,WAAW,EAAE;gBAAE,OAAO,GAAG,CAAC,oBAAoB,EAAE,gBAAgB,CAAC,CAAC;YACvE,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBACtC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAC3C,MAAM,CAAC,GAAG,MAAM,SAAS,CACvB,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,EACxF,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CACvB,CAAC;gBACF,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACjB,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACxE,OAAO,GAAG,CAAC,iBAAiB,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC5D,CAAC;gBACD,OAAO,MAAM,MAAM,EAAE,CAAC;YACxB,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/extract-frame.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const ExtractFrameParams: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+    atSec: z.ZodNumber;
+    quality: z.ZodOptional<z.ZodNumber>;
+    maxWidth: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createExtractFrameTool(cwd: string): AgentTool<typeof ExtractFrameParams>;
+export {};
+//# sourceMappingURL=extract-frame.d.ts.map

package/dist/tools/extract-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-frame.d.ts","sourceRoot":"","sources":["../../src/tools/extract-frame.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,QAAA,MAAM,kBAAkB;;;;;;iBAiBtB,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,kBAAkB,CAAC,CA0CxF"}

package/dist/tools/extract-frame.js

@@ -0,0 +1,70 @@
+import { mkdirSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+import { checkFfmpeg, runFfmpeg } from "../core/media/ffmpeg.js";
+import { safeResolveOutputPath } from "../core/safe-paths.js";
+const ExtractFrameParams = z.object({
+    input: z.string().describe("Source video file."),
+    output: z.string().describe(".jpg or .png path for the extracted frame."),
+    atSec: z.number().min(0).describe("Timestamp in seconds where to grab the frame."),
+    quality: z
+        .number()
+        .int()
+        .min(1)
+        .max(31)
+        .optional()
+        .describe("JPEG quality 1-31 (lower=better, ffmpeg convention). Default 2."),
+    maxWidth: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional max width — preserves aspect, scales down."),
+});
+export function createExtractFrameTool(cwd) {
+    return {
+        name: "extract_frame",
+        description: "Pull a single frame as a JPEG/PNG file. Use AFTER score_shot to save the chosen " +
+            "hero frame as a thumbnail. Pair with score_shot(times=[...]) to find the moment, " +
+            "then this tool to save it.",
+        parameters: ExtractFrameParams,
+        async execute({ input, output, atSec, quality, maxWidth }, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            try {
+                const inAbs = resolvePath(cwd, input);
+                const resolved = safeResolveOutputPath(cwd, output);
+                const outAbs = resolved.path;
+                mkdirSync(dirname(outAbs), { recursive: true });
+                const args = [
+                    "-ss",
+                    String(atSec),
+                    "-i",
+                    inAbs,
+                    "-frames:v",
+                    "1",
+                    "-q:v",
+                    String(quality ?? 2),
+                ];
+                if (maxWidth)
+                    args.push("-vf", `scale=${maxWidth}:-1`);
+                args.push(outAbs);
+                const r = await runFfmpeg(args, { signal: ctx.signal });
+                if (r.code !== 0) {
+                    return err(`ffmpeg exited ${r.code}`, "verify atSec is within file duration");
+                }
+                return compact({
+                    ok: true,
+                    path: outAbs,
+                    atSec,
+                    ...(resolved.redirected ? { redirected: true, reason: resolved.reason } : {}),
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=extract-frame.js.map

package/dist/tools/extract-frame.js.map

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