@kenkaiiii/gg-editor 0.1.0

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

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

package/dist/core/clustering.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { clusterSegments, jaccard, tokenize } from "./clustering.js";
+describe("tokenize", () => {
+    it("lowercases and strips punctuation", () => {
+        const t = tokenize("Hello, World! It's GREAT.");
+        expect(t.has("hello")).toBe(true);
+        expect(t.has("world")).toBe(true);
+        expect(t.has("great")).toBe(true);
+        expect(t.has("it's")).toBe(true);
+    });
+    it("drops stopwords and filler", () => {
+        const t = tokenize("um the quick brown fox like yeah");
+        expect(t.has("um")).toBe(false);
+        expect(t.has("the")).toBe(false);
+        expect(t.has("like")).toBe(false);
+        expect(t.has("yeah")).toBe(false);
+        expect(t.has("quick")).toBe(true);
+        expect(t.has("brown")).toBe(true);
+        expect(t.has("fox")).toBe(true);
+    });
+    it("drops single-character tokens", () => {
+        const t = tokenize("a b cat dog");
+        expect(t.has("a")).toBe(false);
+        expect(t.has("b")).toBe(false);
+        expect(t.has("cat")).toBe(true);
+    });
+});
+describe("jaccard", () => {
+    it("returns 0 for disjoint sets", () => {
+        expect(jaccard(new Set(["a", "b"]), new Set(["c", "d"]))).toBe(0);
+    });
+    it("returns 1 for identical sets", () => {
+        expect(jaccard(new Set(["a", "b"]), new Set(["a", "b"]))).toBe(1);
+    });
+    it("computes intersection / union", () => {
+        // {a,b,c} ∩ {b,c,d} = {b,c} = 2
+        // {a,b,c} ∪ {b,c,d} = {a,b,c,d} = 4
+        expect(jaccard(new Set(["a", "b", "c"]), new Set(["b", "c", "d"]))).toBe(0.5);
+    });
+});
+describe("clusterSegments", () => {
+    it("groups identical re-takes", () => {
+        const segs = [
+            { start: 0, end: 3, text: "Hello everyone, welcome to the show today" },
+            { start: 5, end: 7, text: "this is just other content here" },
+            { start: 10, end: 13, text: "Hello everyone, welcome to the show" },
+            { start: 15, end: 18, text: "Hello everyone! Welcome to today's show" },
+        ];
+        const clusters = clusterSegments(segs, { threshold: 0.5 });
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].memberIndexes).toEqual([0, 2, 3]);
+        expect(clusters[0].members[0].start).toBe(0);
+    });
+    it("excludes singletons by default", () => {
+        const segs = [
+            { start: 0, end: 1, text: "First unique segment about apples" },
+            { start: 2, end: 3, text: "Second different topic about cars" },
+        ];
+        expect(clusterSegments(segs)).toHaveLength(0);
+    });
+    it("includes singletons when requested", () => {
+        const segs = [
+            { start: 0, end: 1, text: "First unique segment about apples" },
+            { start: 2, end: 3, text: "Second different topic about cars" },
+        ];
+        const r = clusterSegments(segs, { includeSingletons: true });
+        expect(r.length).toBeGreaterThanOrEqual(2);
+    });
+    it("respects the comparison window", () => {
+        const segs = [
+            { start: 0, end: 1, text: "the unique alpha beta gamma delta marker phrase" },
+            // Use distinct fillers so adjacent fillers don't cluster with each other.
+            // Each pulls from a long pool of unique words.
+            ...Array.from({ length: 200 }, (_, i) => ({
+                start: 2 + i,
+                end: 3 + i,
+                text: `unrelated${i} discussion${i} subject${i} other${i} different${i}`,
+            })),
+            { start: 300, end: 301, text: "the unique alpha beta gamma delta marker phrase" },
+        ];
+        // With window=10, the two matching takes can't link (too far apart).
+        const r = clusterSegments(segs, { window: 10, threshold: 0.5 });
+        expect(r.find((c) => c.memberIndexes.includes(0) && c.memberIndexes.includes(201))).toBeUndefined();
+        // With window=300+, they link.
+        const r2 = clusterSegments(segs, { window: 500, threshold: 0.5 });
+        const matchingCluster = r2.find((c) => c.memberIndexes.includes(0) && c.memberIndexes.includes(201));
+        expect(matchingCluster).toBeDefined();
+    });
+    it("skips segments below minTokens threshold", () => {
+        const segs = [
+            { start: 0, end: 1, text: "yes" },
+            { start: 2, end: 3, text: "yes" },
+            { start: 4, end: 5, text: "yes" },
+        ];
+        expect(clusterSegments(segs, { minTokens: 4 })).toHaveLength(0);
+    });
+    it("sorts clusters temporally", () => {
+        const segs = [
+            { start: 0, end: 1, text: "alpha beta gamma delta first cluster phrase" },
+            { start: 2, end: 3, text: "epsilon zeta eta theta second different group" },
+            { start: 4, end: 5, text: "alpha beta gamma delta first cluster phrase" },
+            { start: 6, end: 7, text: "epsilon zeta eta theta second different group" },
+        ];
+        const r = clusterSegments(segs, { threshold: 0.5 });
+        expect(r).toHaveLength(2);
+        expect(r[0].memberIndexes).toEqual([0, 2]); // first temporally
+        expect(r[1].memberIndexes).toEqual([1, 3]);
+        expect(r[0].id).toBe(1);
+        expect(r[1].id).toBe(2);
+    });
+});
+//# sourceMappingURL=clustering.test.js.map

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

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

package/dist/core/color-match.d.ts

@@ -0,0 +1,19 @@
+export interface CdlValues {
+    slope: [number, number, number];
+    offset: [number, number, number];
+    power: [number, number, number];
+    saturation: number;
+    /** Confidence 0-1; below 0.4 means "I'm guessing". */
+    confidence: number;
+    /** One-line rationale (≤120 chars). */
+    why: string;
+}
+export interface ColorMatchOptions {
+    apiKey?: string;
+    model?: string;
+    detail?: "low" | "high";
+    signal?: AbortSignal;
+}
+export declare function deriveColorMatch(referenceFramePath: string, targetFramePath: string, opts?: ColorMatchOptions): Promise<CdlValues>;
+export declare function parseColorMatchResponse(content: string): CdlValues;
+//# sourceMappingURL=color-match.d.ts.map

package/dist/core/color-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-match.d.ts","sourceRoot":"","sources":["../../src/core/color-match.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA4BD,wBAAsB,gBAAgB,CACpC,kBAAkB,EAAE,MAAM,EAC1B,eAAe,EAAE,MAAM,EACvB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,SAAS,CAAC,CAoDpB;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAelE"}

package/dist/core/color-match.js

@@ -0,0 +1,118 @@
+/**
+ * Vision-derived CDL: ask GPT-4o to compare a reference frame to a target
+ * frame and emit slope/offset/power/saturation deltas to bring the target
+ * toward the reference.
+ *
+ * NOT a substitute for ColorChecker-based matching — that's deterministic.
+ * This is a "look match" useful when shots are similar but feel off (white
+ * balance drift, exposure mismatch, slightly different skin tones).
+ *
+ * Returns CDL values centred around neutral (slope/power=1, offset=0, sat=1)
+ * so the agent can feed them straight into set_primary_correction.
+ */
+import { readFileSync } from "node:fs";
+const SYSTEM = `You match the COLOR LOOK of a target frame to a reference frame.
+
+Output a JSON object with these EXACT keys (no extras, no prose):
+{
+  "slope":  [r, g, b],
+  "offset": [r, g, b],
+  "power":  [r, g, b],
+  "saturation": <number>,
+  "confidence": <0..1>,
+  "why": "<≤120 char rationale>"
+}
+
+Neutral (no change) values:
+  slope = [1, 1, 1]
+  offset = [0, 0, 0]
+  power = [1, 1, 1]
+  saturation = 1
+
+Conventions:
+  - slope is gain per channel (multiplier). 1.05 = 5% brighter on that channel.
+  - offset is a small additive lift, ±0.1 typical, ±0.3 max.
+  - power is gamma per channel. >1 darkens midtones.
+  - saturation: 0.5..1.5 typical range.
+
+Stay subtle. The CDL will be applied additively to whatever grade is already on the target — don't try to do everything in one node. If the two frames look indistinguishable, return neutral values + low confidence.`;
+export async function deriveColorMatch(referenceFramePath, targetFramePath, opts = {}) {
+    const apiKey = opts.apiKey ?? process.env.OPENAI_API_KEY;
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for color_match.");
+    const refB64 = readFileSync(referenceFramePath).toString("base64");
+    const tgtB64 = readFileSync(targetFramePath).toString("base64");
+    const detail = opts.detail ?? "low";
+    const model = opts.model ?? "gpt-4o-mini";
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: SYSTEM },
+            {
+                role: "user",
+                content: [
+                    { type: "text", text: "REFERENCE (the look you want):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${refB64}`, detail },
+                    },
+                    { type: "text", text: "TARGET (needs to match the reference):" },
+                    {
+                        type: "image_url",
+                        image_url: { url: `data:image/jpeg;base64,${tgtB64}`, detail },
+                    },
+                ],
+            },
+        ],
+        response_format: { type: "json_object" },
+        temperature: 0,
+    };
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`OpenAI HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices[0]?.message?.content;
+    if (!content)
+        throw new Error("color_match: empty model response");
+    return parseColorMatchResponse(content);
+}
+export function parseColorMatchResponse(content) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start) {
+        throw new Error("color_match: no JSON object in response");
+    }
+    const parsed = JSON.parse(content.slice(start, end + 1));
+    return {
+        slope: triple(parsed.slope, [1, 1, 1]),
+        offset: triple(parsed.offset, [0, 0, 0]),
+        power: triple(parsed.power, [1, 1, 1]),
+        saturation: clamp(num(parsed.saturation, 1), 0, 4),
+        confidence: clamp(num(parsed.confidence, 0), 0, 1),
+        why: String(parsed.why ?? "").slice(0, 200),
+    };
+}
+function triple(v, fallback) {
+    if (Array.isArray(v) && v.length === 3) {
+        return [num(v[0], fallback[0]), num(v[1], fallback[1]), num(v[2], fallback[2])];
+    }
+    return fallback;
+}
+function num(v, fallback) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : fallback;
+}
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+//# sourceMappingURL=color-match.js.map

package/dist/core/color-match.js.map

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

package/dist/core/color-match.test.d.ts

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

package/dist/core/color-match.test.d.ts.map

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

package/dist/core/color-match.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { parseColorMatchResponse } from "./color-match.js";
+describe("parseColorMatchResponse", () => {
+    it("parses a well-formed CDL JSON object", () => {
+        const r = parseColorMatchResponse('{"slope":[1.05,1.0,0.95],"offset":[0,0,0.02],"power":[1,1,1],"saturation":1.05,"confidence":0.7,"why":"warm shift"}');
+        expect(r.slope).toEqual([1.05, 1.0, 0.95]);
+        expect(r.offset).toEqual([0, 0, 0.02]);
+        expect(r.saturation).toBe(1.05);
+        expect(r.confidence).toBe(0.7);
+        expect(r.why).toBe("warm shift");
+    });
+    it("falls back to neutral on missing fields", () => {
+        const r = parseColorMatchResponse('{"confidence":0.9}');
+        expect(r.slope).toEqual([1, 1, 1]);
+        expect(r.offset).toEqual([0, 0, 0]);
+        expect(r.power).toEqual([1, 1, 1]);
+        expect(r.saturation).toBe(1);
+        expect(r.confidence).toBe(0.9);
+    });
+    it("clamps saturation and confidence to sane ranges", () => {
+        const r = parseColorMatchResponse('{"saturation":99,"confidence":2}');
+        expect(r.saturation).toBe(4);
+        expect(r.confidence).toBe(1);
+    });
+    it("survives prose wrapping around the JSON", () => {
+        const r = parseColorMatchResponse('Here is the result:\n{"saturation":1.1,"confidence":0.5}\nThanks');
+        expect(r.saturation).toBe(1.1);
+        expect(r.confidence).toBe(0.5);
+    });
+    it("throws on totally absent JSON", () => {
+        expect(() => parseColorMatchResponse("no json at all")).toThrow(/no JSON/);
+    });
+    it("rejects non-array slope/offset/power gracefully", () => {
+        const r = parseColorMatchResponse('{"slope":"not-an-array","offset":[1,2]}');
+        expect(r.slope).toEqual([1, 1, 1]);
+        // offset is wrong length → fallback
+        expect(r.offset).toEqual([0, 0, 0]);
+    });
+});
+//# sourceMappingURL=color-match.test.js.map

package/dist/core/color-match.test.js.map

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

package/dist/core/ducking.d.ts

@@ -0,0 +1,37 @@
+export interface DuckingOptions {
+    /**
+     * Sidechain threshold (linear amplitude, 0-1). When the voice exceeds
+     * this, the compressor clamps the music. Default 0.02 — matches typical
+     * dialogue average energy. Real-world podcast implementations cluster at
+     * 0.012–0.03; below 0.02 even quiet voice triggers ducking, above 0.05
+     * quiet conversation won't duck the music at all.
+     */
+    threshold?: number;
+    /** Compression ratio. Default 8. */
+    ratio?: number;
+    /** Attack time in ms. Default 5. */
+    attackMs?: number;
+    /** Release time in ms. Default 250. */
+    releaseMs?: number;
+    /** Voice gain in linear amplitude. Default 1 (unchanged). */
+    voiceGain?: number;
+    /** Background gain (post-duck) in linear amplitude. Default 1. */
+    bgGain?: number;
+    signal?: AbortSignal;
+}
+export interface DuckingResult {
+    output: string;
+    filterGraph: string;
+}
+/**
+ * Render a voice + background mix with the background ducked underneath the
+ * voice. Both inputs may be audio or video files; the output is whatever
+ * extension you give it (PCM .wav for max quality, .m4a/.aac for size).
+ */
+export declare function duckAudio(voicePath: string, bgPath: string, outputPath: string, opts?: DuckingOptions): Promise<DuckingResult>;
+/**
+ * Pure builder for the sidechain filter graph. Exposed so tests can verify
+ * the chain without spawning ffmpeg.
+ */
+export declare function buildDuckingFilter(opts?: DuckingOptions): string;
+//# sourceMappingURL=ducking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ducking.d.ts","sourceRoot":"","sources":["../../src/core/ducking.ts"],"names":[],"mappings":"AAsBA,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CAoBxB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,cAAmB,GAAG,MAAM,CAepE"}

package/dist/core/ducking.js

@@ -0,0 +1,71 @@
+/**
+ * Sidechain audio ducking via ffmpeg.
+ *
+ * Two inputs:
+ *   - voice (or any "key" track that should be heard)
+ *   - background (music / ambient)
+ *
+ * The voice's amplitude controls a compressor on the background, so when the
+ * voice is loud the music gets quieter; when the voice is silent the music
+ * comes back up. Standard podcast/YouTube technique.
+ *
+ * Filter graph:
+ *   [bg][voice] sidechaincompress=threshold=...:ratio=...:attack=...:release=... [ducked]
+ *   [voice][ducked] amix=inputs=2:duration=longest:weights=1 1 [out]
+ *
+ * Output is a single audio file (or video with a re-encoded audio stream when
+ * the voice / bg inputs are videos). v1 mixes voice + ducked-bg; if you want
+ * the voice to ride atop a video timeline, render this as the audio track and
+ * import.
+ */
+import { runFfmpeg } from "./media/ffmpeg.js";
+/**
+ * Render a voice + background mix with the background ducked underneath the
+ * voice. Both inputs may be audio or video files; the output is whatever
+ * extension you give it (PCM .wav for max quality, .m4a/.aac for size).
+ */
+export async function duckAudio(voicePath, bgPath, outputPath, opts = {}) {
+    const filterGraph = buildDuckingFilter(opts);
+    const isWav = /\.wav$/i.test(outputPath);
+    const args = [
+        "-i",
+        voicePath,
+        "-i",
+        bgPath,
+        "-filter_complex",
+        filterGraph,
+        "-map",
+        "[out]",
+        ...(isWav ? ["-c:a", "pcm_s16le"] : ["-c:a", "aac", "-b:a", "192k"]),
+        outputPath,
+    ];
+    const r = await runFfmpeg(args, { signal: opts.signal });
+    if (r.code !== 0) {
+        throw new Error(`ffmpeg duckAudio exited ${r.code}: ${tail(r.stderr)}`);
+    }
+    return { output: outputPath, filterGraph };
+}
+/**
+ * Pure builder for the sidechain filter graph. Exposed so tests can verify
+ * the chain without spawning ffmpeg.
+ */
+export function buildDuckingFilter(opts = {}) {
+    const threshold = opts.threshold ?? 0.02;
+    const ratio = opts.ratio ?? 8;
+    const attackMs = opts.attackMs ?? 5;
+    const releaseMs = opts.releaseMs ?? 250;
+    const voiceGain = opts.voiceGain ?? 1;
+    const bgGain = opts.bgGain ?? 1;
+    // 0 = voice, 1 = bg. Sidechain expects [main][key].
+    return [
+        `[1:a]volume=${bgGain}[bgRaw]`,
+        `[0:a]volume=${voiceGain}[voiceMain]`,
+        `[voiceMain]asplit=2[voiceOut][voiceKey]`,
+        `[bgRaw][voiceKey]sidechaincompress=threshold=${threshold}:ratio=${ratio}:attack=${attackMs}:release=${releaseMs}[ducked]`,
+        `[voiceOut][ducked]amix=inputs=2:duration=longest:dropout_transition=0:weights=1 1[out]`,
+    ].join(";");
+}
+function tail(s) {
+    return s.split("\n").filter(Boolean).slice(-3).join(" | ").slice(-300);
+}
+//# sourceMappingURL=ducking.js.map

package/dist/core/ducking.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ducking.js","sourceRoot":"","sources":["../../src/core/ducking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AA6B9C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,SAAiB,EACjB,MAAc,EACd,UAAkB,EAClB,OAAuB,EAAE;IAEzB,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG;QACX,IAAI;QACJ,SAAS;QACT,IAAI;QACJ,MAAM;QACN,iBAAiB;QACjB,WAAW;QACX,MAAM;QACN,OAAO;QACP,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACpE,UAAU;KACX,CAAC;IACF,MAAM,CAAC,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAuB,EAAE;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,oDAAoD;IACpD,OAAO;QACL,eAAe,MAAM,SAAS;QAC9B,eAAe,SAAS,aAAa;QACrC,yCAAyC;QACzC,gDAAgD,SAAS,UAAU,KAAK,WAAW,QAAQ,YAAY,SAAS,UAAU;QAC1H,wFAAwF;KACzF,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC;AAED,SAAS,IAAI,CAAC,CAAS;IACrB,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC;AACzE,CAAC"}

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

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

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

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

package/dist/core/ducking.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { buildDuckingFilter } from "./ducking.js";
+describe("buildDuckingFilter", () => {
+    it("uses default threshold/ratio/attack/release", () => {
+        const f = buildDuckingFilter();
+        expect(f).toContain("threshold=0.02");
+        expect(f).toContain("ratio=8");
+        expect(f).toContain("attack=5");
+        expect(f).toContain("release=250");
+    });
+    it("respects overrides", () => {
+        const f = buildDuckingFilter({
+            threshold: 0.02,
+            ratio: 12,
+            attackMs: 1,
+            releaseMs: 400,
+        });
+        expect(f).toContain("threshold=0.02");
+        expect(f).toContain("ratio=12");
+        expect(f).toContain("attack=1");
+        expect(f).toContain("release=400");
+    });
+    it("splits the voice into output + sidechain key", () => {
+        const f = buildDuckingFilter();
+        expect(f).toContain("asplit=2[voiceOut][voiceKey]");
+    });
+    it("mixes voice + ducked bg into [out]", () => {
+        const f = buildDuckingFilter();
+        expect(f).toContain("[voiceOut][ducked]amix");
+        expect(f).toMatch(/\[out\]$/);
+    });
+    it("applies bg + voice gain controls", () => {
+        const f = buildDuckingFilter({ voiceGain: 1.2, bgGain: 0.3 });
+        expect(f).toContain("[1:a]volume=0.3");
+        expect(f).toContain("[0:a]volume=1.2");
+    });
+});
+//# sourceMappingURL=ducking.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ducking.test.js","sourceRoot":"","sources":["../../src/core/ducking.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,CAAC,GAAG,kBAAkB,EAAE,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QACtC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC5B,MAAM,CAAC,GAAG,kBAAkB,CAAC;YAC3B,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,EAAE;YACT,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,GAAG;SACf,CAAC,CAAC;QACH,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;QACtC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAChC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,CAAC,GAAG,kBAAkB,EAAE,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,8BAA8B,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,GAAG,kBAAkB,EAAE,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC;QAC9C,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,GAAG,kBAAkB,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC9D,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QACvC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/core/edl-roundtrip.test.d.ts

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

package/dist/core/edl-roundtrip.test.d.ts.map

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