@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/audio/persist.js

@@ -0,0 +1,27 @@
+import { createSaveStore, s } from '../save/index.js';
+import { BUS_NAMES, DEFAULT_MIXER, sanitizeMixer, } from './audio.js';
+const Bus = s.object({ volume: s.number({ min: 0, max: 1 }), muted: s.boolean() });
+const Mixer = s.object(Object.fromEntries(BUS_NAMES.map((b) => [b, Bus])));
+/**
+ * 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 function persistMixer(audio, opts) {
+    const store = createSaveStore({
+        game: opts.game,
+        slot: opts.slot ?? 'audio',
+        version: 1,
+        defaults: () => sanitizeMixer(DEFAULT_MIXER),
+        schema: (v) => Mixer.is(v),
+        host: opts.host,
+        storage: opts.storage,
+        debounceMs: opts.debounceMs ?? 300,
+        autoFlush: opts.autoFlush,
+    });
+    audio.applySettings(store.get());
+    const unbind = audio.onSettingsChange((next) => {
+        store.set(sanitizeMixer(next));
+    });
+    return { store, unbind };
+}

package/dist/audio/recipes.d.ts

@@ -0,0 +1,55 @@
+import type { SoundSpec } from './synth.js';
+export interface RecipeOptions {
+    /** Base pitch in Hz (meaning varies per recipe). */
+    pitch?: number;
+    /** Overall length scale, 1 = default. */
+    length?: number;
+    /** 0..1, how much high end. Default 0.5. */
+    brightness?: number;
+    /** Seed for the random parts. */
+    seed?: number;
+    /** Peak level after normalisation. Default 0.8. */
+    level?: number;
+}
+/** Electric zap: a fast falling buzz with a hissing tail. */
+export declare function zap(o?: RecipeOptions): SoundSpec;
+/** Bell-like chime with inharmonic partials and an FM shimmer. `pitch` is the fundamental. */
+export declare function chime(o?: RecipeOptions): SoundSpec;
+/** Low, soft impact: a falling sine body plus a muffled noise knock. */
+export declare function thud(o?: RecipeOptions): SoundSpec;
+/** Short UI tick. `pitch` sets the tone (higher = lighter). */
+export declare function click(o?: RecipeOptions): SoundSpec;
+/** Rising (or falling) airy sweep, for transitions and panels. */
+export declare function whoosh(o?: RecipeOptions & {
+    direction?: 'up' | 'down';
+}): SoundSpec;
+/** A scatter of tiny high plinks across the stereo field, like glints or magic. */
+export declare function sparkle(o?: RecipeOptions & {
+    count?: number;
+}): SoundSpec;
+/**
+ * Seamless loop of crackling: sparse clicks over a faint low rumble. Fire, static, sparks.
+ * `pitch` moves the click band's centre.
+ */
+export declare function crackleLoop(o?: RecipeOptions & {
+    density?: number;
+}): SoundSpec;
+/**
+ * Seamless loop of a soft sustained chord (root, fifth, octave) with slow movement. Ambience
+ * and tension beds. Frequencies are snapped so every layer completes whole cycles per loop.
+ */
+export declare function dronePad(o?: RecipeOptions & {
+    chord?: readonly number[];
+}): SoundSpec;
+/** All recipes by name, for sound boards and data-driven sound tables. */
+export declare const recipes: {
+    readonly zap: typeof zap;
+    readonly chime: typeof chime;
+    readonly thud: typeof thud;
+    readonly click: typeof click;
+    readonly whoosh: typeof whoosh;
+    readonly sparkle: typeof sparkle;
+    readonly crackleLoop: typeof crackleLoop;
+    readonly dronePad: typeof dronePad;
+};
+export type RecipeName = keyof typeof recipes;

package/dist/audio/recipes.js

@@ -0,0 +1,227 @@
+/**
+ * Generic named sound recipes. Each returns a `SoundSpec`; pass options to vary pitch,
+ * length, brightness or seed. Game-specific sound design builds on these or writes specs
+ * directly.
+ */
+import { loopSafeFreq, rng, semitones } from './dsp.js';
+import { pluck } from './envelope.js';
+const bright = (o) => Math.min(1, Math.max(0, o.brightness ?? 0.5));
+/** Electric zap: a fast falling buzz with a hissing tail. */
+export function zap(o = {}) {
+    const L = o.length ?? 1;
+    const p = o.pitch ?? 1400;
+    const b = bright(o);
+    return {
+        duration: 0.4 * L,
+        normalize: o.level ?? 0.8,
+        layers: [
+            {
+                source: { type: 'osc', wave: 'sawtooth', freq: p, freqEnd: p * 0.08, glide: 0.25 * L },
+                env: { attack: 0.002, decay: 0.3 * L, sustain: 0, release: 0.02, curve: 'exp' },
+                filter: { type: 'lowpass', freq: 3000 + 6000 * b, freqEnd: 600, q: 4 },
+                gain: 0.6,
+            },
+            {
+                source: { type: 'osc', wave: 'square', freq: p * 1.51, freqEnd: p * 0.11, glide: 0.2 * L },
+                env: pluck(0.18 * L),
+                gain: 0.25,
+            },
+            {
+                source: { type: 'noise', color: 'white', seed: o.seed ?? 7 },
+                env: { attack: 0.001, decay: 0.25 * L, sustain: 0, release: 0.02, curve: 'exp' },
+                filter: { type: 'bandpass', freq: 5000 + 3000 * b, freqEnd: 900, q: 1.2 },
+                gain: 0.5,
+            },
+        ],
+    };
+}
+/** Bell-like chime with inharmonic partials and an FM shimmer. `pitch` is the fundamental. */
+export function chime(o = {}) {
+    const L = o.length ?? 1;
+    const f = o.pitch ?? 880;
+    const b = bright(o);
+    const ring = 1.6 * L;
+    const partials = [
+        [1, 1, ring],
+        [2.76, 0.4 * (0.5 + b), ring * 0.6],
+        [5.4, 0.2 * b, ring * 0.35],
+        [8.93, 0.08 * b, ring * 0.2],
+    ];
+    const layers = partials
+        .filter(([ratio]) => f * ratio < 18000)
+        .map(([ratio, gain, decay]) => ({
+        source: { type: 'osc', wave: 'sine', freq: f * ratio },
+        env: pluck(decay, 0.003),
+        gain,
+    }));
+    layers.push({
+        source: { type: 'osc', wave: 'sine', freq: f, fm: { ratio: 3.5, index: 1.5 * b, indexEnd: 0 } },
+        env: pluck(ring * 0.5, 0.003),
+        gain: 0.3,
+    });
+    return { duration: ring + 0.05, normalize: o.level ?? 0.8, layers };
+}
+/** Low, soft impact: a falling sine body plus a muffled noise knock. */
+export function thud(o = {}) {
+    const L = o.length ?? 1;
+    const p = o.pitch ?? 110;
+    const b = bright(o);
+    return {
+        duration: 0.5 * L,
+        normalize: o.level ?? 0.85,
+        layers: [
+            {
+                source: { type: 'osc', wave: 'sine', freq: p, freqEnd: p * 0.4, glide: 0.25 * L },
+                env: pluck(0.4 * L, 0.003),
+                gain: 1,
+            },
+            {
+                source: { type: 'noise', color: 'brown', seed: o.seed ?? 3 },
+                env: pluck(0.08 * L, 0.001),
+                filter: { type: 'lowpass', freq: 300 + 1500 * b, q: 0.7 },
+                gain: 0.7,
+            },
+        ],
+    };
+}
+/** Short UI tick. `pitch` sets the tone (higher = lighter). */
+export function click(o = {}) {
+    const p = o.pitch ?? 1800;
+    const b = bright(o);
+    return {
+        duration: 0.06 * (o.length ?? 1),
+        normalize: o.level ?? 0.6,
+        layers: [
+            {
+                source: { type: 'osc', wave: 'triangle', freq: p, freqEnd: p * 0.7 },
+                env: pluck(0.03, 0.001),
+                gain: 0.8,
+            },
+            {
+                source: { type: 'noise', color: 'white', seed: o.seed ?? 11 },
+                env: pluck(0.01, 0.0005),
+                filter: { type: 'highpass', freq: 2000 + 4000 * b },
+                gain: 0.4 * (0.5 + b),
+            },
+        ],
+    };
+}
+/** Rising (or falling) airy sweep, for transitions and panels. */
+export function whoosh(o = {}) {
+    const L = o.length ?? 1;
+    const b = bright(o);
+    const lo = 250;
+    const hi = 1800 + 3000 * b;
+    const up = (o.direction ?? 'up') === 'up';
+    return {
+        duration: 0.7 * L,
+        normalize: o.level ?? 0.7,
+        layers: [
+            {
+                source: { type: 'noise', color: 'pink', seed: o.seed ?? 5 },
+                env: { attack: 0.3 * L, decay: 0.3 * L, sustain: 0, release: 0.05, curve: 'linear' },
+                filter: { type: 'bandpass', freq: up ? lo : hi, freqEnd: up ? hi : lo, q: 1.5 },
+                gain: 1,
+            },
+        ],
+    };
+}
+/** A scatter of tiny high plinks across the stereo field, like glints or magic. */
+export function sparkle(o = {}) {
+    const L = o.length ?? 1;
+    const rand = rng(o.seed ?? 21);
+    const base = o.pitch ?? 1760;
+    const scale = [0, 2, 4, 7, 9, 12, 14, 16, 19];
+    const count = o.count ?? 9;
+    const span = 0.5 * L;
+    const layers = [];
+    for (let i = 0; i < count; i++) {
+        const st = scale[Math.floor(rand() * scale.length)];
+        layers.push({
+            source: { type: 'osc', wave: 'sine', freq: semitones(base, st) },
+            env: pluck(0.12 + 0.15 * rand(), 0.002),
+            start: (i / count) * span * (0.7 + 0.3 * rand()),
+            gain: 0.35 + 0.4 * rand(),
+            pan: rand() * 1.6 - 0.8,
+        });
+    }
+    return { duration: span + 0.35, normalize: o.level ?? 0.7, channels: 2, layers };
+}
+/**
+ * Seamless loop of crackling: sparse clicks over a faint low rumble. Fire, static, sparks.
+ * `pitch` moves the click band's centre.
+ */
+export function crackleLoop(o = {}) {
+    const dur = 4 * (o.length ?? 1);
+    const b = bright(o);
+    const hold = { attack: 0.005, decay: 0, sustain: 1, release: 0.01, curve: 'linear' };
+    return {
+        duration: dur,
+        loop: { crossfade: 0.25 },
+        normalize: o.level ?? 0.6,
+        layers: [
+            {
+                source: { type: 'crackle', density: o.density ?? 25, seed: o.seed ?? 13 },
+                env: hold,
+                filter: { type: 'bandpass', freq: o.pitch ?? 1500 + 2500 * b, q: 0.6 },
+                gain: 1,
+            },
+            {
+                source: { type: 'noise', color: 'brown', seed: (o.seed ?? 13) + 1 },
+                env: hold,
+                filter: { type: 'lowpass', freq: 220 },
+                gain: 0.25,
+            },
+        ],
+    };
+}
+/**
+ * Seamless loop of a soft sustained chord (root, fifth, octave) with slow movement. Ambience
+ * and tension beds. Frequencies are snapped so every layer completes whole cycles per loop.
+ */
+export function dronePad(o = {}) {
+    const dur = 8 * (o.length ?? 1);
+    const root = o.pitch ?? 110;
+    const b = bright(o);
+    const chord = o.chord ?? [0, 7, 12];
+    const hold = { attack: 0.005, decay: 0, sustain: 1, release: 0.01, curve: 'linear' };
+    const layers = [];
+    chord.forEach((st, i) => {
+        const f = semitones(root, st);
+        for (const [k, detune] of [
+            [0, 1],
+            [1, 1.004],
+        ]) {
+            layers.push({
+                source: {
+                    type: 'osc',
+                    wave: k === 0 ? 'sawtooth' : 'triangle',
+                    freq: loopSafeFreq(f * detune, dur),
+                },
+                env: hold,
+                filter: { type: 'lowpass', freq: 500 + 1500 * b, q: 0.5 },
+                gain: (k === 0 ? 0.35 : 0.5) / (1 + i * 0.4),
+                tremolo: { rate: loopSafeFreq(0.125 * (i + 1), dur), depth: 0.3 },
+                pan: chord.length > 1 ? ((i / (chord.length - 1)) * 2 - 1) * 0.5 * (k === 0 ? 1 : -1) : 0,
+            });
+        }
+    });
+    return {
+        duration: dur,
+        loop: { crossfade: 0.5 },
+        normalize: o.level ?? 0.5,
+        channels: 2,
+        layers,
+    };
+}
+/** All recipes by name, for sound boards and data-driven sound tables. */
+export const recipes = {
+    zap,
+    chime,
+    thud,
+    click,
+    whoosh,
+    sparkle,
+    crackleLoop,
+    dronePad,
+};

package/dist/audio/send.d.ts

@@ -0,0 +1,41 @@
+/**
+ * An effect send: a parallel path from one bus through a reverb (`ConvolverNode` on a
+ * procedural impulse) or a lowpass (`BiquadFilterNode`) back into master. A zone drives
+ * `amount` (and `cutoff`) as the listener moves. Built with the context; safe before unlock.
+ */
+import type { AudioEngine, OutputBus } from './audio.js';
+export type SendKind = 'reverb' | 'lowpass';
+export interface SendOptions {
+    kind: SendKind;
+    /** Bus whose signal feeds the send. Default `sfx`. */
+    bus?: OutputBus;
+    /** Starting send level 0..1. Default 0 (silent until a zone raises it). */
+    amount?: number;
+    /** Reverb: impulse length in seconds. Default 2. */
+    seconds?: number;
+    /** Reverb: tail shape, `(1 - t)^decay`. Default 3. */
+    decay?: number;
+    /** Reverb: impulse noise seed. Default 1. */
+    seed?: number;
+    /** Lowpass: starting cutoff in Hz. Default 800. */
+    cutoff?: number;
+    /** Lowpass: resonance. Default 0.7. */
+    q?: number;
+}
+export interface Send {
+    readonly kind: SendKind;
+    /** Send level 0..1 (linear, ramped over ~15 ms). */
+    amount: number;
+    /** Lowpass cutoff in Hz (ramped). Undefined on a reverb send. */
+    cutoff: number | undefined;
+    /** The effect node (`ConvolverNode` or `BiquadFilterNode`), once the context exists. */
+    readonly node: ConvolverNode | BiquadFilterNode | null;
+    /**
+     * The send's input gain. Anything with `connect` (a voice's own node, another bus) can feed it
+     * directly; the source bus is connected for you.
+     */
+    readonly input: GainNode | null;
+    /** Disconnect everything. */
+    dispose(): void;
+}
+export declare function createSend(mixer: AudioEngine, opts: SendOptions): Send;

package/dist/audio/send.js

@@ -0,0 +1,118 @@
+import { impulseResponse } from './dsp.js';
+export function createSend(mixer, opts) {
+    const kind = opts.kind;
+    const bus = opts.bus ?? 'sfx';
+    let amount = clamp01(opts.amount ?? 0);
+    let cutoff = Math.max(10, opts.cutoff ?? 800);
+    const q = opts.q ?? 0.7;
+    let input = null;
+    let node = null;
+    let ret = null;
+    let builtOn = null;
+    let unsub = null;
+    let disposed = false;
+    function build() {
+        const ctx = mixer.context;
+        const from = mixer.busNode(bus);
+        const master = mixer.busNode('master');
+        if (disposed || !ctx || !from || !master || builtOn === ctx)
+            return;
+        let effect;
+        if (kind === 'reverb') {
+            if (typeof ctx.createConvolver !== 'function')
+                return;
+            const c = ctx.createConvolver();
+            c.normalize = true;
+            c.buffer = impulseResponse(ctx, {
+                seconds: opts.seconds,
+                decay: opts.decay,
+                seed: opts.seed,
+            });
+            effect = c;
+        }
+        else {
+            if (typeof ctx.createBiquadFilter !== 'function')
+                return;
+            const f = ctx.createBiquadFilter();
+            f.type = 'lowpass';
+            f.frequency.value = cutoff;
+            f.Q.value = q;
+            effect = f;
+        }
+        const g = ctx.createGain();
+        g.gain.value = amount;
+        const r = ctx.createGain();
+        r.gain.value = 1;
+        from.connect(g);
+        g.connect(effect);
+        effect.connect(r);
+        r.connect(master);
+        input = g;
+        node = effect;
+        ret = r;
+        builtOn = ctx;
+    }
+    function teardown() {
+        const from = mixer.busNode(bus);
+        if (input) {
+            try {
+                from?.disconnect(input);
+            }
+            catch {
+                // Not connected (context replaced).
+            }
+            input.disconnect();
+        }
+        node?.disconnect();
+        ret?.disconnect();
+        input = null;
+        node = null;
+        ret = null;
+        builtOn = null;
+    }
+    build();
+    if (!builtOn) {
+        unsub = mixer.onStateChange((s) => {
+            if (s === 'running')
+                build();
+        });
+    }
+    return {
+        kind,
+        get amount() {
+            return amount;
+        },
+        set amount(v) {
+            amount = clamp01(v);
+            const ctx = mixer.context;
+            if (input && ctx)
+                input.gain.setTargetAtTime(amount, ctx.currentTime, 0.015);
+        },
+        get cutoff() {
+            return kind === 'lowpass' ? cutoff : undefined;
+        },
+        set cutoff(v) {
+            if (kind !== 'lowpass' || v === undefined)
+                return;
+            cutoff = Math.max(10, Number.isFinite(v) ? v : cutoff);
+            const ctx = mixer.context;
+            if (node && ctx)
+                node.frequency.setTargetAtTime(cutoff, ctx.currentTime, 0.015);
+        },
+        get node() {
+            return node;
+        },
+        get input() {
+            return input;
+        },
+        dispose() {
+            disposed = true;
+            unsub?.();
+            unsub = null;
+            teardown();
+        },
+    };
+}
+function clamp01(v) {
+    return Math.min(1, Math.max(0, Number.isFinite(v) ? v : 0));
+}

package/dist/audio/sprites.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Audio sprites (ws/audio-4): one buffer, many named ranges. `audio.defineSprites(name, sheet)`
+ * registers the sheet; `audio.play('name#clip')` then plays one range with the usual `Voice`
+ * surface, and `audio.loop('name#clip')` loops it between its `loopPoints` (or the whole
+ * range). This file is the pure part: the reference syntax, the range arithmetic and the JSON
+ * sidecar shape. Nothing here touches a node.
+ */
+/** `[startMs, lengthMs]` of one clip inside the sheet's buffer. */
+export type SpriteRange = readonly [startMs: number, lengthMs: number];
+/** What `audio.defineSprites` takes. */
+export interface SpriteSheet {
+    /** The decoded buffer every clip is a range of. */
+    buffer?: AudioBuffer;
+    /**
+     * Or a factory that produces it (the game's own fetch and decode, so the engine makes no
+     * network call: a bundle `audio` entry, `fetch` + `decodeAudioData`). Rendered lazily, or by
+     * `audio.prepare`.
+     */
+    source?: () => Promise<AudioBuffer>;
+    /** Clip name → `[startMs, lengthMs]`. */
+    sprites: Readonly<Record<string, SpriteRange>>;
+    /**
+     * Clip name → `[startMs, endMs]` inside the clip, the section `audio.loop('name#clip')` repeats
+     * once it has played into it (an intro before a loop). A clip without one loops its whole range.
+     */
+    loopPoints?: Readonly<Record<string, readonly [startMs: number, endMs: number]>>;
+}
+/**
+ * The JSON sidecar a sprite packer writes next to its audio file: `src` names the audio file
+ * (relative to the sidecar), `sprites` and `loopPoints` are as in `SpriteSheet`. Load it as a
+ * bundle `json` entry and the audio as an `audio` entry, then `spriteSheetFrom(sidecar, buffer)`.
+ */
+export interface SpriteSidecar {
+    src: string;
+    sprites: Readonly<Record<string, SpriteRange>>;
+    loopPoints?: Readonly<Record<string, readonly [number, number]>>;
+}
+/** A sidecar plus its decoded buffer as a `SpriteSheet` for `audio.defineSprites`. */
+export declare function spriteSheetFrom(sidecar: SpriteSidecar, buffer: AudioBuffer): SpriteSheet;
+/** What a sprite voice schedules: `start(when, offset, duration)` or a loop between two points. */
+export interface SpriteSchedule {
+    /** Seconds into the buffer the clip starts. */
+    offset: number;
+    /** Seconds the clip plays (a one-shot). */
+    duration: number;
+    /** Seconds into the buffer the loop section runs between (a loop). */
+    loopStart: number;
+    loopEnd: number;
+}
+/** Splits `name#clip`; null for a plain sound name. */
+export declare function parseSpriteRef(ref: string): {
+    sheet: string;
+    clip: string;
+} | null;
+/**
+ * The schedule of `clip` in `sheet`, in seconds. Throws a readable error for a clip the sheet
+ * does not define. Writes `out` and returns it (no allocation when one is passed).
+ */
+export declare function spriteSchedule(sheet: SpriteSheet, sheetName: string, clip: string, out?: SpriteSchedule): SpriteSchedule;

package/dist/audio/sprites.js

@@ -0,0 +1,43 @@
+/**
+ * Audio sprites (ws/audio-4): one buffer, many named ranges. `audio.defineSprites(name, sheet)`
+ * registers the sheet; `audio.play('name#clip')` then plays one range with the usual `Voice`
+ * surface, and `audio.loop('name#clip')` loops it between its `loopPoints` (or the whole
+ * range). This file is the pure part: the reference syntax, the range arithmetic and the JSON
+ * sidecar shape. Nothing here touches a node.
+ */
+/** A sidecar plus its decoded buffer as a `SpriteSheet` for `audio.defineSprites`. */
+export function spriteSheetFrom(sidecar, buffer) {
+    return { buffer, sprites: sidecar.sprites, loopPoints: sidecar.loopPoints };
+}
+/** Splits `name#clip`; null for a plain sound name. */
+export function parseSpriteRef(ref) {
+    const i = ref.indexOf('#');
+    if (i < 0)
+        return null;
+    return { sheet: ref.slice(0, i), clip: ref.slice(i + 1) };
+}
+/**
+ * The schedule of `clip` in `sheet`, in seconds. Throws a readable error for a clip the sheet
+ * does not define. Writes `out` and returns it (no allocation when one is passed).
+ */
+export function spriteSchedule(sheet, sheetName, clip, out = { offset: 0, duration: 0, loopStart: 0, loopEnd: 0 }) {
+    const range = sheet.sprites[clip];
+    if (!range) {
+        const known = Object.keys(sheet.sprites).join(', ') || '(none)';
+        throw new Error(`[audio] sprite sheet "${sheetName}" has no clip "${clip}" (clips: ${known})`);
+    }
+    const start = Math.max(0, range[0]) / 1000;
+    const length = Math.max(0, range[1]) / 1000;
+    out.offset = start;
+    out.duration = length;
+    const lp = sheet.loopPoints?.[clip];
+    if (lp) {
+        out.loopStart = start + Math.max(0, lp[0]) / 1000;
+        out.loopEnd = start + Math.min(length * 1000, Math.max(lp[0], lp[1])) / 1000;
+    }
+    else {
+        out.loopStart = start;
+        out.loopEnd = start + length;
+    }
+    return out;
+}

package/dist/audio/synth.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Procedural synth: a declarative `SoundSpec` (layers of oscillators / noise / crackle, each
+ * with an envelope, optional glide, FM, vibrato, tremolo and filters) rendered once into an
+ * `AudioBuffer` with an `OfflineAudioContext`. Specs are plain data: easy to tweak, diff and test.
+ */
+import { type NoiseColor } from './dsp.js';
+import { type Envelope } from './envelope.js';
+export type Wave = 'sine' | 'square' | 'sawtooth' | 'triangle';
+export interface OscSource {
+    type: 'osc';
+    wave: Wave;
+    /** Start frequency, Hz. */
+    freq: number;
+    /** Glide target, Hz. */
+    freqEnd?: number;
+    /** Glide time, seconds from layer start. Default: the layer's whole envelope. */
+    glide?: number;
+    /** Default `exp` (musical pitch sweep). */
+    glideCurve?: 'exp' | 'linear';
+    /** Cents. */
+    detune?: number;
+    /** Pitch wobble: `rate` Hz, `depth` cents. */
+    vibrato?: {
+        rate: number;
+        depth: number;
+    };
+    /**
+     * Frequency modulation (bells, metallic tones): modulator at `freq * ratio`, deviation
+     * `index * freq` Hz, ramping to `indexEnd` over the envelope.
+     */
+    fm?: {
+        ratio: number;
+        index: number;
+        indexEnd?: number;
+    };
+}
+export interface NoiseSource {
+    type: 'noise';
+    color: NoiseColor;
+    seed?: number;
+}
+export interface CrackleSource {
+    type: 'crackle';
+    /** Average clicks per second. */
+    density: number;
+    seed?: number;
+    /** Seconds each click rings. Default 0.004. */
+    clickDecay?: number;
+}
+export type Source = OscSource | NoiseSource | CrackleSource;
+export interface FilterSpec {
+    type: BiquadFilterType;
+    /** Cutoff/centre Hz. */
+    freq: number;
+    /** Sweep target Hz (exponential, over the layer's envelope). */
+    freqEnd?: number;
+    q?: number;
+    /** dB, for shelf/peaking types. */
+    gain?: number;
+}
+export interface Layer {
+    source: Source;
+    env: Envelope;
+    /** Peak gain of this layer. Default 1. */
+    gain?: number;
+    /** Seconds after the sound starts. Default 0. */
+    start?: number;
+    /** Seconds from layer start to note-off. Default: as long as fits before `duration`. */
+    gate?: number;
+    /** -1..1. Makes the render stereo. */
+    pan?: number;
+    filter?: FilterSpec | readonly FilterSpec[];
+    /** Amplitude wobble: `rate` Hz, `depth` 0..1. */
+    tremolo?: {
+        rate: number;
+        depth: number;
+    };
+}
+export interface SoundSpec {
+    /** Seconds. For loops, the loop length. */
+    duration: number;
+    layers: readonly Layer[];
+    /** Master gain applied before normalisation. Default 1. */
+    gain?: number;
+    /** Peak-normalise to this level (e.g. 0.8). Default: no normalisation. */
+    normalize?: number;
+    /** Default 44100. */
+    sampleRate?: number;
+    /** Default: 2 if any layer pans, else 1. */
+    channels?: 1 | 2;
+    /** Render `crossfade` extra seconds and fold them into the head for a seamless loop. */
+    loop?: {
+        crossfade: number;
+    };
+}
+/** Default gate: note-off early enough for the release to finish inside `duration`. */
+export declare function layerGate(layer: Layer, duration: number): number;
+export declare function specChannels(spec: SoundSpec): 1 | 2;
+/** Problems with a spec, or an empty array. Used by tests and in dev before rendering. */
+export declare function validateSpec(spec: SoundSpec): string[];
+export type OfflineContextFactory = (channels: number, length: number, sampleRate: number) => OfflineAudioContext;
+/** Render a spec to an `AudioBuffer`. Rendering needs no user gesture. */
+export declare function renderSound(spec: SoundSpec, createOffline?: OfflineContextFactory): Promise<AudioBuffer>;