@clipkit/runtime 1.0.0

package/dist/assets/mp4-frame-source.js

@@ -0,0 +1,387 @@
+// Worker-compatible, deterministic video frame source.
+//
+// HTMLVideoElement bundles demux + decode + a playback clock — but it
+// doesn't exist in workers, and its seeking is approximate. This class
+// rebuilds the pipeline from parts that DO exist in workers:
+//
+//   fetch(url)  →  mp4box demux (sample table + codec config)
+//               →  VideoDecoder (WebCodecs)
+//               →  getFrame(t) returns the exact VideoFrame for time t
+//
+// Determinism is the point: preview frame N is pixel-identical to
+// exported frame N, because both decode the same sample.
+//
+// Decode model — PIPELINED, not batch-per-seek:
+//   - One persistent decoder. Samples are fed in decode order through a
+//     cursor (`nextFeedIndex`); outputs land in a frame cache keyed by
+//     sample index.
+//   - getFrame(t) keeps the feed cursor FEED_AHEAD samples past the
+//     target, so during linear playback each request feeds ~1 new
+//     sample (amortized one hardware decode per frame — real-time).
+//   - Only a backward seek or a large forward jump resets the decoder
+//     to the target's preceding keyframe. flush() happens only at
+//     end-of-stream.
+//   - Decoded frames behind the playhead are evicted + closed.
+//
+// v1 limits (documented in PARITY-PLAN.md):
+//   - MP4 containers only (mp4box). Other containers fall back to the
+//     host's main-thread pump.
+//   - The whole file is fetched up front. Fine for clip-length assets;
+//     long-form needs ranged fetches + incremental demux.
+import { createFile, DataStream, Endianness } from 'mp4box';
+import { getLogger } from '../logger.js';
+/** Samples kept fed beyond the target — the decode pipeline depth. */
+const FEED_AHEAD = 12;
+/** Cached frames kept behind the target (handles tiny backwards jitter). */
+const CACHE_BEHIND = 2;
+/**
+ * Cached frames kept behind the target while playing BACKWARD
+ * (time_remap reverse). H.264 only decodes forward from a keyframe,
+ * so reverse playback re-decodes a GOP chunk and then serves the next
+ * ~24 descending requests from cache — one GOP decode per chunk
+ * instead of per frame, with memory bounded to the window.
+ */
+const REVERSE_CACHE = 24;
+/** Forward jump (in samples) beyond which we reset to a keyframe instead of decoding through. */
+const FORWARD_RESET_THRESHOLD = 90;
+/** Safety timeout for a single frame request. */
+const FRAME_TIMEOUT_MS = 2000;
+export class Mp4FrameSource {
+    width;
+    height;
+    /** Media duration in seconds. */
+    duration;
+    /** Samples in decode order, with composition times. */
+    samples;
+    /** Indices of keyframes within `samples`, ascending. */
+    keyIndices;
+    /** Decoder-output timestamp → sample index (composition order lookup). */
+    tsToIndex = new Map();
+    config;
+    decoder = null;
+    /** Next sample index (decode order) to feed the decoder. */
+    nextFeedIndex = Number.POSITIVE_INFINITY;
+    /** True after an end-of-stream flush — next decode needs a reset. */
+    flushed = false;
+    /** Decoded frames, keyed by sample index. Evicted + closed as the window moves. */
+    cache = new Map();
+    /** Cache window [lo, hi] — outputs outside it are closed on arrival. */
+    windowLo = 0;
+    windowHi = Number.POSITIVE_INFINITY;
+    /** Previous request's target — direction detection for the window shape. */
+    lastTarget = -1;
+    /** Pending getFrame waiters, keyed by sample index. */
+    waiters = new Map();
+    /** Serializes getFrame calls. */
+    opChain = Promise.resolve();
+    disposed = false;
+    static isSupported() {
+        return typeof VideoDecoder !== 'undefined';
+    }
+    constructor(config, samples, width, height, duration) {
+        this.config = config;
+        this.samples = samples;
+        this.width = width;
+        this.height = height;
+        this.duration = duration;
+        this.keyIndices = [];
+        for (let i = 0; i < samples.length; i++) {
+            if (samples[i].isKey)
+                this.keyIndices.push(i);
+            this.tsToIndex.set(samples[i].chunk.timestamp, i);
+        }
+        if (this.keyIndices.length === 0 || this.keyIndices[0] !== 0) {
+            // Defensive: treat the first sample as a sync point — most
+            // encoders emit a keyframe first; without one we can't decode.
+            this.keyIndices.unshift(0);
+        }
+    }
+    /** Fetch + demux + verify the codec is decodable. Throws on any failure. */
+    static async load(url) {
+        if (!Mp4FrameSource.isSupported()) {
+            throw new Error('WebCodecs VideoDecoder unavailable in this context');
+        }
+        // 10s fetch timeout (mirrors loadImage): a dead video host (e.g. the retired
+        // MDN flower.mp4) otherwise dangles a connection through preload.
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 10000);
+        let response;
+        try {
+            response = await fetch(url, { mode: 'cors', signal: ac.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!response.ok)
+            throw new Error(`fetch failed (${response.status})`);
+        const buffer = (await response.arrayBuffer());
+        buffer.fileStart = 0;
+        const mp4 = createFile();
+        const { info, rawSamples } = await new Promise((resolve, reject) => {
+            const collected = [];
+            let trackInfo = null;
+            mp4.onError = (e) => reject(new Error(`mp4box: ${e}`));
+            mp4.onReady = (i) => {
+                if (i.videoTracks.length === 0) {
+                    reject(new Error('no video track in container'));
+                    return;
+                }
+                trackInfo = i;
+                const track = i.videoTracks[0];
+                mp4.setExtractionOptions(track.id, null, { nbSamples: track.nb_samples });
+                mp4.start();
+            };
+            mp4.onSamples = (_trackId, _user, samples) => {
+                collected.push(...samples);
+                const expected = trackInfo?.videoTracks[0]?.nb_samples ?? Infinity;
+                if (collected.length >= expected) {
+                    resolve({ info: trackInfo, rawSamples: collected });
+                }
+            };
+            mp4.appendBuffer(buffer);
+            mp4.flush();
+        });
+        const track = info.videoTracks[0];
+        const description = extractDescription(mp4, track.id);
+        const config = {
+            codec: track.codec,
+            codedWidth: track.video?.width ?? track.track_width,
+            codedHeight: track.video?.height ?? track.track_height,
+            ...(description ? { description } : {}),
+        };
+        const support = await VideoDecoder.isConfigSupported(config);
+        if (!support.supported) {
+            throw new Error(`codec ${track.codec} not decodable here`);
+        }
+        const samples = rawSamples.map((s) => ({
+            time: s.cts / s.timescale,
+            isKey: s.is_sync,
+            chunk: new EncodedVideoChunk({
+                type: s.is_sync ? 'key' : 'delta',
+                timestamp: Math.round((s.cts / s.timescale) * 1_000_000),
+                duration: Math.round((s.duration / s.timescale) * 1_000_000),
+                data: s.data,
+            }),
+        }));
+        if (samples.length === 0)
+            throw new Error('container has zero video samples');
+        const duration = info.duration / info.timescale;
+        return new Mp4FrameSource(config, samples, config.codedWidth, config.codedHeight, duration > 0 ? duration : samples[samples.length - 1].time);
+    }
+    /**
+     * The decoded frame covering media time `t` (seconds). The RETURNED
+     * FRAME IS OWNED BY THE SOURCE — upload it, don't close it; it's
+     * closed when the cache window moves past it. Returns null after
+     * dispose or on decode failure.
+     */
+    getFrame(t) {
+        const run = this.opChain.then(() => this.#getFrameInner(t));
+        // Keep the chain alive through failures.
+        this.opChain = run.catch(() => undefined);
+        return run;
+    }
+    async #getFrameInner(t) {
+        if (this.disposed)
+            return null;
+        const target = this.#sampleIndexAt(t);
+        const backward = this.lastTarget >= 0 && target < this.lastTarget;
+        this.lastTarget = target;
+        // Move the eviction window and close frames OUTSIDE it — both
+        // sides, or reverse playback (descending targets) would keep every
+        // frame it ever decoded and leak the whole clip as GPU surfaces.
+        // The window keeps a deep tail BEHIND the target when stepping
+        // backward (so descending requests amortize one GOP re-decode
+        // across REVERSE_CACHE cache hits) and a shallow one going forward.
+        const prevWindowLo = this.windowLo;
+        this.windowLo = Math.max(0, target - (backward ? REVERSE_CACHE : CACHE_BEHIND));
+        this.windowHi = Math.min(this.samples.length - 1, target + FEED_AHEAD);
+        for (const [idx, frame] of this.cache) {
+            if (idx < this.windowLo || idx > this.windowHi) {
+                frame.close();
+                this.cache.delete(idx);
+            }
+        }
+        const feedEnd = this.windowHi;
+        const cached = this.cache.get(target);
+        if (cached) {
+            // Keep the pipeline primed for the frames that follow.
+            this.#feedThrough(feedEnd, /*hasWaiter*/ false);
+            return cached;
+        }
+        this.#ensureDecoderFor(target, prevWindowLo);
+        const result = await new Promise((resolve) => {
+            const list = this.waiters.get(target) ?? [];
+            list.push(resolve);
+            this.waiters.set(target, list);
+            this.#feedThrough(feedEnd, /*hasWaiter*/ true);
+            // Safety net: a stuck decoder shouldn't stall produce forever.
+            setTimeout(() => {
+                const pending = this.waiters.get(target);
+                if (pending && pending.includes(resolve)) {
+                    this.waiters.set(target, pending.filter((w) => w !== resolve));
+                    resolve(this.cache.get(target) ?? null);
+                }
+            }, FRAME_TIMEOUT_MS);
+        });
+        return result;
+    }
+    /**
+     * Make sure the decoder exists and its feed cursor can reach
+     * `target`. Reset to the target's preceding keyframe when:
+     *   - there's no usable decoder (never started, errored, or flushed
+     *     at end-of-stream), or
+     *   - the target sits in a region this run already evicted
+     *     (`target < prevWindowLo` — backward seek past the cache), or
+     *   - the feed cursor is already past the target by more than the
+     *     pipeline depth (an uncached target can never emerge from this
+     *     run — without a reset the waiter would just hit its timeout), or
+     *   - the jump forward is large enough that decoding through is more
+     *     work than restarting at the target's keyframe.
+     *
+     * Crucially NOT a reset: target fed but output still pending in the
+     * decoder (the normal in-flight case during playback) — feeding a
+     * few samples ahead makes it emit. Produces are serialized, so at
+     * most one waiter exists and it always belongs to the current call.
+     */
+    #ensureDecoderFor(target, prevWindowLo) {
+        const needsReset = !this.decoder ||
+            this.decoder.state === 'closed' ||
+            this.flushed ||
+            this.nextFeedIndex === Number.POSITIVE_INFINITY ||
+            target < prevWindowLo ||
+            this.nextFeedIndex > target + FEED_AHEAD ||
+            target - this.nextFeedIndex > FORWARD_RESET_THRESHOLD;
+        if (!needsReset)
+            return;
+        if (this.decoder && this.decoder.state !== 'closed')
+            this.decoder.close();
+        const decoder = new VideoDecoder({
+            output: (frame) => this.#onFrame(frame),
+            error: (e) => {
+                getLogger().warn('VideoDecoder error:', e.message);
+                this.#failPendingWaiters();
+            },
+        });
+        decoder.configure(this.config);
+        this.decoder = decoder;
+        this.flushed = false;
+        this.nextFeedIndex = this.#keyframeBefore(target);
+    }
+    /** Feed samples up to `end` (decode order). Flush only at end-of-stream. */
+    #feedThrough(end, hasWaiter) {
+        const decoder = this.decoder;
+        if (!decoder || decoder.state === 'closed' || this.flushed)
+            return;
+        while (this.nextFeedIndex <= end && this.nextFeedIndex < this.samples.length) {
+            decoder.decode(this.samples[this.nextFeedIndex].chunk);
+            this.nextFeedIndex += 1;
+        }
+        // End of stream with someone waiting: flush to drain the decoder's
+        // reorder buffer (the last few frames only emit on flush).
+        if (hasWaiter && this.nextFeedIndex >= this.samples.length) {
+            this.flushed = true;
+            decoder.flush().catch(() => {
+                /* reset on next request */
+            });
+        }
+    }
+    #onFrame(frame) {
+        if (this.disposed) {
+            frame.close();
+            return;
+        }
+        const idx = this.tsToIndex.get(frame.timestamp);
+        if (idx === undefined || idx < this.windowLo || idx > this.windowHi) {
+            frame.close();
+        }
+        else {
+            const previous = this.cache.get(idx);
+            if (previous)
+                previous.close();
+            this.cache.set(idx, frame);
+        }
+        if (idx !== undefined) {
+            const waiting = this.waiters.get(idx);
+            if (waiting) {
+                this.waiters.delete(idx);
+                const resolved = this.cache.get(idx) ?? null;
+                for (const w of waiting)
+                    w(resolved);
+            }
+        }
+    }
+    #failPendingWaiters() {
+        for (const [, waiting] of this.waiters) {
+            for (const w of waiting)
+                w(null);
+        }
+        this.waiters.clear();
+    }
+    /** Index of the sample whose composition window covers time t. */
+    #sampleIndexAt(t) {
+        const clamped = Math.max(0, Math.min(t, this.samples[this.samples.length - 1].time));
+        // Samples are in decode order; composition order ≈ decode order for
+        // streams without B-frame reordering (our common case). Linear-scan
+        // fallback keeps B-frame streams correct at small cost.
+        let best = 0;
+        let bestTime = -Infinity;
+        for (let i = 0; i < this.samples.length; i++) {
+            const st = this.samples[i].time;
+            if (st <= clamped && st > bestTime) {
+                bestTime = st;
+                best = i;
+            }
+        }
+        return best;
+    }
+    #keyframeBefore(index) {
+        let best = this.keyIndices[0];
+        for (const k of this.keyIndices) {
+            if (k <= index)
+                best = k;
+            else
+                break;
+        }
+        return best;
+    }
+    dispose() {
+        this.disposed = true;
+        this.#failPendingWaiters();
+        for (const frame of this.cache.values())
+            frame.close();
+        this.cache.clear();
+        if (this.decoder && this.decoder.state !== 'closed')
+            this.decoder.close();
+        this.decoder = null;
+        this.samples = [];
+    }
+}
+/**
+ * Pull the codec-private description (avcC / hvcC / vpcC / av1C box
+ * payload) out of the sample-description entry — VideoDecoder needs it
+ * for H.264/H.265 in MP4 (the "avcC extradata" convention).
+ */
+function extractDescription(mp4, trackId) {
+    try {
+        const trak = mp4.getTrackById(trackId);
+        for (const entry of trak.mdia.minf.stbl.stsd.entries) {
+            const box = entry.avcC ?? entry.hvcC ?? entry.vpcC ?? entry.av1C;
+            if (box) {
+                // ⚠ Endianness lives on the `Endianness` export in current
+                // mp4box builds — `DataStream.BIG_ENDIAN` is undefined there,
+                // and passing undefined silently serializes LITTLE-endian,
+                // byte-swapping the avcC and making VideoDecoder reject the
+                // config. Cost us a debugging session; don't regress this.
+                const stream = new DataStream(undefined, 0, Endianness.BIG_ENDIAN);
+                box.write(stream);
+                // Skip the 8-byte box header (size + fourcc).
+                return new Uint8Array(stream.buffer, 8);
+            }
+        }
+    }
+    catch (err) {
+        getLogger().debug('extractDescription failed:', err instanceof Error ? err.message : String(err));
+    }
+    return undefined;
+}
+//# sourceMappingURL=mp4-frame-source.js.map

package/dist/assets/mp4-frame-source.js.map

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

package/dist/audio/encoder.d.ts

@@ -0,0 +1,31 @@
+import type { Muxer, ArrayBufferTarget } from 'mp4-muxer';
+export interface AudioEncodeOptions {
+    /** AAC bitrate in bits/second. Default 128 kbps. */
+    bitrate?: number;
+    /** Codec string. Default 'mp4a.40.2' (AAC-LC). */
+    codec?: string;
+    /** Samples per AudioData chunk. Default 1024 (typical AAC frame size). */
+    chunkSize?: number;
+}
+/** A muxer codec id paired with the matching WebCodecs encoder codec string. */
+export interface PickedAudioCodec {
+    /** mp4-muxer / webm-muxer audio codec id. */
+    muxer: 'aac' | 'opus';
+    /** WebCodecs AudioEncoder codec string. */
+    encoder: string;
+}
+/**
+ * Pick an audio codec this environment's WebCodecs AudioEncoder can actually
+ * encode. AAC ('mp4a.40.2') is preferred (most universal in MP4), but
+ * Chromium on Linux ships NO AAC encoder — only macOS/Windows borrow the OS
+ * one — so on the Linux render container it falls back to Opus, which Chromium
+ * encodes everywhere (and which MP4/WebM both mux). Returns null when no audio
+ * encoder exists at all, so the caller can render silently instead of throwing
+ * "Unsupported codec type" mid-export.
+ */
+export declare function pickAudioCodec(sampleRate: number, numberOfChannels: number, bitrate?: number): Promise<PickedAudioCodec | null>;
+/**
+ * Encode an AudioBuffer through WebCodecs and feed chunks into the muxer.
+ */
+export declare function encodeAudioBuffer(buffer: AudioBuffer, muxer: Muxer<ArrayBufferTarget>, options?: AudioEncodeOptions): Promise<void>;
+//# sourceMappingURL=encoder.d.ts.map

package/dist/audio/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/audio/encoder.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG1D,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IACtB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,gBAAgB,EAAE,MAAM,EACxB,OAAO,SAAkB,GACxB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAoBlC;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,KAAK,CAAC,iBAAiB,CAAC,EAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAyDf"}

package/dist/audio/encoder.js

@@ -0,0 +1,96 @@
+// WebCodecs AudioEncoder integration for the exporter.
+//
+// Takes a rendered AudioBuffer (output of `mixSourceAudio`), chunks it into
+// AudioData frames, encodes via AudioEncoder (AAC-LC), and writes the
+// resulting EncodedAudioChunks into the muxer's audio track.
+import { getLogger } from '../logger.js';
+const DEFAULT_BITRATE = 128_000;
+const DEFAULT_CODEC = 'mp4a.40.2';
+const DEFAULT_CHUNK_SIZE = 1024;
+/**
+ * Pick an audio codec this environment's WebCodecs AudioEncoder can actually
+ * encode. AAC ('mp4a.40.2') is preferred (most universal in MP4), but
+ * Chromium on Linux ships NO AAC encoder — only macOS/Windows borrow the OS
+ * one — so on the Linux render container it falls back to Opus, which Chromium
+ * encodes everywhere (and which MP4/WebM both mux). Returns null when no audio
+ * encoder exists at all, so the caller can render silently instead of throwing
+ * "Unsupported codec type" mid-export.
+ */
+export async function pickAudioCodec(sampleRate, numberOfChannels, bitrate = DEFAULT_BITRATE) {
+    if (typeof AudioEncoder === 'undefined')
+        return null;
+    const candidates = [
+        { muxer: 'aac', encoder: 'mp4a.40.2' },
+        { muxer: 'opus', encoder: 'opus' },
+    ];
+    for (const c of candidates) {
+        try {
+            const { supported } = await AudioEncoder.isConfigSupported({
+                codec: c.encoder,
+                sampleRate,
+                numberOfChannels,
+                bitrate,
+            });
+            if (supported)
+                return c;
+        }
+        catch {
+            /* malformed/unsupported codec string → try the next candidate */
+        }
+    }
+    return null;
+}
+/**
+ * Encode an AudioBuffer through WebCodecs and feed chunks into the muxer.
+ */
+export async function encodeAudioBuffer(buffer, muxer, options = {}) {
+    if (typeof AudioEncoder === 'undefined') {
+        throw new Error('WebCodecs AudioEncoder is not available in this environment');
+    }
+    const bitrate = options.bitrate ?? DEFAULT_BITRATE;
+    const codec = options.codec ?? DEFAULT_CODEC;
+    const chunkSize = options.chunkSize ?? DEFAULT_CHUNK_SIZE;
+    const sampleRate = buffer.sampleRate;
+    const channels = buffer.numberOfChannels;
+    const encoder = new AudioEncoder({
+        output: (chunk, metadata) => {
+            muxer.addAudioChunk(chunk, metadata);
+        },
+        error: (error) => {
+            getLogger().error('AudioEncoder error:', error.message);
+        },
+    });
+    encoder.configure({
+        codec,
+        sampleRate,
+        numberOfChannels: channels,
+        bitrate,
+    });
+    // Interleave channels into a single Float32Array per chunk.
+    const totalFrames = buffer.length;
+    const channelData = [];
+    for (let ch = 0; ch < channels; ch++)
+        channelData.push(buffer.getChannelData(ch));
+    for (let offset = 0; offset < totalFrames; offset += chunkSize) {
+        const frames = Math.min(chunkSize, totalFrames - offset);
+        const interleaved = new Float32Array(frames * channels);
+        for (let i = 0; i < frames; i++) {
+            for (let ch = 0; ch < channels; ch++) {
+                interleaved[i * channels + ch] = channelData[ch][offset + i];
+            }
+        }
+        const audioData = new AudioData({
+            format: 'f32',
+            sampleRate,
+            numberOfFrames: frames,
+            numberOfChannels: channels,
+            timestamp: Math.round((offset / sampleRate) * 1_000_000), // microseconds
+            data: interleaved,
+        });
+        encoder.encode(audioData);
+        audioData.close();
+    }
+    await encoder.flush();
+    encoder.close();
+}
+//# sourceMappingURL=encoder.js.map

package/dist/audio/encoder.js.map

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

package/dist/audio/fades.d.ts

@@ -0,0 +1,16 @@
+export interface FadePoint {
+    /** Timeline seconds since the element became active. */
+    tau: number;
+    /** Envelope gain in [0, 1] (multiply with the element's volume gain). */
+    gain: number;
+}
+/** Envelope value at timeline offset τ. */
+export declare function fadeGainAt(tau: number, trackLength: number, fadeIn: number, fadeOut: number): number;
+/**
+ * Corner points of the envelope from `startTau` (inclusive) through the
+ * end of the track. The first point is the value AT startTau (for
+ * setValueAtTime); subsequent points are linearRamp targets. When both
+ * fades are 0 the result is a single constant point.
+ */
+export declare function fadeBreakpoints(startTau: number, trackLength: number, fadeIn: number, fadeOut: number): FadePoint[];
+//# sourceMappingURL=fades.d.ts.map

package/dist/audio/fades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fades.d.ts","sourceRoot":"","sources":["../../src/audio/fades.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,2CAA2C;AAC3C,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,SAAS,EAAE,CASb"}

package/dist/audio/fades.js

@@ -0,0 +1,43 @@
+// Audio fade envelope — ONE piecewise-linear definition shared by the
+// preview scheduler (realtime GainNode ramps) and the export mixer
+// (OfflineAudioContext ramps), so preview and export are gain-identical.
+//
+// The envelope runs in TIMELINE seconds over the element's visible
+// window [0, trackLength]:
+//
+//   g(τ) = min(1, τ / fade_in) × min(1, (trackLength − τ) / fade_out)
+//
+// (each factor is 1 when its fade is 0/absent). When the fades don't
+// overlap, g is piecewise linear and ramping between its corner points
+// reproduces it exactly; when fade_in + fade_out > trackLength the
+// overlap region is quadratic and the linear ramps are a close
+// approximation through the same corners. fadeBreakpoints returns the
+// corners from a given starting offset, ready for setValueAtTime +
+// linearRampToValueAtTime.
+/** Envelope value at timeline offset τ. */
+export function fadeGainAt(tau, trackLength, fadeIn, fadeOut) {
+    let g = 1;
+    if (fadeIn > 0)
+        g *= Math.min(1, Math.max(0, tau / fadeIn));
+    if (fadeOut > 0)
+        g *= Math.min(1, Math.max(0, (trackLength - tau) / fadeOut));
+    return g;
+}
+/**
+ * Corner points of the envelope from `startTau` (inclusive) through the
+ * end of the track. The first point is the value AT startTau (for
+ * setValueAtTime); subsequent points are linearRamp targets. When both
+ * fades are 0 the result is a single constant point.
+ */
+export function fadeBreakpoints(startTau, trackLength, fadeIn, fadeOut) {
+    const corners = new Set([startTau, trackLength]);
+    if (fadeIn > 0)
+        corners.add(Math.min(fadeIn, trackLength));
+    if (fadeOut > 0)
+        corners.add(Math.max(0, trackLength - fadeOut));
+    return [...corners]
+        .filter((tau) => tau >= startTau)
+        .sort((a, b) => a - b)
+        .map((tau) => ({ tau, gain: fadeGainAt(tau, trackLength, fadeIn, fadeOut) }));
+}
+//# sourceMappingURL=fades.js.map

package/dist/audio/fades.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fades.js","sourceRoot":"","sources":["../../src/audio/fades.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,mEAAmE;AACnE,yEAAyE;AACzE,EAAE;AACF,mEAAmE;AACnE,2BAA2B;AAC3B,EAAE;AACF,sEAAsE;AACtE,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,mEAAmE;AACnE,+DAA+D;AAC/D,sEAAsE;AACtE,mEAAmE;AACnE,2BAA2B;AAS3B,2CAA2C;AAC3C,MAAM,UAAU,UAAU,CACxB,GAAW,EACX,WAAmB,EACnB,MAAc,EACd,OAAe;IAEf,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,MAAM,GAAG,CAAC;QAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC;IAC5D,IAAI,OAAO,GAAG,CAAC;QAAE,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,WAAW,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAC9E,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAgB,EAChB,WAAmB,EACnB,MAAc,EACd,OAAe;IAEf,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;IACzD,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAC3D,IAAI,OAAO,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAEjE,OAAO,CAAC,GAAG,OAAO,CAAC;SAChB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,QAAQ,CAAC;SAChC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACrB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;AAClF,CAAC"}

package/dist/audio/limiter.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Create the master limiter node. Works on both AudioContext (preview) and
+ * OfflineAudioContext (export). Route the summed master gain through this,
+ * then to the destination — and tap meters POST-limiter so they show what
+ * you actually hear.
+ */
+export declare function createMasterLimiter(ctx: BaseAudioContext): DynamicsCompressorNode;
+//# sourceMappingURL=limiter.d.ts.map

package/dist/audio/limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/audio/limiter.ts"],"names":[],"mappings":"AAyBA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,gBAAgB,GAAG,sBAAsB,CAQjF"}