@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/audio/music.js

@@ -0,0 +1,548 @@
+/**
+ * Music on a beat grid: looping stems started sample-accurately on the next beat or bar from the
+ * context clock, grouped in layers, crossfaded by `fadeBeats` and by an intensity level. Sits on
+ * the mixer's buses; it owns its own `AudioBufferSourceNode`s so they can start at an offset
+ * that keeps every stem in phase with the grid. Each playing stem is registered with the mixer
+ * through a `Voice` adapter, so `audio.voices('music')`, `stopAll` and `pause` see it.
+ *
+ * A stem with a `url` can also be streamed (`play(name, { stream: true })`, ws/audio-4): a
+ * `MediaElementAudioSourceNode` over an `<audio>` element the page decodes as it goes, so a long
+ * track costs no decoded buffer. The grid then follows the element's `currentTime`.
+ */
+import { rampParamTo, VoiceSends, } from './audio.js';
+/** Gains of a sorted run of stems (by `lo`) at `level`, linear crossfades, summing to 1. */
+export function intensityGains(ranges, level, out) {
+    const n = ranges.length;
+    out.length = n;
+    if (n === 0)
+        return out;
+    const x = Math.min(1, Math.max(0, level));
+    for (let i = 0; i < n; i++)
+        out[i] = 0;
+    if (x <= ranges[0][1] || n === 1) {
+        out[0] = 1;
+        if (n === 1)
+            return out;
+    }
+    for (let i = 0; i < n - 1; i++) {
+        const hi = ranges[i][1];
+        const nextLo = ranges[i + 1][0];
+        const a = Math.min(hi, nextLo);
+        const b = Math.max(hi, nextLo);
+        if (x < a)
+            break;
+        if (x >= b) {
+            out[i] = 0;
+            out[i + 1] = 1;
+            continue;
+        }
+        // In the transition between stem i and stem i+1.
+        const t = b > a ? (x - a) / (b - a) : 1;
+        out[i] = 1 - t;
+        out[i + 1] = t;
+        break;
+    }
+    return out;
+}
+export function createMusic(mixer, opts) {
+    const bpm = opts.bpm;
+    const beatsPerBar = Math.max(1, Math.round(opts.beatsPerBar ?? 4));
+    const bus = opts.bus ?? 'music';
+    const beatDuration = 60 / bpm;
+    const intensityFade = (opts.intensityFadeBeats ?? 1) * beatDuration;
+    const stems = new Map();
+    const active = new Map();
+    const pending = [];
+    const beatListeners = new Set();
+    const playingNames = [];
+    const scratchRanges = [];
+    const scratchGains = [];
+    const scratchStems = [];
+    const scratchLayers = [];
+    /** Streams fading out, paused once their `stopAt` passes. */
+    const stoppingStreams = [];
+    let origin = -1;
+    /** The streamed stem whose element clock the grid follows (the first one playing). */
+    let clockStream = null;
+    const makeElement = opts.createElement ??
+        (typeof document !== 'undefined'
+            ? () => document.createElement('audio')
+            : null);
+    let lastBeat = -1;
+    let intensity = 0;
+    let unsub = null;
+    let disposed = false;
+    const ctxTime = () => mixer.context?.currentTime ?? 0;
+    function ensureGrid() {
+        const ctx = mixer.context;
+        if (!ctx || mixer.state !== 'running' || !mixer.busNode(bus))
+            return false;
+        if (origin < 0) {
+            origin = ctx.currentTime;
+            lastBeat = -1;
+        }
+        return true;
+    }
+    function startTime(at) {
+        const now = ctxTime();
+        if (at === 'now')
+            return now;
+        const unit = at === 'beat' ? beatDuration : beatDuration * beatsPerBar;
+        const k = Math.ceil((now - origin) / unit - 1e-9);
+        return origin + Math.max(k, 0) * unit;
+    }
+    function layerOf(stem, o) {
+        return o.layer ?? stem.layer ?? stem.name;
+    }
+    /** Recompute the intensity gain of every playing stem in `layer` and ramp to it. */
+    function applyLayer(layer, fade, when) {
+        scratchStems.length = 0;
+        for (const p of active.values()) {
+            if (p.layer === layer && !p.stopping && p.stem.intensity)
+                scratchStems.push(p);
+        }
+        scratchStems.sort((a, b) => a.stem.intensity[0] - b.stem.intensity[0]);
+        scratchRanges.length = 0;
+        for (const p of scratchStems) {
+            const r = p.stem.intensity;
+            scratchRanges.push([r[0], r[1]]);
+        }
+        intensityGains(scratchRanges, intensity, scratchGains);
+        for (let i = 0; i < scratchStems.length; i++) {
+            const p = scratchStems[i];
+            ramp(p, scratchGains[i] * p.playGain, fade, when);
+        }
+    }
+    function ramp(p, target, fade, when) {
+        if (p.target === target && fade > 0)
+            return;
+        p.target = target;
+        const g = p.gainNode.gain;
+        g.cancelScheduledValues(when);
+        g.setValueAtTime(g.value, when);
+        if (fade > 0)
+            g.linearRampToValueAtTime(target, when + fade);
+        else
+            g.setValueAtTime(target, when);
+    }
+    function startStem(stem, o) {
+        const ctx = mixer.context;
+        const busNode = mixer.busNode(bus);
+        const layer = layerOf(stem, o);
+        const streamed = o.stream === true &&
+            stem.url !== undefined &&
+            makeElement !== null &&
+            typeof ctx.createMediaElementSource === 'function';
+        if (!streamed && !stem.buffer) {
+            console.warn(`[audio] stem "${stem.name}" has no buffer${stem.url ? ' and cannot stream here' : ''}`);
+            return;
+        }
+        // A stream cannot be scheduled ahead: it starts now, and so do the fades around it.
+        const when = streamed ? ctxTime() : startTime(o.at ?? 'bar');
+        const existing = active.get(stem.name);
+        if (existing)
+            stopOne(existing, (o.fadeBeats ?? 1) * beatDuration, when);
+        // A rangeless stem replaces the layer's other rangeless stems (a crossfade).
+        let replaced = false;
+        if (!stem.intensity) {
+            for (const p of active.values()) {
+                if (p.layer === layer && !p.stopping && !p.stem.intensity && p.stem.name !== stem.name) {
+                    stopOne(p, (o.fadeBeats ?? 1) * beatDuration, when);
+                    replaced = true;
+                }
+            }
+        }
+        const fade = (o.fadeBeats ?? (replaced ? 1 : 0)) * beatDuration;
+        const gainNode = ctx.createGain();
+        const playGain = o.gain ?? 1;
+        const p = {
+            stem,
+            layer,
+            src: null,
+            el: null,
+            elNode: null,
+            stopAt: 0,
+            gainNode,
+            filterNode: null,
+            playGain,
+            target: 0,
+            stopping: false,
+            voice: null,
+            unregister: null,
+            sends: null,
+        };
+        p.voice = stemVoice(p);
+        const target = stem.intensity ? 0 : playGain;
+        if (fade > 0) {
+            gainNode.gain.setValueAtTime(0, when);
+            gainNode.gain.linearRampToValueAtTime(target, when + fade);
+        }
+        else {
+            gainNode.gain.setValueAtTime(target, when);
+        }
+        p.target = target;
+        gainNode.connect(busNode);
+        if (streamed) {
+            const el = makeElement();
+            el.src = stem.url;
+            el.loop = true;
+            const node = ctx.createMediaElementSource(el);
+            node.connect(gainNode);
+            p.el = el;
+            p.elNode = node;
+            // In phase with the grid where the element's length is known; else it sets the grid.
+            const duration = el.duration;
+            if (Number.isFinite(duration) && duration > 0) {
+                el.currentTime = (((when - origin) % duration) + duration) % duration;
+            }
+            if (clockStream === null) {
+                clockStream = p;
+                if (active.size === 0) {
+                    origin = when - (Number.isFinite(el.currentTime) ? el.currentTime : 0);
+                    lastBeat = -1;
+                }
+            }
+            void Promise.resolve(el.play()).catch(() => { });
+        }
+        else {
+            const src = ctx.createBufferSource();
+            src.buffer = stem.buffer;
+            src.loop = true;
+            p.src = src;
+            src.connect(gainNode);
+            src.onended = () => endOne(p);
+            // Keep the loop in phase with the grid: offset by the grid time elapsed, modulo the loop.
+            const duration = stem.buffer.duration;
+            const offset = duration > 0 ? (((when - origin) % duration) + duration) % duration : 0;
+            src.start(when, offset);
+        }
+        active.set(stem.name, p);
+        p.unregister = mixer.register(p.voice, bus);
+        if (stem.intensity)
+            applyLayer(layer, fade, when);
+    }
+    /** The stem's source is done (buffer ended, or stream paused after its fade): tear it down. */
+    function endOne(p) {
+        p.sends?.dispose();
+        p.sends = null;
+        p.gainNode.disconnect();
+        if (p.filterNode) {
+            p.filterNode.disconnect();
+            mixer.releaseBiquad(p.filterNode);
+            p.filterNode = null;
+        }
+        if (p.el) {
+            p.el.pause();
+            p.elNode?.disconnect();
+            p.el.src = '';
+            if (clockStream === p)
+                clockStream = null;
+        }
+        p.unregister?.();
+        p.unregister = null;
+        if (active.get(p.stem.name) === p)
+            active.delete(p.stem.name);
+    }
+    /** Wire gain → [filter] → bus and move the sends to the tail. */
+    function relink(p) {
+        const busNode = mixer.busNode(bus);
+        const ctx = mixer.context;
+        if (!busNode || !ctx)
+            return;
+        p.gainNode.disconnect();
+        p.filterNode?.disconnect();
+        const tail = p.filterNode ? p.gainNode.connect(p.filterNode) : p.gainNode;
+        tail.connect(busNode);
+        if (p.sends) {
+            if (p.sends.attached)
+                p.sends.retarget(tail);
+            else
+                p.sends.attach(ctx, tail);
+        }
+    }
+    /** Streams cannot `stop(when)`: pause the ones whose fade has ended. */
+    function reapStreams(now) {
+        for (let i = stoppingStreams.length - 1; i >= 0; i--) {
+            const p = stoppingStreams[i];
+            if (now < p.stopAt)
+                continue;
+            stoppingStreams.splice(i, 1);
+            endOne(p);
+        }
+    }
+    /** Follow the clock stream's element: the grid origin is its `currentTime` ago, modulo its length. */
+    function followClock(now) {
+        const p = clockStream;
+        if (!p || p.stopping)
+            return;
+        const el = p.el;
+        const t = el.currentTime;
+        const duration = el.duration;
+        if (!Number.isFinite(t) || el.paused)
+            return;
+        let o = now - t;
+        if (Number.isFinite(duration) && duration > 0 && origin >= 0) {
+            // The element wrapped; keep the origin the candidate nearest the one we had.
+            o -= Math.round((o - origin) / duration) * duration;
+        }
+        origin = o;
+    }
+    /** The `Voice` the mixer sees for a stem: stop fades in seconds, gain and rate write its nodes. */
+    function stemVoice(p) {
+        const voice = {
+            rate: 1,
+            stop(fade = 0) {
+                stopOne(p, fade, ctxTime());
+            },
+            setGain(gain, r = 0.05) {
+                p.playGain = gain;
+                const when = ctxTime();
+                if (p.stopping)
+                    return;
+                if (p.stem.intensity)
+                    applyLayer(p.layer, r, when);
+                else
+                    ramp(p, gain, r, when);
+            },
+            setRate(rate, r = 0.05) {
+                voice.rate = rate;
+                if (p.src) {
+                    rampParamTo(p.src.playbackRate, rate, ctxTime(), r);
+                }
+                else if (p.el && !p.stopping) {
+                    // An element cannot run at 0: pause it, and resume where it was.
+                    if (rate <= 0) {
+                        p.el.pause();
+                    }
+                    else {
+                        p.el.playbackRate = rate;
+                        if (p.el.paused)
+                            void Promise.resolve(p.el.play()).catch(() => { });
+                    }
+                }
+            },
+            setPosition() { },
+            setDirection() { },
+            follow() { },
+            sendTo(input, amount, r = 0.05) {
+                p.sends ??= new VoiceSends();
+                const sends = p.sends;
+                if (!sends.attached)
+                    sends.attach(mixer.context, p.filterNode ?? p.gainNode);
+                sends.set(input, amount, r);
+            },
+            filter(kind, o = {}) {
+                if (p.stopping)
+                    return;
+                const now = ctxTime();
+                const ramp = o.ramp ?? 0.05;
+                if (kind === null) {
+                    const f = p.filterNode;
+                    if (!f)
+                        return;
+                    p.filterNode = null;
+                    relink(p);
+                    mixer.releaseBiquad(f);
+                    return;
+                }
+                let f = p.filterNode;
+                const fresh = f === null;
+                f ??= mixer.acquireBiquad();
+                if (!f)
+                    return;
+                f.type = kind;
+                rampParamTo(f.frequency, o.cutoff ?? 1000, now, fresh ? 0 : ramp);
+                rampParamTo(f.Q, o.q ?? 1, now, fresh ? 0 : ramp);
+                if (fresh) {
+                    p.filterNode = f;
+                    relink(p);
+                }
+            },
+            position: new Float64Array(3),
+            get playing() {
+                return !p.stopping;
+            },
+            get sendCount() {
+                return p.sends?.count ?? 0;
+            },
+            occlusion: 0,
+            doppler: 1,
+        };
+        return voice;
+    }
+    function stopOne(p, fade, when) {
+        if (p.stopping)
+            return;
+        p.stopping = true;
+        active.delete(p.stem.name);
+        p.unregister?.();
+        p.unregister = null;
+        const g = p.gainNode.gain;
+        g.cancelScheduledValues(when);
+        g.setValueAtTime(g.value, when);
+        if (fade > 0) {
+            g.linearRampToValueAtTime(0, when + fade);
+        }
+        else {
+            g.setValueAtTime(0, when);
+        }
+        if (p.src) {
+            try {
+                p.src.stop(when + fade);
+            }
+            catch {
+                // Already stopped.
+            }
+        }
+        else if (p.el) {
+            if (clockStream === p) {
+                clockStream = null;
+                for (const q of active.values())
+                    if (q.el && !q.stopping)
+                        clockStream = q;
+            }
+            p.stopAt = when + fade;
+            if (fade > 0)
+                stoppingStreams.push(p);
+            else
+                endOne(p);
+        }
+    }
+    function flushPending() {
+        if (!ensureGrid())
+            return;
+        for (const q of pending)
+            startStem(q.stem, q.opts);
+        pending.length = 0;
+    }
+    function watchUnlock() {
+        if (unsub)
+            return;
+        unsub = mixer.onStateChange((s) => {
+            if (s === 'running')
+                flushPending();
+        });
+    }
+    const music = {
+        add(stem) {
+            stems.set(stem.name, stem);
+        },
+        play(stem, o = {}) {
+            if (disposed)
+                return;
+            const s = typeof stem === 'string' ? stems.get(stem) : stem;
+            if (!s) {
+                console.warn(`[audio] unknown stem "${String(stem)}"`);
+                return;
+            }
+            if (typeof stem !== 'string')
+                stems.set(s.name, s);
+            if (!ensureGrid()) {
+                pending.push({ stem: s, opts: o });
+                watchUnlock();
+                return;
+            }
+            startStem(s, o);
+        },
+        stop(layer, fadeBeats = 1) {
+            const fade = fadeBeats * beatDuration;
+            const when = ctxTime();
+            for (const p of [...active.values()]) {
+                if (layer === undefined || p.layer === layer)
+                    stopOne(p, fade, when);
+            }
+            if (layer === undefined)
+                pending.length = 0;
+            else
+                for (let i = pending.length - 1; i >= 0; i--) {
+                    if (layerOf(pending[i].stem, pending[i].opts) === layer)
+                        pending.splice(i, 1);
+                }
+        },
+        setIntensity(level) {
+            intensity = Math.min(1, Math.max(0, Number.isFinite(level) ? level : 0));
+            if (origin < 0)
+                return;
+            const when = ctxTime();
+            // One pass per distinct layer that has ranged stems.
+            scratchLayers.length = 0;
+            for (const p of active.values()) {
+                if (!p.stem.intensity || p.stopping || scratchLayers.includes(p.layer))
+                    continue;
+                scratchLayers.push(p.layer);
+            }
+            for (const layer of scratchLayers)
+                applyLayer(layer, intensityFade, when);
+        },
+        get intensity() {
+            return intensity;
+        },
+        get beat() {
+            return origin < 0
+                ? 0
+                : Math.max(0, Math.floor((ctxTime() - origin) / beatDuration)) % beatsPerBar;
+        },
+        get bar() {
+            return origin < 0
+                ? 0
+                : Math.floor(Math.max(0, Math.floor((ctxTime() - origin) / beatDuration)) / beatsPerBar);
+        },
+        get totalBeats() {
+            return origin < 0 ? 0 : Math.max(0, Math.floor((ctxTime() - origin) / beatDuration));
+        },
+        beatDuration,
+        nextBeatTime() {
+            return origin < 0 ? 0 : startTime('beat');
+        },
+        nextBarTime() {
+            return origin < 0 ? 0 : startTime('bar');
+        },
+        onBeat(cb) {
+            beatListeners.add(cb);
+            return () => beatListeners.delete(cb);
+        },
+        gain(name) {
+            return active.get(name)?.target ?? 0;
+        },
+        get playing() {
+            playingNames.length = 0;
+            for (const p of active.values())
+                playingNames.push(p.stem.name);
+            return playingNames;
+        },
+        update() {
+            if (disposed || !ensureGrid())
+                return;
+            const now = ctxTime();
+            if (stoppingStreams.length > 0)
+                reapStreams(now);
+            if (clockStream)
+                followClock(now);
+            const total = Math.max(0, Math.floor((now - origin) / beatDuration));
+            if (total === lastBeat)
+                return;
+            if (lastBeat < 0)
+                lastBeat = total - 1;
+            // Fire each beat crossed since the last update (a long frame skips none).
+            for (let b = lastBeat + 1; b <= total; b++) {
+                const beat = b % beatsPerBar;
+                const bar = Math.floor(b / beatsPerBar);
+                for (const fn of beatListeners)
+                    fn(beat, bar);
+            }
+            lastBeat = total;
+        },
+        dispose() {
+            disposed = true;
+            music.stop(undefined, 0);
+            for (const p of stoppingStreams)
+                endOne(p);
+            stoppingStreams.length = 0;
+            beatListeners.clear();
+            unsub?.();
+            unsub = null;
+            origin = -1;
+        },
+    };
+    return music;
+}

package/dist/audio/occlusion.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Occlusion (ws/audio-4): a game answers one probe per spatial voice with how much of the world
+ * sits between the listener and the emitter (0 clear .. 1 occluded); the engine never casts a
+ * ray. Each probed voice owns a pooled lowpass whose cutoff and gain ramp with the answer. The
+ * probing is round-robin and budgeted, so a scene with many emitters costs a fixed number of
+ * probes per `audio.update`. This file holds the scheduler and the curves; the nodes live in
+ * `audio.ts` (`VoiceImpl.applyOcclusion`).
+ */
+/** The probe's answer, written in place (no allocation per probe). */
+export interface OcclusionResult {
+    /** 0 clear .. 1 fully occluded. Clamped. */
+    amount: number;
+}
+/** `audio.occlusion`: the game's probe and the filter's range. */
+export interface OcclusionOptions {
+    /**
+     * Answer how occluded the sound at `emitter` is for the ears at `listener`, into `out.amount`.
+     * Called from `audio.update`, at most `budget` times per call, each voice at most once per
+     * `interval` seconds. Both positions are live views; copy them if kept.
+     */
+    probe: (listener: ArrayLike<number>, emitter: ArrayLike<number>, out: OcclusionResult) => void;
+    /** Seconds between two probes of one voice, and the ramp time of its filter. Default 0.1. */
+    interval?: number;
+    /** Lowpass cutoff (Hz) when clear. Default 20000. */
+    openCutoff?: number;
+    /** Lowpass cutoff (Hz) when fully occluded. Default 600. */
+    closedCutoff?: number;
+    /** Linear gain when fully occluded (1 when clear). Default 0.4. */
+    closedGain?: number;
+    /** Most probes per `audio.update`. Default 8. */
+    budget?: number;
+}
+export declare const DEFAULT_OCCLUSION: Readonly<Required<Omit<OcclusionOptions, 'probe'>>>;
+/** What the scheduler needs from a voice (a `VoiceImpl` in `audio.ts`). */
+export interface OccludableVoice {
+    readonly position: ArrayLike<number>;
+    /** Context time of the last probe (-Infinity before the first). */
+    occlusionProbedAt: number;
+    /** Ramp the voice's filter to `amount` over `ramp` seconds. */
+    applyOcclusion(amount: number, cutoff: number, gain: number, ramp: number): void;
+}
+/** Lowpass cutoff for `amount`: log-interpolated between open and closed, so the sweep sounds even. */
+export declare function occlusionCutoff(amount: number, open: number, closed: number): number;
+/** Linear gain for `amount`: 1 down to `closedGain`. */
+export declare function occlusionGain(amount: number, closedGain: number): number;
+/**
+ * Round-robin probe scheduler over the engine's occludable voices. `run` walks `voices` from
+ * where the last call stopped, probing those due (`interval` since their last probe) until the
+ * budget is spent; the rest wait for the next `update`. Allocates nothing per call.
+ */
+export declare class OcclusionScheduler {
+    private cursor;
+    private readonly out;
+    run(opts: OcclusionOptions, listener: ArrayLike<number>, voices: readonly OccludableVoice[], now: number): number;
+}

package/dist/audio/occlusion.js

@@ -0,0 +1,61 @@
+/**
+ * Occlusion (ws/audio-4): a game answers one probe per spatial voice with how much of the world
+ * sits between the listener and the emitter (0 clear .. 1 occluded); the engine never casts a
+ * ray. Each probed voice owns a pooled lowpass whose cutoff and gain ramp with the answer. The
+ * probing is round-robin and budgeted, so a scene with many emitters costs a fixed number of
+ * probes per `audio.update`. This file holds the scheduler and the curves; the nodes live in
+ * `audio.ts` (`VoiceImpl.applyOcclusion`).
+ */
+export const DEFAULT_OCCLUSION = {
+    interval: 0.1,
+    openCutoff: 20000,
+    closedCutoff: 600,
+    closedGain: 0.4,
+    budget: 8,
+};
+/** Lowpass cutoff for `amount`: log-interpolated between open and closed, so the sweep sounds even. */
+export function occlusionCutoff(amount, open, closed) {
+    return open * (closed / open) ** amount;
+}
+/** Linear gain for `amount`: 1 down to `closedGain`. */
+export function occlusionGain(amount, closedGain) {
+    return 1 - amount * (1 - closedGain);
+}
+/**
+ * Round-robin probe scheduler over the engine's occludable voices. `run` walks `voices` from
+ * where the last call stopped, probing those due (`interval` since their last probe) until the
+ * budget is spent; the rest wait for the next `update`. Allocates nothing per call.
+ */
+export class OcclusionScheduler {
+    cursor = 0;
+    out = { amount: 0 };
+    run(opts, listener, voices, now) {
+        const n = voices.length;
+        if (n === 0)
+            return 0;
+        const interval = opts.interval ?? DEFAULT_OCCLUSION.interval;
+        const budget = Math.max(1, opts.budget ?? DEFAULT_OCCLUSION.budget);
+        const open = opts.openCutoff ?? DEFAULT_OCCLUSION.openCutoff;
+        const closed = opts.closedCutoff ?? DEFAULT_OCCLUSION.closedCutoff;
+        const closedGain = opts.closedGain ?? DEFAULT_OCCLUSION.closedGain;
+        let cursor = this.cursor < n ? this.cursor : 0;
+        let probed = 0;
+        let visited = 0;
+        while (visited < n && probed < budget) {
+            const v = voices[cursor];
+            cursor = (cursor + 1) % n;
+            visited++;
+            if (now - v.occlusionProbedAt < interval - 1e-9)
+                continue;
+            this.out.amount = 0;
+            opts.probe(listener, v.position, this.out);
+            const a = Math.min(1, Math.max(0, Number.isFinite(this.out.amount) ? this.out.amount : 0));
+            v.occlusionProbedAt = now;
+            v.applyOcclusion(a, occlusionCutoff(a, open, closed), occlusionGain(a, closedGain), interval);
+            probed++;
+            // The next call resumes after the last voice probed (skipped ones stay in line).
+            this.cursor = cursor;
+        }
+        return probed;
+    }
+}

package/dist/audio/persist.d.ts

@@ -0,0 +1,23 @@
+import type { Host } from '../host/types.js';
+import { type SaveStore, type StorageLike } from '../save/index.js';
+import { type AudioEngine, type MixerSettings } from './audio.js';
+export interface PersistMixerOptions {
+    game: string;
+    /** Default `audio` (key `thunderclap:<game>:audio`), separate from progress saves. */
+    slot?: string;
+    /** Where the slot is stored (`host.storage`). Default: `defaultHost()`. */
+    host?: Pick<Host, 'storage'>;
+    /** A fixed storage instead of the host's (tests); `null` keeps it in memory. */
+    storage?: StorageLike | null;
+    debounceMs?: number;
+    autoFlush?: boolean;
+}
+/**
+ * Load mixer settings from `engine/save`, apply them to `audio`, and save every change.
+ * Returns the store (check `store.persistent` to warn about non-persistent storage) and
+ * an `unbind` function.
+ */
+export declare function persistMixer(audio: AudioEngine, opts: PersistMixerOptions): {
+    store: SaveStore<MixerSettings>;
+    unbind: () => void;
+};