@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/audio/dsp.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pure sample-level helpers: seeded noise, crackle impulses, loop folding, normalisation,
+ * unit conversions. No WebAudio here, so all of it runs (and is tested) in Node.
+ */
+/** Deterministic PRNG (mulberry32). Returns floats in [0, 1). */
+export declare function rng(seed: number): () => number;
+export type NoiseColor = 'white' | 'pink' | 'brown';
+/** Fill `out` with noise in roughly [-1, 1]. Same seed, same samples. */
+export declare function fillNoise(out: Float32Array, color: NoiseColor, seed?: number): Float32Array;
+/**
+ * Sparse random clicks, like embers or static. `density` = average clicks per second; each
+ * click is a short decaying noise burst of `clickDecay` seconds with random amplitude.
+ */
+export declare function fillCrackle(out: Float32Array, sampleRate: number, density: number, seed?: number, clickDecay?: number): Float32Array;
+/**
+ * Make a seamless loop: `data` holds `loopLen + fade` samples. The last `fade` samples are
+ * crossfaded (equal power) into the first `fade`, and the result is the first `loopLen` samples.
+ * Returns a new array of length `loopLen`.
+ */
+export declare function foldLoop(data: Float32Array, loopLen: number, fade: number): Float32Array<ArrayBuffer>;
+/** Largest absolute sample across channels. */
+export declare function peakOf(channels: readonly Float32Array[]): number;
+/** Scale all channels so the peak equals `target`. No-op on silence. Returns the gain applied. */
+export declare function normalize(channels: readonly Float32Array[], target?: number): number;
+/** Round `freq` so a whole number of cycles fits in `duration` (clean loops for tonal layers). */
+export declare function loopSafeFreq(freq: number, duration: number): number;
+export declare const midiToHz: (note: number) => number;
+export declare const semitones: (freq: number, st: number) => number;
+export declare const dbToGain: (db: number) => number;
+export declare const gainToDb: (g: number) => number;
+/**
+ * Slider position (0..1) to linear gain. Squared curve: 0.5 on the slider ≈ -12 dB, which
+ * feels much closer to "half as loud" than linear gain does.
+ */
+export declare function volumeToGain(volume: number): number;
+/**
+ * Procedural reverb impulse response: decaying seeded noise, independent per channel (stereo
+ * width), with a short fade-in so the onset doesn't click. `decay` shapes the tail
+ * (`(1 - t)^decay`; higher = shorter, darker room). Same arguments, same samples.
+ */
+export declare function reverbImpulse(sampleRate: number, seconds?: number, decay?: number, seed?: number, channels?: number): Float32Array<ArrayBuffer>[];
+/** The part of a `BaseAudioContext` that `impulseResponse` needs (a fake will do in tests). */
+export interface BufferFactory {
+    readonly sampleRate: number;
+    createBuffer(channels: number, length: number, sampleRate: number): AudioBuffer;
+}
+export interface ImpulseResponseOptions {
+    /** Impulse length in seconds. Default 2. */
+    seconds?: number;
+    /** Tail shape: `(1 - t)^decay`. Higher = shorter, drier. Default 3. */
+    decay?: number;
+    /** Noise seed. Default 1. */
+    seed?: number;
+    /** Default 2 (stereo width from independent channels). */
+    channels?: number;
+}
+/**
+ * A procedural reverb impulse as an `AudioBuffer` on `ctx` (a `ConvolverNode.buffer`), built from
+ * `reverbImpulse`: no asset to load. Same options, same samples.
+ */
+export declare function impulseResponse(ctx: BufferFactory, opts?: ImpulseResponseOptions): AudioBuffer;

package/dist/audio/dsp.js

@@ -0,0 +1,159 @@
+/**
+ * Pure sample-level helpers: seeded noise, crackle impulses, loop folding, normalisation,
+ * unit conversions. No WebAudio here, so all of it runs (and is tested) in Node.
+ */
+/** Deterministic PRNG (mulberry32). Returns floats in [0, 1). */
+export function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** Fill `out` with noise in roughly [-1, 1]. Same seed, same samples. */
+export function fillNoise(out, color, seed = 1) {
+    const rand = rng(seed);
+    if (color === 'white') {
+        for (let i = 0; i < out.length; i++)
+            out[i] = rand() * 2 - 1;
+        return out;
+    }
+    if (color === 'pink') {
+        // Paul Kellet's economy pink filter.
+        let b0 = 0;
+        let b1 = 0;
+        let b2 = 0;
+        for (let i = 0; i < out.length; i++) {
+            const w = rand() * 2 - 1;
+            b0 = 0.99765 * b0 + w * 0.099046;
+            b1 = 0.963 * b1 + w * 0.2965164;
+            b2 = 0.57 * b2 + w * 1.0526913;
+            out[i] = (b0 + b1 + b2 + w * 0.1848) * 0.2;
+        }
+        return out;
+    }
+    // Brown: leaky integrated white noise.
+    let last = 0;
+    for (let i = 0; i < out.length; i++) {
+        const w = rand() * 2 - 1;
+        last = (last + 0.02 * w) / 1.02;
+        out[i] = last * 3.5;
+    }
+    return out;
+}
+/**
+ * Sparse random clicks, like embers or static. `density` = average clicks per second; each
+ * click is a short decaying noise burst of `clickDecay` seconds with random amplitude.
+ */
+export function fillCrackle(out, sampleRate, density, seed = 1, clickDecay = 0.004) {
+    out.fill(0);
+    const rand = rng(seed);
+    const p = density / sampleRate;
+    const decayN = Math.max(1, Math.round(clickDecay * sampleRate));
+    const k = Math.exp(-5 / decayN);
+    for (let i = 0; i < out.length; i++) {
+        if (rand() >= p)
+            continue;
+        let amp = (0.3 + 0.7 * rand()) * (rand() < 0.5 ? -1 : 1);
+        const len = Math.min(decayN * 2, out.length - i);
+        for (let j = 0; j < len; j++) {
+            out[i + j] += amp * (rand() * 2 - 1);
+            amp *= k;
+        }
+    }
+    return out;
+}
+/**
+ * Make a seamless loop: `data` holds `loopLen + fade` samples. The last `fade` samples are
+ * crossfaded (equal power) into the first `fade`, and the result is the first `loopLen` samples.
+ * Returns a new array of length `loopLen`.
+ */
+export function foldLoop(data, loopLen, fade) {
+    if (fade < 0 || loopLen + fade > data.length)
+        throw new RangeError('foldLoop: not enough samples');
+    const out = new Float32Array(loopLen);
+    out.set(data.subarray(0, loopLen));
+    for (let i = 0; i < fade; i++) {
+        const x = (i + 0.5) / fade;
+        const fadeIn = Math.sin((x * Math.PI) / 2);
+        const fadeOut = Math.cos((x * Math.PI) / 2);
+        out[i] = data[i] * fadeIn + data[loopLen + i] * fadeOut;
+    }
+    return out;
+}
+/** Largest absolute sample across channels. */
+export function peakOf(channels) {
+    let peak = 0;
+    for (const ch of channels) {
+        for (let i = 0; i < ch.length; i++) {
+            const v = Math.abs(ch[i]);
+            if (v > peak)
+                peak = v;
+        }
+    }
+    return peak;
+}
+/** Scale all channels so the peak equals `target`. No-op on silence. Returns the gain applied. */
+export function normalize(channels, target = 0.9) {
+    const peak = peakOf(channels);
+    if (peak < 1e-9)
+        return 1;
+    const g = target / peak;
+    for (const ch of channels)
+        for (let i = 0; i < ch.length; i++)
+            ch[i] *= g;
+    return g;
+}
+/** Round `freq` so a whole number of cycles fits in `duration` (clean loops for tonal layers). */
+export function loopSafeFreq(freq, duration) {
+    if (duration <= 0)
+        return freq;
+    return Math.max(1, Math.round(freq * duration)) / duration;
+}
+export const midiToHz = (note) => 440 * 2 ** ((note - 69) / 12);
+export const semitones = (freq, st) => freq * 2 ** (st / 12);
+export const dbToGain = (db) => 10 ** (db / 20);
+export const gainToDb = (g) => (g <= 0 ? -Infinity : 20 * Math.log10(g));
+/**
+ * Slider position (0..1) to linear gain. Squared curve: 0.5 on the slider ≈ -12 dB, which
+ * feels much closer to "half as loud" than linear gain does.
+ */
+export function volumeToGain(volume) {
+    const v = Math.min(1, Math.max(0, Number.isFinite(volume) ? volume : 0));
+    return v * v;
+}
+/**
+ * Procedural reverb impulse response: decaying seeded noise, independent per channel (stereo
+ * width), with a short fade-in so the onset doesn't click. `decay` shapes the tail
+ * (`(1 - t)^decay`; higher = shorter, darker room). Same arguments, same samples.
+ */
+export function reverbImpulse(sampleRate, seconds = 2, decay = 3, seed = 1, channels = 2) {
+    const n = Math.max(1, Math.round(sampleRate * Math.max(0.01, seconds)));
+    const fadeIn = Math.min(n, Math.max(1, Math.round(sampleRate * 0.002)));
+    const out = [];
+    for (let c = 0; c < channels; c++) {
+        const r = rng(seed * 7919 + c * 104729);
+        const ch = new Float32Array(n);
+        for (let i = 0; i < n; i++) {
+            const env = (1 - i / n) ** decay * Math.min(1, (i + 1) / fadeIn);
+            ch[i] = (r() * 2 - 1) * env;
+        }
+        out.push(ch);
+    }
+    return out;
+}
+/**
+ * A procedural reverb impulse as an `AudioBuffer` on `ctx` (a `ConvolverNode.buffer`), built from
+ * `reverbImpulse`: no asset to load. Same options, same samples.
+ */
+export function impulseResponse(ctx, opts = {}) {
+    const ir = reverbImpulse(ctx.sampleRate, opts.seconds ?? 2, opts.decay ?? 3, opts.seed ?? 1, opts.channels ?? 2);
+    const buffer = ctx.createBuffer(ir.length, ir[0].length, ctx.sampleRate);
+    ir.forEach((ch, i) => {
+        buffer.copyToChannel(ch, i);
+    });
+    return buffer;
+}

package/dist/audio/duck.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Ducking: while anything plays on a trigger bus (dialogue on `ui`), the target bus (music)
+ * drops by `amount`, with an attack and a release. The level is a linear envelope advanced by
+ * `update(dt)` and handed to the mixer as the target bus's scale under the ducker's own key
+ * (`setBusScale`; keys on one bus multiply, so two duckers combine), so the mixer
+ * owns the write: the bus keeps following `setVolume` and `setMuted`, stays silent while
+ * `pause` holds it, and `unpause` lands on the ducked gain.
+ */
+import type { AudioEngine, OutputBus, Voice } from './audio.js';
+export interface DuckerOptions {
+    /** Bus whose activity ducks the target. */
+    trigger: OutputBus;
+    /** Bus that is lowered. */
+    target: OutputBus;
+    /** Fraction of the target's gain removed when fully ducked, 0..1. Default 0.6. */
+    amount?: number;
+    /** Seconds from idle to fully ducked. Default 0.1. */
+    attack?: number;
+    /** Seconds from fully ducked back to idle. Default 0.6. */
+    release?: number;
+    /**
+     * Sidechain threshold in dB. When set (and the context has `createAnalyser`), an analyser on
+     * the trigger bus counts as active while its RMS is above this level, so voices nobody passed
+     * to `watch` still duck. Off by default: activity comes from `watch`.
+     */
+    threshold?: number;
+}
+export interface Ducker {
+    /** Count `voice` as activity on the trigger bus while it plays. Returns the voice. */
+    watch<V extends Voice>(voice: V): V;
+    /** Advance the envelope and write the target bus gain. Call once per frame. */
+    update(dt: number): void;
+    /** True while the trigger bus is active (a watched voice plays, or the sidechain is above threshold). */
+    readonly active: boolean;
+    /** Duck envelope 0 (idle) .. 1 (fully ducked). */
+    readonly level: number;
+    /** Multiplier applied to the target bus right now, `1 - amount × level`. */
+    readonly gain: number;
+    /** This ducker's own `setBusScale` key on the target bus (`'ducker:<n>'`). */
+    readonly key: string;
+    /** Clear this ducker's scale on the target bus (`clearBusScale`) and stop. */
+    dispose(): void;
+}
+export declare function createDucker(mixer: AudioEngine, opts: DuckerOptions): Ducker;

package/dist/audio/duck.js

@@ -0,0 +1,101 @@
+const ANALYSER_SIZE = 256;
+/** Source of each ducker's own `setBusScale` key, so duckers on one target multiply. */
+let nextDuckerId = 0;
+export function createDucker(mixer, opts) {
+    const amount = Math.min(1, Math.max(0, opts.amount ?? 0.6));
+    const attack = Math.max(0.001, opts.attack ?? 0.1);
+    const release = Math.max(0.001, opts.release ?? 0.6);
+    const threshold = opts.threshold;
+    const watched = [];
+    let level = 0;
+    let active = false;
+    let analyser = null;
+    let analyserOn = null;
+    const samples = new Float32Array(ANALYSER_SIZE);
+    let disposed = false;
+    const key = `ducker:${nextDuckerId++}`;
+    function ensureAnalyser() {
+        const ctx = mixer.context;
+        if (threshold === undefined || !ctx || analyserOn === ctx)
+            return;
+        const bus = mixer.busNode(opts.trigger);
+        if (!bus || typeof ctx.createAnalyser !== 'function')
+            return;
+        const a = ctx.createAnalyser();
+        a.fftSize = ANALYSER_SIZE;
+        bus.connect(a);
+        analyser = a;
+        analyserOn = ctx;
+    }
+    function sidechainActive() {
+        if (!analyser || threshold === undefined)
+            return false;
+        analyser.getFloatTimeDomainData(samples);
+        let sum = 0;
+        for (let i = 0; i < samples.length; i++)
+            sum += samples[i] * samples[i];
+        const rms = Math.sqrt(sum / samples.length);
+        return rms > 10 ** (threshold / 20);
+    }
+    function anyWatched() {
+        // Drop finished voices in place (no allocation).
+        let w = 0;
+        for (let i = 0; i < watched.length; i++) {
+            const v = watched[i];
+            if (v.playing)
+                watched[w++] = v;
+        }
+        watched.length = w;
+        return w > 0;
+    }
+    function write() {
+        // The mixer skips an unchanged scale and holds the write while paused or in the background.
+        mixer.setBusScale(opts.target, 1 - amount * level, 0.005, key);
+    }
+    return {
+        watch(voice) {
+            if (!disposed)
+                watched.push(voice);
+            return voice;
+        },
+        update(dt) {
+            if (disposed)
+                return;
+            ensureAnalyser();
+            active = anyWatched() || sidechainActive();
+            const step = Math.max(0, dt);
+            let next = active ? level + step / attack : level - step / release;
+            // Snap at the ends so float residue never leaves a bus a hair below its volume.
+            if (next > 1 - 1e-6)
+                next = 1;
+            else if (next < 1e-6)
+                next = 0;
+            if (next === level)
+                return;
+            level = next;
+            write();
+        },
+        get active() {
+            return active;
+        },
+        get level() {
+            return level;
+        },
+        get gain() {
+            return 1 - amount * level;
+        },
+        key,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            level = 0;
+            active = false;
+            // Drop this ducker's key: the target goes back to the product of the other keys.
+            mixer.clearBusScale(opts.target, key, 0.005);
+            analyser?.disconnect();
+            analyser = null;
+            watched.length = 0;
+        },
+    };
+}

package/dist/audio/envelope.d.ts

@@ -0,0 +1,53 @@
+/**
+ * ADSR envelopes. One source of truth: `envelopeSegments` produces breakpoints, which
+ * `envelopeValueAt` evaluates (pure, tested) and `scheduleEnvelope` writes to an `AudioParam`
+ * with the matching automation calls, so what we test is what plays.
+ */
+export interface Envelope {
+    /** Seconds from 0 to peak (always linear). */
+    attack: number;
+    /** Seconds held at peak. Default 0. */
+    hold?: number;
+    /** Seconds from peak to `sustain`. */
+    decay: number;
+    /** Sustain level, 0..1 of peak. */
+    sustain: number;
+    /** Seconds from the gate-off value to silence. */
+    release: number;
+    /** Shape of decay and release. `exp` sounds natural for percussive sounds. Default `exp`. */
+    curve?: 'linear' | 'exp';
+}
+/** A breakpoint: reach `v` at time `t`, ramping from the previous point with `ramp`. */
+export interface Segment {
+    t: number;
+    v: number;
+    ramp: 'set' | 'linear' | 'exp';
+}
+/** Smallest level an exponential ramp can target (WebAudio can't ramp exponentially to 0). */
+export declare const EXP_FLOOR = 0.0001;
+/** Shorthand for a percussive envelope: instant-ish attack, exponential fall. */
+export declare function pluck(decay: number, attack?: number): Envelope;
+/** Total audible length for a given gate (time from note-on to note-off). */
+export declare function envelopeLength(env: Envelope, gate: number): number;
+/** Evaluate a breakpoint list at time `t` (relative to its start). */
+export declare function evaluateSegments(segs: readonly Segment[], t: number): number;
+/**
+ * Breakpoints for `env` scaled by `peak`, starting at t=0, with note-off at `gate` seconds.
+ * If the gate closes during attack/decay, release starts from the value at that moment.
+ * The last point is exactly 0.
+ */
+export declare function envelopeSegments(env: Envelope, gate: number, peak?: number): Segment[];
+/** Peak-normalised value of `env` at time `t` for a note with the given gate. */
+export declare function envelopeValueAt(env: Envelope, t: number, gate: number, peak?: number): number;
+/** The subset of `AudioParam` used for scheduling (lets tests record calls). */
+export interface ParamLike {
+    value: number;
+    setValueAtTime(v: number, t: number): unknown;
+    linearRampToValueAtTime(v: number, t: number): unknown;
+    exponentialRampToValueAtTime(v: number, t: number): unknown;
+    cancelScheduledValues(t: number): unknown;
+}
+/** Write breakpoints to an `AudioParam`, offset by `start` (context time). */
+export declare function scheduleSegments(param: ParamLike, segs: readonly Segment[], start: number): void;
+/** Schedule `env` on `param` (usually a GainNode's gain). Returns the end time. */
+export declare function scheduleEnvelope(param: ParamLike, env: Envelope, start: number, gate: number, peak?: number): number;

package/dist/audio/envelope.js

@@ -0,0 +1,106 @@
+/**
+ * ADSR envelopes. One source of truth: `envelopeSegments` produces breakpoints, which
+ * `envelopeValueAt` evaluates (pure, tested) and `scheduleEnvelope` writes to an `AudioParam`
+ * with the matching automation calls, so what we test is what plays.
+ */
+/** Smallest level an exponential ramp can target (WebAudio can't ramp exponentially to 0). */
+export const EXP_FLOOR = 1e-4;
+/** Shorthand for a percussive envelope: instant-ish attack, exponential fall. */
+export function pluck(decay, attack = 0.002) {
+    return { attack, decay, sustain: 0, release: 0.01, curve: 'exp' };
+}
+/** Total audible length for a given gate (time from note-on to note-off). */
+export function envelopeLength(env, gate) {
+    return Math.max(0, gate) + env.release;
+}
+function interp(a, b, t) {
+    if (t >= b.t)
+        return b.v;
+    if (t <= a.t)
+        return a.v;
+    const p = (t - a.t) / (b.t - a.t);
+    if (b.ramp === 'set')
+        return a.v;
+    if (b.ramp === 'linear')
+        return a.v + (b.v - a.v) * p;
+    const v0 = Math.max(a.v, EXP_FLOOR);
+    const v1 = Math.max(b.v, EXP_FLOOR);
+    return v0 * (v1 / v0) ** p;
+}
+/** Evaluate a breakpoint list at time `t` (relative to its start). */
+export function evaluateSegments(segs, t) {
+    if (segs.length === 0 || t < segs[0].t)
+        return 0;
+    for (let i = 1; i < segs.length; i++) {
+        if (t < segs[i].t)
+            return interp(segs[i - 1], segs[i], t);
+    }
+    return segs[segs.length - 1].v;
+}
+/**
+ * Breakpoints for `env` scaled by `peak`, starting at t=0, with note-off at `gate` seconds.
+ * If the gate closes during attack/decay, release starts from the value at that moment.
+ * The last point is exactly 0.
+ */
+export function envelopeSegments(env, gate, peak = 1) {
+    const exp = (env.curve ?? 'exp') === 'exp';
+    const a = Math.max(0, env.attack);
+    const h = Math.max(0, env.hold ?? 0);
+    const d = Math.max(0, env.decay);
+    const r = Math.max(1e-4, env.release);
+    const s = Math.min(1, Math.max(0, env.sustain)) * peak;
+    const g = Math.max(0, gate);
+    const full = [{ t: 0, v: 0, ramp: 'set' }];
+    if (a > 0)
+        full.push({ t: a, v: peak, ramp: 'linear' });
+    else
+        full[0] = { t: 0, v: peak, ramp: 'set' };
+    if (h > 0)
+        full.push({ t: a + h, v: peak, ramp: 'linear' });
+    if (d > 0)
+        full.push({ t: a + h + d, v: exp ? Math.max(s, EXP_FLOOR) : s, ramp: exp ? 'exp' : 'linear' });
+    else if (s !== peak)
+        full.push({ t: a + h, v: s, ramp: 'set' });
+    // Keep points strictly before the gate, then a point at the gate with the curve's value there.
+    const out = full.filter((p) => p.t < g || (p.t === 0 && g === 0));
+    const atGate = evaluateSegments(full, g);
+    const next = full.find((p) => p.t >= g);
+    if (g > 0 || out.length === 0) {
+        out.push({ t: g, v: atGate, ramp: next ? next.ramp : 'linear' });
+    }
+    // A 'set' point at the gate would jump; at the gate we already hold atGate, so mark it linear.
+    const last = out[out.length - 1];
+    if (last.ramp === 'set' && last.t > 0)
+        last.ramp = 'linear';
+    if (exp && atGate > EXP_FLOOR) {
+        out.push({ t: g + r, v: EXP_FLOOR, ramp: 'exp' });
+        out.push({ t: g + r, v: 0, ramp: 'set' });
+    }
+    else {
+        out.push({ t: g + r, v: 0, ramp: 'linear' });
+    }
+    return out;
+}
+/** Peak-normalised value of `env` at time `t` for a note with the given gate. */
+export function envelopeValueAt(env, t, gate, peak = 1) {
+    return evaluateSegments(envelopeSegments(env, gate, peak), t);
+}
+/** Write breakpoints to an `AudioParam`, offset by `start` (context time). */
+export function scheduleSegments(param, segs, start) {
+    param.cancelScheduledValues(start);
+    for (const p of segs) {
+        const t = start + p.t;
+        if (p.ramp === 'set')
+            param.setValueAtTime(p.v, t);
+        else if (p.ramp === 'linear')
+            param.linearRampToValueAtTime(p.v, t);
+        else
+            param.exponentialRampToValueAtTime(Math.max(EXP_FLOOR, p.v), t);
+    }
+}
+/** Schedule `env` on `param` (usually a GainNode's gain). Returns the end time. */
+export function scheduleEnvelope(param, env, start, gate, peak = 1) {
+    const segs = envelopeSegments(env, gate, peak);
+    scheduleSegments(param, segs, start);
+    return start + segs[segs.length - 1].t;
+}

package/dist/audio/index.d.ts

@@ -0,0 +1,13 @@
+export { type AttachAudioOptions, AudioEngine, type AudioEngineOptions, type AudioFollowTarget, type AudioPlayOptions, type AudioState, BUS_NAMES, type BusName, type BusSettings, busGain, type CameraLike, type ConeOptions, createVoiceAdapter, DEFAULT_LIMITER, DEFAULT_MAX_DOPPLER_SPEED, DEFAULT_MIXER, DEFAULT_REVERB_SENDS, type LimiterOptions, MAX_VOICE_SENDS, type MixerSettings, type OutputBus, type PauseOptions, type ReverbOptions, type Rolloff, SPEED_OF_SOUND, SpatialListener, type SpatialOptions, type StopAllOptions, sanitizeMixer, type Voice, type VoiceAdapter, type VoiceAdapterOptions, type VoiceFilterKind, type VoiceFilterOptions, } from './audio.js';
+export { type BufferFactory, dbToGain, fillCrackle, fillNoise, foldLoop, gainToDb, type ImpulseResponseOptions, impulseResponse, loopSafeFreq, midiToHz, type NoiseColor, normalize, peakOf, reverbImpulse, rng, semitones, volumeToGain, } from './dsp.js';
+export { createDucker, type Ducker, type DuckerOptions } from './duck.js';
+export { type Envelope, envelopeLength, envelopeSegments, envelopeValueAt, pluck, type Segment, scheduleEnvelope, } from './envelope.js';
+export { createMusic, intensityGains, type Music, type MusicOptions, type MusicPlayOptions, type MusicStart, type Stem, type StreamElement, } from './music.js';
+export { DEFAULT_OCCLUSION, type OccludableVoice, type OcclusionOptions, type OcclusionResult, OcclusionScheduler, occlusionCutoff, occlusionGain, } from './occlusion.js';
+export { type PersistMixerOptions, persistMixer } from './persist.js';
+export { chime, click, crackleLoop, dronePad, type RecipeName, type RecipeOptions, recipes, sparkle, thud, whoosh, zap, } from './recipes.js';
+export { createSend, type Send, type SendKind, type SendOptions } from './send.js';
+export { parseSpriteRef, type SpriteRange, type SpriteSchedule, type SpriteSheet, type SpriteSidecar, spriteSchedule, spriteSheetFrom, } from './sprites.js';
+export { type CrackleSource, type FilterSpec, type Layer, type NoiseSource, type OfflineContextFactory, type OscSource, renderSound, type SoundSpec, type Source, validateSpec, type Wave, } from './synth.js';
+export { createVariations, type Variations, type VariationsOptions, } from './variations.js';
+export { type AudioZone, type AudioZoneDesc, type AudioZoneHost, AudioZones, type ZoneShape, zoneWeight, } from './zones.js';

package/dist/audio/index.js

@@ -0,0 +1,14 @@
+// ws/audio-4
+export { AudioEngine, BUS_NAMES, busGain, createVoiceAdapter, DEFAULT_LIMITER, DEFAULT_MAX_DOPPLER_SPEED, DEFAULT_MIXER, DEFAULT_REVERB_SENDS, MAX_VOICE_SENDS, SPEED_OF_SOUND, SpatialListener, sanitizeMixer, } from './audio.js';
+export { dbToGain, fillCrackle, fillNoise, foldLoop, gainToDb, impulseResponse, loopSafeFreq, midiToHz, normalize, peakOf, reverbImpulse, rng, semitones, volumeToGain, } from './dsp.js';
+export { createDucker } from './duck.js';
+export { envelopeLength, envelopeSegments, envelopeValueAt, pluck, scheduleEnvelope, } from './envelope.js';
+export { createMusic, intensityGains, } from './music.js';
+export { DEFAULT_OCCLUSION, OcclusionScheduler, occlusionCutoff, occlusionGain, } from './occlusion.js';
+export { persistMixer } from './persist.js';
+export { chime, click, crackleLoop, dronePad, recipes, sparkle, thud, whoosh, zap, } from './recipes.js';
+export { createSend } from './send.js';
+export { parseSpriteRef, spriteSchedule, spriteSheetFrom, } from './sprites.js';
+export { renderSound, validateSpec, } from './synth.js';
+export { createVariations, } from './variations.js';
+export { AudioZones, zoneWeight, } from './zones.js';

package/dist/audio/music.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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 { type AudioEngine, type OutputBus } from './audio.js';
+export interface MusicOptions {
+    bpm: number;
+    /** Beats in a bar. Default 4. */
+    beatsPerBar?: number;
+    /** Bus the stems play on. Default `music`. */
+    bus?: OutputBus;
+    /** Beats a `setIntensity` crossfade takes. Default 1. */
+    intensityFadeBeats?: number;
+    /**
+     * Makes the media element a streamed stem plays through. Default `document.createElement('audio')`
+     * where a document exists; without one (and without `createMediaElementSource` on the
+     * context) streamed stems fall back to their buffer.
+     */
+    createElement?: () => StreamElement;
+}
+/** What music needs from an `<audio>` element (a fake in tests). */
+export interface StreamElement {
+    src: string;
+    loop: boolean;
+    currentTime: number;
+    /** NaN until the metadata loaded. */
+    readonly duration: number;
+    readonly paused: boolean;
+    playbackRate: number;
+    play(): Promise<void> | void;
+    pause(): void;
+}
+/** A looping piece of music: a buffer (or a streamable URL) whose length is a whole number of bars. */
+export interface Stem {
+    name: string;
+    /** The decoded loop. Optional when `url` is set and the stem is only ever streamed. */
+    buffer?: AudioBuffer;
+    /** A URL to stream the stem from (`play(name, { stream: true })`). */
+    url?: string;
+    /**
+     * Layer the stem belongs to (default: its own name). Within a layer, stems with an `intensity`
+     * range are mixed by `setIntensity`; a stem without one replaces the layer's other rangeless
+     * stem when played (a crossfade).
+     */
+    layer?: string;
+    /**
+     * Intensity range `[lo, hi]` (0..1) over which the stem is at full gain. Between the `hi` of one
+     * stem and the `lo` of the next in the same layer (sorted by `lo`) the two crossfade linearly,
+     * so their gains sum to 1 at every level. Below the first stem's `lo` the first stem plays,
+     * above the last stem's `hi` the last one does.
+     */
+    intensity?: readonly [number, number];
+}
+export type MusicStart = 'now' | 'beat' | 'bar';
+export interface MusicPlayOptions {
+    /** Overrides the stem's layer. */
+    layer?: string;
+    /** Fade-in length in beats (and fade-out of a stem this one replaces). Default 0 for a stem joining a layer, 1 for a replacement. */
+    fadeBeats?: number;
+    /** When to start: immediately, on the next beat, or on the next bar. Default `bar`. */
+    at?: MusicStart;
+    /** Linear gain on top of the intensity gain. Default 1. */
+    gain?: number;
+    /**
+     * Stream the stem from its `url` through a media element instead of a decoded buffer
+     * (ws/audio-4). A streamed stem starts now, in phase with the grid (`at` is ignored); if the
+     * grid has not started it starts from the element's clock. Falls back to the buffer path
+     * where the context has no `createMediaElementSource` or no element can be made.
+     */
+    stream?: boolean;
+}
+export interface Music {
+    /** Register a stem so `play(name)` finds it. Replaces a stem of the same name. */
+    add(stem: Stem): void;
+    /** Start a stem (by name, or a stem registered on the fly) aligned to the grid. */
+    play(stem: string | Stem, opts?: MusicPlayOptions): void;
+    /** Stop one layer (or every stem) with a fade in beats (default 1). */
+    stop(layer?: string, fadeBeats?: number): void;
+    /** Crossfade stems that declare an `intensity` range. 0..1. */
+    setIntensity(level: number): void;
+    readonly intensity: number;
+    /** Beat within the current bar, 0-based. */
+    readonly beat: number;
+    /** Bars since the grid started, 0-based. */
+    readonly bar: number;
+    /** Beats since the grid started. */
+    readonly totalBeats: number;
+    /** Seconds per beat. */
+    readonly beatDuration: number;
+    /** Context time of the next beat / bar boundary (0 before the context exists). */
+    nextBeatTime(): number;
+    nextBarTime(): number;
+    /** Called once per beat crossed by `update`, with the beat in the bar and the bar. Returns unsubscribe. */
+    onBeat(cb: (beat: number, bar: number) => void): () => void;
+    /** Current target gain of a stem (intensity × play gain; 0 when not playing). */
+    gain(name: string): number;
+    /** Names of the stems playing now. */
+    readonly playing: readonly string[];
+    /** Advance `beat`/`bar` from the context clock and fire `onBeat`. Call once per frame. */
+    update(dt: number): void;
+    /** Stop everything at once and drop the grid. */
+    dispose(): void;
+}
+/** Gains of a sorted run of stems (by `lo`) at `level`, linear crossfades, summing to 1. */
+export declare function intensityGains(ranges: readonly (readonly [number, number])[], level: number, out: number[]): number[];
+export declare function createMusic(mixer: AudioEngine, opts: MusicOptions): Music;