@maravilla-labs/frames 0.5.1 → 0.8.0

package/README.md

@@ -186,11 +186,65 @@ doesn't block it.
 <video class="intro" src="/clips/intro.mp4" preload="auto" muted playsinline></video>
 ```
 
-If the same composition will be rendered to a final video by the
-Maravilla runtime, the audio track of the embedded `<video>` is not
-captured (browsers don't expose decoded audio to the rendering API).
-Use the `audio` option on `FRAMES.render(...)` to mix a soundtrack
-into the final output instead.
+The audio track of an embedded `<video>` is not captured (browsers
+don't expose decoded audio to the rendering API). Add a `kind: "audio"`
+instruction (below) instead — or, for a single pre-mixed soundtrack, the
+`audio` option on `FRAMES.render(...)`.
+
+## Audio
+
+Declare time-bound audio tracks right in the timeline. They are mixed
+into the final video by the renderer (multi-track ffmpeg, server-side)
+and played in the browser preview by a built-in Web Audio engine — so
+preview matches render.
+
+```ts
+defineTimeline({
+  duration: 12000,
+  instructions: [
+    // Background music bed for the whole piece.
+    { kind: "audio", at: 0, duration: 12000, role: "music",
+      src: "/audio/bed.m4a", key: "audio/bed.m4a", fadeIn: 400, fadeOut: 800 },
+    // A voiceover from 3s; music automatically ducks beneath it.
+    { kind: "audio", at: 3000, role: "voiceover",
+      src: "/audio/vo.m4a", key: "audio/vo.m4a" },
+  ],
+});
+```
+
+Fields: `at` / `duration` / `seek` (ms, like video); `src` — a URL the
+browser preview fetches + decodes; `key` — the storage key the renderer
+stages to mix (omit for preview-only tracks); `role` —
+`"voiceover" | "music" | "sfx"` (default `"music"`); `gain` (linear,
+default 1); `fadeIn` / `fadeOut` (ms); `fadeInCurve` / `fadeOutCurve`
+(see below); `duck` — whether a music bed dips under voiceover (default
+`true` for `role: "music"`).
+
+**Fade curves.** A fade has a shape as well as a length. The names map
+to ffmpeg's own `afade` curves, and the preview evaluates the same
+formulas, so a fade sounds identical in the editor and in the export:
+
+| `fadeInCurve` / `fadeOutCurve` | afade | character |
+|---|---|---|
+| `linear` (default) | `tri` | straight gain ramp; dips in loudness mid-fade |
+| `equal-power` | `qsin` | constant perceived loudness (−3 dB at the midpoint) |
+| `s-curve` | `hsin` | gentle at both ends, quick through the middle |
+| `exponential` | `exp` | slow start, fast finish (100 dB range) |
+| `logarithmic` | `log` | fast start, slow finish |
+
+`fadeGain(curve, x)` returns a fade-in's gain at progress `x` (a fade-out
+is `fadeGain(curve, 1 - p)`), for drawing an envelope in your own UI;
+`FADE_CURVES` lists the names in picker order.
+
+**Ducking** is a static envelope computed from the voiceover clips'
+positions (not their loudness), so it's deterministic and the preview
+reproduces the exact dip the export bakes in.
+
+**Preview transport.** Scrubbing via `applyState(t)` stays silent (like
+any NLE); audio is heard during continuous playback. Drive it from your
+player with `window.__mvFrames.playAudio(fromMs)` /
+`stopAudio()` / `setAudioMuted(muted)`. The renderer reads the tracks it
+mixes from `window.__mvFrames.audio`.
 
 ## Bring your own animation library
 

package/dist/audio.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Browser-side audio preview for a frames timeline.
+ *
+ * The render worker mixes audio with ffmpeg (the browser can't expose
+ * decoded audio to the capture pipeline), so this engine exists purely so
+ * the **editor / preview** plays the same mix the final video will have:
+ * multiple time-bound tracks (voiceover, background music, sfx), per-track
+ * gain + fades, and static-envelope ducking of music under voiceover (see
+ * [`ducking.ts`] — the exact curve the worker bakes in).
+ *
+ * Scrubbing (`applyState(t)`) stays silent by design — like every real NLE,
+ * audio is heard only during continuous playback. The preview host calls
+ * [`AudioEngine.playFrom`] on play and [`AudioEngine.stop`] on pause.
+ */
+import { type DuckParams } from "./ducking.js";
+import { type FadeCurve } from "./fades.js";
+/** A timeline audio track, resolved for browser playback. Times in ms. */
+export type PreviewAudioTrack = {
+    /** Playable URL fetched + decoded for preview. */
+    src: string;
+    /** Timeline start, ms. */
+    at: number;
+    /** Play length on the timeline, ms. `null` = natural clip length. */
+    duration: number | null;
+    /** Start offset within the source, ms. */
+    seek: number;
+    /** Linear base gain (1 = unity). */
+    gain: number;
+    /** Fade-in / fade-out, ms. */
+    fadeIn: number;
+    fadeOut: number;
+    /** Shape of each fade (see `fades.ts`). Default `linear`. */
+    fadeInCurve?: FadeCurve;
+    fadeOutCurve?: FadeCurve;
+    /** "voiceover" drives ducking; "music" gets ducked when `duck`. */
+    role: "voiceover" | "music" | "sfx";
+    /** Whether this (music) track dips under voiceover. */
+    duck: boolean;
+    /** Optional per-track effect (structurally matches `AudioEffect`). */
+    effect?: {
+        kind: "radio";
+        drive?: number;
+        tone?: number;
+        depth?: number;
+    };
+};
+export declare class AudioEngine {
+    private tracks;
+    private duck;
+    private ctx;
+    private master;
+    private buffers;
+    private active;
+    private muted;
+    constructor(tracks: PreviewAudioTrack[], duck?: DuckParams);
+    /** Merged voiceover regions (seconds) — what music ducks under. */
+    private voiceoverSegments;
+    /** Fetch + decode every track's source (idempotent, cached by URL). */
+    private ensureBuffers;
+    /** Start (or restart) playback from timeline position `fromMs`. */
+    playFrom(fromMs: number): Promise<void>;
+    /**
+     * Per-track base gain + fade-in on `inGain`, fade-out on `outGain`, each
+     * shaped by its curve. `t0` is the playhead (seconds): a fade the playhead is
+     * already inside continues from where it is rather than restarting.
+     */
+    private applyFades;
+    /** Ducking automation (scaled by the music track's base gain) on `g`. */
+    private applyDuck;
+    /** Stop all currently-playing sources (idempotent). */
+    stop(): void;
+    setMuted(muted: boolean): void;
+}
+/**
+ * Resolved "radio voice" parameters. The exact same formulas are mirrored by
+ * the ffmpeg render (worker `audio_mix.rs`) so preview == export:
+ * a band-pass (high-pass + low-pass) for the radio band, a low-shelf for
+ * "depth", and a tanh waveshaper (pushed by `pre`, tamed by `post`) for drive.
+ */
+export declare function radioParams(effect: {
+    drive?: number;
+    tone?: number;
+    depth?: number;
+}): {
+    hp: number;
+    lp: number;
+    shelfGainDb: number;
+    pre: number;
+    post: number;
+    k: number;
+};
+//# sourceMappingURL=audio.d.ts.map

package/dist/audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio.d.ts","sourceRoot":"","sources":["../src/audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAIL,KAAK,UAAU,EAEhB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5D,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB,mEAAmE;IACnE,IAAI,EAAE,WAAW,GAAG,OAAO,GAAG,KAAK,CAAC;IACpC,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,sEAAsE;IACtE,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E,CAAC;AAcF,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,GAAG,CAA6B;IACxC,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,iBAAiB,EAAE,EAAE,IAAI,GAAE,UAAyB;IAKxE,mEAAmE;IACnE,OAAO,CAAC,iBAAiB;IAWzB,uEAAuE;YACzD,aAAa;IA0B3B,mEAAmE;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6E7C;;;;OAIG;IACH,OAAO,CAAC,UAAU;IA4ClB,yEAAyE;IACzE,OAAO,CAAC,SAAS;IAkBjB,uDAAuD;IACvD,IAAI,IAAI,IAAI;IAWZ,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;CAI/B;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;CACX,CAYA"}

package/dist/audio.js

@@ -0,0 +1,282 @@
+/**
+ * Browser-side audio preview for a frames timeline.
+ *
+ * The render worker mixes audio with ffmpeg (the browser can't expose
+ * decoded audio to the capture pipeline), so this engine exists purely so
+ * the **editor / preview** plays the same mix the final video will have:
+ * multiple time-bound tracks (voiceover, background music, sfx), per-track
+ * gain + fades, and static-envelope ducking of music under voiceover (see
+ * [`ducking.ts`] — the exact curve the worker bakes in).
+ *
+ * Scrubbing (`applyState(t)`) stays silent by design — like every real NLE,
+ * audio is heard only during continuous playback. The preview host calls
+ * [`AudioEngine.playFrom`] on play and [`AudioEngine.stop`] on pause.
+ */
+import { DEFAULT_DUCK, duckAutomation, mergeSegments, } from "./ducking.js";
+import { fadeAutomation } from "./fades.js";
+function getAudioContextCtor() {
+    if (typeof window === "undefined")
+        return null;
+    return (window.AudioContext ||
+        window
+            .webkitAudioContext ||
+        null);
+}
+export class AudioEngine {
+    tracks;
+    duck;
+    ctx = null;
+    master = null;
+    buffers = new Map();
+    active = [];
+    muted = false;
+    constructor(tracks, duck = DEFAULT_DUCK) {
+        this.tracks = tracks;
+        this.duck = duck;
+    }
+    /** Merged voiceover regions (seconds) — what music ducks under. */
+    voiceoverSegments() {
+        const segs = this.tracks
+            .filter((t) => t.role === "voiceover")
+            .map((t) => ({
+            start: t.at / 1000,
+            end: (t.at + (t.duration ?? 0)) / 1000,
+        }))
+            .filter((s) => s.end > s.start);
+        return mergeSegments(segs);
+    }
+    /** Fetch + decode every track's source (idempotent, cached by URL). */
+    async ensureBuffers() {
+        const Ctor = getAudioContextCtor();
+        if (!Ctor)
+            return;
+        if (!this.ctx) {
+            this.ctx = new Ctor();
+            this.master = this.ctx.createGain();
+            this.master.connect(this.ctx.destination);
+        }
+        const ctx = this.ctx;
+        await Promise.all(this.tracks.map(async (t) => {
+            if (this.buffers.has(t.src))
+                return;
+            try {
+                const resp = await fetch(t.src);
+                const raw = await resp.arrayBuffer();
+                const buf = await ctx.decodeAudioData(raw);
+                this.buffers.set(t.src, buf);
+            }
+            catch (err) {
+                // A bad/missing audio URL must never wedge the preview — skip it.
+                // eslint-disable-next-line no-console
+                console.warn(`[@maravilla-labs/frames] audio decode failed for ${t.src}:`, err);
+            }
+        }));
+    }
+    /** Start (or restart) playback from timeline position `fromMs`. */
+    async playFrom(fromMs) {
+        await this.ensureBuffers();
+        if (!this.ctx || !this.master)
+            return;
+        this.stop();
+        // Resume may reject if there's no user activation (autoplay policy). Don't
+        // let that abort scheduling — the caller invokes this from a click handler,
+        // so activation is usually present; if not, the context stays suspended and
+        // simply produces no sound rather than throwing.
+        if (this.ctx.state === "suspended") {
+            try {
+                await this.ctx.resume();
+            }
+            catch {
+                /* no user activation yet — stay silent, don't throw */
+            }
+        }
+        const ctx = this.ctx;
+        const t0 = fromMs / 1000;
+        const startCtx = ctx.currentTime + 0.05; // small lead so scheduling lands
+        const segments = this.voiceoverSegments();
+        this.master.gain.value = this.muted ? 0 : 1;
+        for (const track of this.tracks) {
+            const buf = this.buffers.get(track.src);
+            if (!buf)
+                continue;
+            const naturalMs = buf.duration * 1000 - track.seek;
+            const durMs = track.duration ?? Math.max(0, naturalMs);
+            const trackEnd = track.at + durMs;
+            if (t0 * 1000 >= trackEnd)
+                continue; // already past this clip
+            // When (timeline ms) the clip actually begins sounding from the playhead.
+            const playStart = Math.max(t0 * 1000, track.at);
+            const delaySec = (playStart - t0 * 1000) / 1000;
+            const offsetInClip = (track.seek + (playStart - track.at)) / 1000;
+            const remainingSec = (trackEnd - playStart) / 1000;
+            if (remainingSec <= 0)
+                continue;
+            // Map a timeline time (seconds) to this AudioContext's clock.
+            const toCtx = (timelineSec) => Math.max(startCtx, startCtx + (timelineSec - t0));
+            // Two gains, in series: the fade-in and the fade-out are separate
+            // automations that MULTIPLY where they overlap — the same as ffmpeg's two
+            // chained `afade` filters, and it keeps each curve's events on its own
+            // AudioParam so they can never collide.
+            const fadeGain = ctx.createGain();
+            const fadeOutGain = ctx.createGain();
+            fadeGain.connect(fadeOutGain);
+            this.applyFades(fadeGain, fadeOutGain, track, t0, toCtx);
+            let tail = fadeOutGain;
+            if (track.role === "music" && track.duck && segments.length) {
+                const duckGain = ctx.createGain();
+                this.applyDuck(duckGain, track.gain, segments, toCtx);
+                fadeOutGain.connect(duckGain);
+                tail = duckGain;
+            }
+            tail.connect(this.master);
+            // Optional effect (e.g. radio voice) sits between the source and the
+            // fade/duck gains, so it shapes the dry signal exactly like the ffmpeg
+            // render does.
+            const node = ctx.createBufferSource();
+            node.buffer = buf;
+            const radio = track.effect?.kind === "radio" ? buildRadioChain(ctx, track.effect) : null;
+            if (radio) {
+                node.connect(radio.input);
+                radio.output.connect(fadeGain);
+            }
+            else {
+                node.connect(fadeGain);
+            }
+            node.start(startCtx + delaySec, offsetInClip, remainingSec);
+            this.active.push(node);
+        }
+    }
+    /**
+     * Per-track base gain + fade-in on `inGain`, fade-out on `outGain`, each
+     * shaped by its curve. `t0` is the playhead (seconds): a fade the playhead is
+     * already inside continues from where it is rather than restarting.
+     */
+    applyFades(inGain, outGain, track, t0, toCtx) {
+        const base = track.role === "music" && track.duck ? 1 : track.gain;
+        const startSec = track.at / 1000;
+        const durMs = track.duration ?? 0;
+        const endSec = (track.at + durMs) / 1000;
+        const fadeInSec = Math.max(0, track.fadeIn) / 1000;
+        const fadeOutSec = Math.max(0, track.fadeOut) / 1000;
+        const inCurve = track.fadeInCurve ?? "linear";
+        const outCurve = track.fadeOutCurve ?? "linear";
+        // Fade-in (carries the base gain).
+        if (fadeInSec > 0) {
+            const inEnd = startSec + fadeInSec;
+            if (t0 >= inEnd) {
+                inGain.gain.setValueAtTime(base, toCtx(t0));
+            }
+            else {
+                const from = Math.max(0, (t0 - startSec) / fadeInSec);
+                const at = Math.max(startSec, t0);
+                // A value event AT the curve's start time counts as an overlap and
+                // throws — hold silence only when the clip starts later than the playhead.
+                if (at > t0)
+                    inGain.gain.setValueAtTime(0, toCtx(t0));
+                inGain.gain.setValueCurveAtTime(fadeAutomation(inCurve, "in", base, from), toCtx(at), inEnd - at);
+            }
+        }
+        else {
+            inGain.gain.setValueAtTime(base, toCtx(t0));
+        }
+        // Fade-out (unity outside the fade).
+        const outStart = Math.max(startSec, endSec - fadeOutSec);
+        const hasOut = fadeOutSec > 0 && durMs > 0 && endSec > outStart && t0 < endSec;
+        const outAt = Math.max(outStart, t0);
+        if (!hasOut || outAt > t0)
+            outGain.gain.setValueAtTime(1, toCtx(t0));
+        if (hasOut) {
+            const from = Math.max(0, (t0 - outStart) / (endSec - outStart));
+            outGain.gain.setValueCurveAtTime(fadeAutomation(outCurve, "out", 1, from), toCtx(outAt), endSec - outAt);
+        }
+    }
+    /** Ducking automation (scaled by the music track's base gain) on `g`. */
+    applyDuck(g, base, segments, toCtx) {
+        const points = duckAutomation(segments, base, this.duck);
+        let first = true;
+        for (const [timeSec, value] of points) {
+            if (first) {
+                g.gain.setValueAtTime(value, toCtx(timeSec));
+                first = false;
+            }
+            else {
+                g.gain.linearRampToValueAtTime(value, toCtx(timeSec));
+            }
+        }
+    }
+    /** Stop all currently-playing sources (idempotent). */
+    stop() {
+        for (const node of this.active) {
+            try {
+                node.stop();
+            }
+            catch {
+                /* already stopped */
+            }
+        }
+        this.active = [];
+    }
+    setMuted(muted) {
+        this.muted = muted;
+        if (this.master)
+            this.master.gain.value = muted ? 0 : 1;
+    }
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/**
+ * Resolved "radio voice" parameters. The exact same formulas are mirrored by
+ * the ffmpeg render (worker `audio_mix.rs`) so preview == export:
+ * a band-pass (high-pass + low-pass) for the radio band, a low-shelf for
+ * "depth", and a tanh waveshaper (pushed by `pre`, tamed by `post`) for drive.
+ */
+export function radioParams(effect) {
+    const drive = clamp01(effect.drive ?? 0.4);
+    const tone = clamp01(effect.tone ?? 0.4);
+    const depth = clamp01(effect.depth ?? 0.5);
+    return {
+        hp: 500 - 350 * tone, // 500Hz (telephone) → 150Hz (open)
+        lp: 2400 + 2800 * tone, // 2400Hz (narrow) → 5200Hz (bright)
+        shelfGainDb: depth * 12, // up to +12 dB low-shelf
+        pre: 1 + drive * 3, // drive into the saturator
+        post: 1 / (1 + drive * 1.6), // make-up / tame
+        k: 1 + drive * 5, // tanh steepness
+    };
+}
+function tanhCurve(k) {
+    const n = 1024;
+    const curve = new Float32Array(n);
+    for (let i = 0; i < n; i++) {
+        const x = (i / (n - 1)) * 2 - 1;
+        curve[i] = Math.tanh(k * x);
+    }
+    return curve;
+}
+function buildRadioChain(ctx, effect) {
+    const p = radioParams(effect);
+    const hp = ctx.createBiquadFilter();
+    hp.type = "highpass";
+    hp.frequency.value = p.hp;
+    const lp = ctx.createBiquadFilter();
+    lp.type = "lowpass";
+    lp.frequency.value = p.lp;
+    const shelf = ctx.createBiquadFilter();
+    shelf.type = "lowshelf";
+    shelf.frequency.value = 180;
+    shelf.gain.value = p.shelfGainDb;
+    const pre = ctx.createGain();
+    pre.gain.value = p.pre;
+    const shaper = ctx.createWaveShaper();
+    shaper.curve = tanhCurve(p.k);
+    shaper.oversample = "2x";
+    const post = ctx.createGain();
+    post.gain.value = p.post;
+    hp.connect(lp);
+    lp.connect(shelf);
+    shelf.connect(pre);
+    pre.connect(shaper);
+    shaper.connect(post);
+    return { input: hp, output: post };
+}
+//# sourceMappingURL=audio.js.map

package/dist/audio.js.map

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

package/dist/ducking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Static-envelope ducking — the single source of truth for "music dips
+ * under voiceover" shared by the browser preview ([`audio.ts`]) and the
+ * Rust render worker (which mirrors this math when it builds the ffmpeg
+ * `volume` expression).
+ *
+ * The model is deliberately *static*: the dip is computed purely from the
+ * voiceover clips' timeline positions (`at` / `duration`), NOT from the
+ * voiceover's actual loudness. That makes it deterministic — the same
+ * timeline produces the same envelope every render — and, crucially, lets
+ * the browser preview reproduce the exact gain curve the final mp4 will
+ * have (a sidechain compressor could not be mirrored frame-for-frame in
+ * Web Audio).
+ *
+ * All times here are in **seconds** (Web Audio + ffmpeg both want seconds);
+ * the DSL stores milliseconds, so callers convert at the boundary.
+ */
+/** Tunable ducking parameters. Defaults match the shorts editor. */
+export type DuckParams = {
+    /** Music multiplier while voiceover is active. `0.25` ≈ −12 dB. */
+    level: number;
+    /** Linear ramp into / out of the dip, seconds. */
+    ramp: number;
+};
+export declare const DEFAULT_DUCK: DuckParams;
+/** A half-open `[start, end)` interval on the timeline, seconds. */
+export type Segment = {
+    start: number;
+    end: number;
+};
+/**
+ * Merge overlapping / touching voiceover segments into a disjoint, sorted
+ * set. Merging is what makes the preview automation and the ffmpeg
+ * expression agree even when voiceover clips overlap: a union of regions
+ * is unambiguous, whereas per-clip ramps could otherwise fight each other.
+ */
+export declare function mergeSegments(segments: Segment[]): Segment[];
+/**
+ * The ducking multiplier at time `t` (seconds) for a music track, given the
+ * merged voiceover `segments`. `1` = full volume, `level` = fully ducked,
+ * with linear ramps of width `ramp` on each edge. Used by the preview to
+ * sample the curve and by tests to assert the Rust expression matches.
+ */
+export declare function duckMultiplier(t: number, segments: Segment[], duck?: DuckParams): number;
+/**
+ * Gain-automation breakpoints `[time, value]` for a music track's
+ * `GainNode`, scaled by `base` gain. The preview replays these with
+ * `setValueAtTime` / `linearRampToValueAtTime` so the dip in the player
+ * matches the dip baked into the render. Times are absolute timeline
+ * seconds.
+ */
+export declare function duckAutomation(segments: Segment[], base: number, duck?: DuckParams): Array<[number, number]>;
+//# sourceMappingURL=ducking.d.ts.map

package/dist/ducking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ducking.d.ts","sourceRoot":"","sources":["../src/ducking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAAG;IACvB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,UAAwC,CAAC;AAEpE,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,CAc5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,GAAE,UAAyB,GAC9B,MAAM,CAOR;AAUD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,OAAO,EAAE,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,UAAyB,GAC9B,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAWzB"}

package/dist/ducking.js

@@ -0,0 +1,85 @@
+/**
+ * Static-envelope ducking — the single source of truth for "music dips
+ * under voiceover" shared by the browser preview ([`audio.ts`]) and the
+ * Rust render worker (which mirrors this math when it builds the ffmpeg
+ * `volume` expression).
+ *
+ * The model is deliberately *static*: the dip is computed purely from the
+ * voiceover clips' timeline positions (`at` / `duration`), NOT from the
+ * voiceover's actual loudness. That makes it deterministic — the same
+ * timeline produces the same envelope every render — and, crucially, lets
+ * the browser preview reproduce the exact gain curve the final mp4 will
+ * have (a sidechain compressor could not be mirrored frame-for-frame in
+ * Web Audio).
+ *
+ * All times here are in **seconds** (Web Audio + ffmpeg both want seconds);
+ * the DSL stores milliseconds, so callers convert at the boundary.
+ */
+export const DEFAULT_DUCK = { level: 0.25, ramp: 0.25 };
+/**
+ * Merge overlapping / touching voiceover segments into a disjoint, sorted
+ * set. Merging is what makes the preview automation and the ffmpeg
+ * expression agree even when voiceover clips overlap: a union of regions
+ * is unambiguous, whereas per-clip ramps could otherwise fight each other.
+ */
+export function mergeSegments(segments) {
+    const sorted = segments
+        .filter((s) => s.end > s.start)
+        .sort((a, b) => a.start - b.start);
+    const out = [];
+    for (const s of sorted) {
+        const last = out[out.length - 1];
+        if (last && s.start <= last.end) {
+            last.end = Math.max(last.end, s.end);
+        }
+        else {
+            out.push({ ...s });
+        }
+    }
+    return out;
+}
+/**
+ * The ducking multiplier at time `t` (seconds) for a music track, given the
+ * merged voiceover `segments`. `1` = full volume, `level` = fully ducked,
+ * with linear ramps of width `ramp` on each edge. Used by the preview to
+ * sample the curve and by tests to assert the Rust expression matches.
+ */
+export function duckMultiplier(t, segments, duck = DEFAULT_DUCK) {
+    let m = 1;
+    for (const { start, end } of segments) {
+        const seg = segMultiplier(t, start, end, duck);
+        if (seg < m)
+            m = seg;
+    }
+    return m;
+}
+function segMultiplier(t, s, e, duck) {
+    const { level: d, ramp: r } = duck;
+    if (t <= s - r || t >= e + r)
+        return 1;
+    if (t < s)
+        return 1 - (1 - d) * (t - (s - r)) / r; // ramp down
+    if (t <= e)
+        return d; // hold
+    return d + (1 - d) * (t - e) / r; // ramp up
+}
+/**
+ * Gain-automation breakpoints `[time, value]` for a music track's
+ * `GainNode`, scaled by `base` gain. The preview replays these with
+ * `setValueAtTime` / `linearRampToValueAtTime` so the dip in the player
+ * matches the dip baked into the render. Times are absolute timeline
+ * seconds.
+ */
+export function duckAutomation(segments, base, duck = DEFAULT_DUCK) {
+    const merged = mergeSegments(segments);
+    const points = [[0, base]];
+    const { level: d, ramp: r } = duck;
+    for (const { start, end } of merged) {
+        points.push([Math.max(0, start - r), base]); // begin ramp down
+        points.push([start, base * d]); // fully ducked
+        points.push([end, base * d]); // hold to clip end
+        points.push([end + r, base]); // ramp back up
+    }
+    return points;
+}
+//# sourceMappingURL=ducking.js.map

package/dist/ducking.js.map

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

package/dist/fades.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fade curves for audio tracks — the shape of a fade-in / fade-out, not just
+ * its length.
+ *
+ * The render worker mixes with ffmpeg's `afade`, so these are ffmpeg's OWN
+ * curve formulas (libavfilter `af_afade.c`, `fade_gain`), evaluated here for the
+ * browser preview. The worker maps each name to the matching `afade` curve
+ * (`audio_mix.rs`, `ffmpeg_fade_curve`), which is what keeps preview == export.
+ *
+ * | name          | afade | shape                                              |
+ * |---------------|-------|----------------------------------------------------|
+ * | `linear`      | tri   | straight gain ramp — a dip in the middle           |
+ * | `equal-power` | qsin  | quarter sine — constant perceived loudness         |
+ * | `s-curve`     | hsin  | half sine — gentle at both ends                     |
+ * | `exponential` | exp   | slow start, fast finish (~-100 dB floor)           |
+ * | `logarithmic` | log   | fast start, slow finish                            |
+ *
+ * `linear` is the default because it is what `afade` does when no curve is
+ * named, so a track written before curves existed renders unchanged.
+ */
+export type FadeCurve = "linear" | "equal-power" | "s-curve" | "exponential" | "logarithmic";
+/** Every curve, in the order a picker should offer them. */
+export declare const FADE_CURVES: readonly FadeCurve[];
+/** Resolve an untrusted value to a known curve (unknown ⇒ `linear`). */
+export declare function resolveFadeCurve(value: unknown): FadeCurve;
+/**
+ * Gain (0..1) of a FADE-IN at progress `x` (0 = start of the fade, 1 = end).
+ * A fade-out at progress `p` is `fadeGain(curve, 1 - p)` — exactly how `afade`
+ * runs its curve backwards for `t=out`.
+ */
+export declare function fadeGain(curve: FadeCurve, x: number): number;
+/**
+ * Sampled gain automation for `AudioParam.setValueCurveAtTime`, scaled by
+ * `base`. `from` lets a curve start part-way through (playback that begins in
+ * the middle of a fade), so the preview never restarts a fade from silence.
+ */
+export declare function fadeAutomation(curve: FadeCurve, direction: "in" | "out", base: number, from?: number, samples?: number): Float32Array;
+//# sourceMappingURL=fades.d.ts.map

package/dist/fades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fades.d.ts","sourceRoot":"","sources":["../src/fades.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAE7F,4DAA4D;AAC5D,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAM3C,CAAC;AAEF,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAI1D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAe5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,IAAI,GAAG,KAAK,EACvB,IAAI,EAAE,MAAM,EACZ,IAAI,SAAI,EACR,OAAO,SAAM,GACZ,YAAY,CAQd"}