@weasel-js/audio 1.7.0 → 1.7.2

package/dist/index.d.ts

@@ -1,7 +1,10 @@
+/** Options for `createAnalyserTap` and `AudioEngine.analyser`. */
 interface AnalyserTapOptions {
     /** Power of two, 32..32768. Default 2048. */
     fftSize?: number;
 }
+/** An `AnalyserNode` attached to a point in the graph, with readers for its
+ *  spectrum, waveform and level. Each call reads the current window. */
 interface AnalyserTap {
     /** The underlying node, exposed for disposal assertions and advanced wiring. */
     node: AnalyserNode;
@@ -19,8 +22,67 @@ interface AnalyserTap {
     /** Detach from the tapped node. Idempotent. */
     dispose(): void;
 }
+/** Attach a new `AnalyserNode` to `source`. The tap only listens, adding no
+ *  path to the destination; `dispose()` detaches it. */
 declare function createAnalyserTap(ctx: AudioContext, source: AudioNode, opts?: AnalyserTapOptions): AnalyserTap;
 
+/** A one-shot timer pair, as `AudioEngineOptions.setTimer` takes it. */
+interface Timers {
+    setTimer(cb: () => void, ms: number): unknown;
+    clearTimer(handle: unknown): void;
+}
+
+/**
+ * Anything with an input and an output node can sit in an insert slot: one of
+ * the built-ins (`createFilterEffect` and the rest), or a pair of nodes of your
+ * own — `{ input: shaper, output: shaper }` for a single node. Several nodes
+ * between the two are fine too. An effect goes in one slot, once.
+ */
+interface InsertEffect {
+    readonly input: AudioNode;
+    readonly output: AudioNode;
+    /** Called once the effect has left the graph after `remove()` or `clear()`. */
+    dispose?(): void;
+}
+/** One effect's place in a bus's insert chain. Every edit is click-free: a
+ *  bypass crossfades the slot's wet and dry, and a structural edit crossfades
+ *  the old route into the new one. */
+interface InsertSlot {
+    readonly effect: InsertEffect;
+    /** Route around the effect (`true`) or back through it. */
+    bypass(on: boolean): void;
+    bypassed(): boolean;
+    /** Clamped to the chain. */
+    moveTo(index: number): void;
+    /** Take the effect out, then call its `dispose`. Idempotent. */
+    remove(): void;
+    /** Position in the chain, or -1 once removed. */
+    index(): number;
+}
+interface InsertAddOptions {
+    /** Default: the end of the chain. Clamped. */
+    index?: number;
+    /** Add it routed around, for a later `bypass(false)`. Default false. */
+    bypassed?: boolean;
+}
+/**
+ * A bus's ordered insert effects, between where voices connect and the bus's
+ * fader. `slots()` is the chain as edited; the audio graph follows one
+ * crossfade at a time, and `settled()` resolves once it has caught up.
+ */
+interface InsertChain {
+    add(effect: InsertEffect, opts?: InsertAddOptions): InsertSlot;
+    slots(): InsertSlot[];
+    clear(): void;
+    settled(): Promise<void>;
+}
+interface InsertChainOptions extends Partial<Timers> {
+    /** Crossfade length for every edit, in ms. Default 15. */
+    fadeMs?: number;
+}
+
+/** Controls for one named bus. `rampMs` slews a gain change over that many
+ *  ms instead of stepping it. */
 interface BusHandle {
     setGain(value: number, rampMs?: number): void;
     mute(on: boolean): void;
@@ -34,13 +96,23 @@ interface BusHandle {
     /** Whether the bus is being heard: unmuted, and soloed if any bus is soloed.
      *  Not derivable from `muted()` and `soloed()` alone. */
     audible(): boolean;
+    /** Effects between where the bus's voices connect and its fader. */
+    readonly inserts: InsertChain;
 }
+/** The mix graph built by `createBusGraph`. `input(name)` is where a voice
+ *  connects; it runs through the bus's inserts to `node(name)`, the fader,
+ *  which feeds `master`, which feeds the destination. Unknown bus names throw. */
 interface BusGraph {
     master: GainNode;
+    input(name: string): GainNode;
     node(name: string): GainNode;
     bus(name: string): BusHandle;
     names(): string[];
+    /** Cancel every insert transition in flight. The nodes stay wired. */
+    dispose(): void;
 }
+/** Options for `createBusGraph`: the insert chains' crossfade and timer. */
+type BusGraphOptions = InsertChainOptions;
 /**
  * The mix graph: one `GainNode` per named bus, all routed to a master that
  * routes to the destination.
@@ -51,12 +123,13 @@ interface BusGraph {
  * `writeParam`, so `rampMs` survives instead of being overwritten by the
  * recomputation that follows it.
  */
-declare function createBusGraph(ctx: AudioContext, names: string[]): BusGraph;
+declare function createBusGraph(ctx: AudioContext, names: string[], opts?: BusGraphOptions): BusGraph;
 
 /** Opaque reference to a decoded sound. Mirrors `TextureHandle` in core. */
 interface SoundHandle {
     readonly id: string;
 }
+/** Decoded buffers behind opaque `SoundHandle`s. Nothing is ever evicted. */
 interface SoundCache {
     load(url: string): Promise<SoundHandle>;
     loadAll(urls: Record<string, string>): Promise<Record<string, SoundHandle>>;
@@ -66,12 +139,18 @@ interface SoundCache {
     register(buffer: AudioBuffer): SoundHandle;
     buffer(handle: SoundHandle): AudioBuffer | null;
 }
+/** Create a cache that decodes through `ctx`. `load` fetches with `fetchFn`,
+ *  returns the existing handle for a url already loaded, and shares one fetch
+ *  between concurrent loads of it; a failed load is not cached. */
 declare function createSoundCache(ctx: AudioContext, fetchFn?: typeof fetch): SoundCache;
 
+/** A 2D world position, in the consumer's own units. */
 interface Vec2 {
     x: number;
     y: number;
 }
+/** Distance and pan model for `spatialize`, in the same units as the
+ *  positions. */
 interface SpatialOptions {
     /** Distance within which gain stays at 1. Default 1. The inverse model needs
      *  this above 0: at 0 it cliffs gain from 1 to 0 at any nonzero distance. */
@@ -96,19 +175,64 @@ declare function spatialize(source: Vec2, listener: Vec2, opts?: SpatialOptions)
     pan: number;
 };
 
+/** An ADSR envelope. Times are ms; `sustain` is a level, 0..1, of the peak. */
+interface Envelope {
+    /** Default 5 — long enough that the onset does not click. */
+    attack?: number;
+    /** Default 0. */
+    decay?: number;
+    /** Default 1. */
+    sustain?: number;
+    /** Default 30. */
+    release?: number;
+}
+type ResolvedEnvelope = Required<Envelope>;
+interface EnvelopePoint {
+    /** ms from the note's start. */
+    at: number;
+    value: number;
+}
+declare function resolveEnvelope(env?: Envelope): ResolvedEnvelope;
+/** The level `t` ms after the start. With `gate`, the release begins that many
+ *  ms in, from whatever level the envelope had reached. */
+declare function envelopeLevel(e: ResolvedEnvelope, t: number, gate?: number): number;
+/**
+ * Breakpoints joined by linear ramps. Without `gate` they end at the sustain,
+ * held until something releases the note; with it they end at zero, `gate +
+ * release` ms in.
+ */
+declare function envelopePoints(e: ResolvedEnvelope, gate?: number): EnvelopePoint[];
+
+/** A pitch: hertz as a number, a scientific pitch name (`'A4'`, `'C#3'`,
+ *  `'Bb2'`), or a MIDI note number wrapped as `{ midi }` so it cannot be read
+ *  as hertz. */
+type Pitch = number | string | {
+    midi: number;
+};
+/** Equal temperament, A4 = MIDI 69 = 440 Hz. Fractional notes are cents. */
+declare function midiToFrequency(midi: number): number;
+/** MIDI number of a scientific pitch name: C4 is 60. Accepts any run of `#`
+ *  or `b` after the letter. */
+declare function noteToMidi(name: string): number;
+declare function toFrequency(pitch: Pitch): number;
+
+/** Which voice a full pool evicts: the earliest started, or the lowest gain. */
 type StealPolicy = 'oldest' | 'quietest';
+/** Options for `createVoicePool`. */
 interface VoicePoolOptions {
     /** Maximum concurrent voices, at least 1. Beyond this, `acquire` steals. */
     limit: number;
     /** Default 'oldest'. */
     steal?: StealPolicy;
 }
+/** What the pool knows about a voice, for choosing one to steal. */
 interface VoiceRecord {
     /** Engine time the voice started, in ms. */
     startedAt: number;
     /** Current gain, consulted by the 'quietest' steal policy. */
     gain: number;
 }
+/** The result of `VoicePool.acquire`. */
 interface Acquisition {
     slot: number;
     /** Identifies this voice, not its slot: a stolen slot is reissued at once,
@@ -118,6 +242,7 @@ interface Acquisition {
      *  responsible for actually stopping that voice's nodes. */
     stolen: number | null;
 }
+/** Slot accounting for concurrent voices. See `createVoicePool`. */
 interface VoicePool {
     acquire(record: VoiceRecord): Acquisition;
     release(slot: number, token: number): void;
@@ -135,6 +260,7 @@ interface VoicePool {
  */
 declare function createVoicePool(opts: VoicePoolOptions): VoicePool;
 
+/** Options for `AudioEngine.play`. */
 interface PlayOptions {
     /** Default: the first configured bus. */
     bus?: string;
@@ -155,10 +281,16 @@ interface PlayOptions {
     cancelKey?: string;
     onDone?: () => void;
 }
+/** Controls for one voice from `play()`. Safe to keep past the voice's end:
+ *  every setter is then a no-op and `isPlaying()` is false. */
 interface VoiceHandle {
     id: number;
     /** `fadeMs` ramps the voice out and stops it at the end of the ramp. */
     stop(fadeMs?: number): void;
+    /** Note-off: a synth voice runs its envelope's release from whatever level it
+     *  has reached. A buffer voice has no envelope, so this is `stop()`. Either
+     *  one released before it starts is canceled. */
+    release(): void;
     setGain(value: number, rampMs?: number): void;
     /** Playback rate. Applies to a voice booked for a future `when` too. */
     setRate(value: number): void;
@@ -169,6 +301,110 @@ interface VoiceHandle {
     setPosition(p: Vec2): void;
     isPlaying(): boolean;
 }
+/** One sine partial of an inharmonic voice. */
+interface SynthPartial {
+    /** Frequency as a multiple of the note's pitch. Any positive number: this is
+     *  what reaches off the harmonic series. */
+    ratio: number;
+    /** Relative level, default 1. The voice's partials are scaled so their levels
+     *  sum to 1, so the peak cannot pass the note's gain. */
+    gain?: number;
+    /** Exponential decay time constant in ms: the partial falls to 1/e of its
+     *  level every `decay` ms, under the note's envelope. Omit to hold it. */
+    decay?: number;
+}
+/** A voice built from sine oscillators at arbitrary ratios of the pitch, each
+ *  with its own level and decay: a bell, a bar, struck metal. */
+interface Inharmonic {
+    partials: readonly SynthPartial[];
+}
+/** An oscillator's waveform: one of Web Audio's built-in shapes; the
+ *  amplitudes of harmonic partials — `[1, 0.5, 0.25]` is the fundamental at
+ *  full level, the second harmonic at half and the third at a quarter, normalized
+ *  so only their ratios matter; or `{ partials }`, sines at any ratio. */
+type Waveform = 'sine' | 'square' | 'sawtooth' | 'triangle' | readonly number[] | Inharmonic;
+/** A `BiquadFilterNode` inside a synth voice, ahead of its amplitude envelope,
+ *  with an envelope of its own on the cutoff. */
+interface VoiceFilter {
+    /** Default 'lowpass'. */
+    type?: BiquadFilterType;
+    /** Cutoff or center in Hz, where the frequency envelope starts and ends. */
+    frequency: number;
+    /** Default 1. */
+    Q?: number;
+    /** dB, for the shelf and peaking types. */
+    gain?: number;
+    /** Shapes the cutoff: it sits at `frequency + amount × level`, `level` being
+     *  this envelope's 0..1. It shares the note's gate and is released with it.
+     *  A thump is a lowpass with a positive `amount` and a short decay to
+     *  `sustain: 0`. Default: the cutoff holds at `frequency`. */
+    envelope?: Envelope;
+    /** Hz added at the envelope's peak; negative sweeps the cutoff down. Default 0. */
+    amount?: number;
+}
+/** The three noise colors: white is flat, pink falls 3 dB an octave, brown 6. */
+type NoiseColor = 'white' | 'pink' | 'brown';
+/** A pitch sweep from the note's own pitch. */
+interface Glide {
+    to: Pitch;
+    /** Default: the note's `duration`, or 100 ms for a held note. */
+    ms?: number;
+    /** Default 'exponential', which moves evenly in pitch; 'linear' moves evenly
+     *  in hertz. */
+    curve?: 'linear' | 'exponential';
+}
+/** The timbre of a note, apart from its pitch — spread one into several
+ *  `playNote` calls to reuse it. */
+interface SynthPatch {
+    /** Default 'sine'. */
+    wave?: Waveform;
+    envelope?: Envelope;
+    glide?: Glide;
+    filter?: VoiceFilter;
+}
+/** Options for `AudioEngine.playNote`. Routing, level, position, timing and
+ *  `cancelKey` mean what they mean for `play()`. */
+interface NoteOptions extends SynthPatch, Omit<PlayOptions, 'rate' | 'loop'> {
+    pitch: Pitch;
+    /** Gate length in ms: how long the note sounds before its release begins.
+     *  Omit to hold it until `release()`. */
+    duration?: number;
+}
+/** The timbre of a noise voice — spread one into several `playNoise` calls to
+ *  reuse it. */
+interface NoisePatch {
+    noise: NoiseColor;
+    envelope?: Envelope;
+    filter?: VoiceFilter;
+}
+/** Options for `AudioEngine.playNoise`. Everything but the source means what it
+ *  means for `playNote`; `rate` and `detune` retune the looping noise buffer,
+ *  which shifts a pink or brown noise's color, and leave the filter where it is. */
+interface NoiseOptions extends NoisePatch, Omit<PlayOptions, 'loop'> {
+    /** Gate length in ms. Omit to hold the noise until `release()`. */
+    duration?: number;
+}
+/**
+ * Options for `AudioEngine.stream`. Routing, level, position, `rate`, `loop`,
+ * `cancelKey` and `onDone` mean what they mean for `play()`, with these
+ * differences, all from playing through a media element rather than a buffer:
+ *
+ * - No `when`: the element starts once it has buffered enough, which is not
+ *   sample-accurate and cannot be booked against the audio clock.
+ * - No `detune`, and `setDetune` does nothing. `rate` is the element's
+ *   `playbackRate`, which keeps pitch unless the element's `preservesPitch`
+ *   is false.
+ * - The stream counts toward its bus's voice limit and can be stolen like any
+ *   voice — give music a bus of its own.
+ */
+interface StreamOptions extends Omit<PlayOptions, 'when' | 'detune'> {
+    /** Where to start, in ms into the media. Default: wherever the element is. */
+    offset?: number;
+    /** Set on an element made from a URL. A cross-origin URL needs CORS and
+     *  `'anonymous'`, or the graph receives silence. */
+    crossOrigin?: '' | 'anonymous' | 'use-credentials';
+}
+/** Options for `createAudioEngine`. */
 interface AudioEngineOptions {
     /** Injectable for tests and for consumers that own the context. */
     context?: AudioContext;
@@ -188,8 +424,13 @@ interface AudioEngineOptions {
      *  replaces the default, and the missing half falls back to `setTimeout`'s. */
     setTimer?: (cb: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
+    /** Crossfade for every insert-chain edit and bypass, in ms. Default 15. */
+    insertFadeMs?: number;
 }
 
+/** A sound engine: named mix buses, a per-bus voice pool, lookahead
+ *  scheduling and 2D spatialization over one `AudioContext`. Times are engine
+ *  ms (`now()`). */
 interface AudioEngine {
     /** The engine's `AudioContext` — the one passed as `options.context`, or the
      *  one the engine created. Use it for `createBuffer`, for analysis, or for a
@@ -211,6 +452,25 @@ interface AudioEngine {
      *  recording. `load` and `decode` both assume encoded bytes. */
     register(buffer: AudioBuffer): SoundHandle;
     play(sound: SoundHandle, opts?: PlayOptions): VoiceHandle;
+    /** Play a synthesized note: an oscillator with harmonic partials, or summed
+     *  sines at any ratios, under an ADSR envelope and an optional filter. It is a voice like any other — same handle, same bus pool
+     *  and stealing, same `cancelKey`. */
+    playNote(note: NoteOptions): VoiceHandle;
+    /** Play noise — white, pink or brown, from a looping buffer made once per
+     *  context — under an envelope and an optional filter with its own cutoff
+     *  envelope. A voice like `playNote`'s in every other respect. */
+    playNoise(noise: NoiseOptions): VoiceHandle;
+    /** Stream long audio — music, ambience — from a media element or a URL
+     *  through a `MediaElementAudioSourceNode`, instead of decoding it whole. It
+     *  is a voice on a bus like any other, with the exceptions `StreamOptions`
+     *  lists. An element has one playhead, so streaming one that is already
+     *  streaming stops the earlier voice. */
+    stream(media: HTMLMediaElement | string, opts?: StreamOptions): VoiceHandle;
+    /** Book a callback against the audio clock through the engine's lookahead
+     *  scheduler; it receives its own `when` to hand on to `play` or `playNote`.
+     *  `stopKey(key)` cancels it. One that came due during a suspension fires
+     *  late on resume, with its original `when`, so compare against `now()`. */
+    schedule(when: number, fire: (when: number) => void, key?: string): void;
     stopKey(key: string): void;
     stopAll(): void;
     bus(name: string): BusHandle;
@@ -223,8 +483,92 @@ interface AudioEngine {
     setListener(p: Vec2, opts?: SpatialOptions): void;
     dispose(): void;
 }
+/**
+ * Create an engine. Browsers start the context suspended: `play()` before it
+ * is unlocked drops the voice with a warning. The engine resumes it on the
+ * first pointer, key or touch gesture, or call `unlock()` from one. Call
+ * `dispose()` when done.
+ */
 declare function createAudioEngine(opts?: AudioEngineOptions): AudioEngine;
 
+interface FilterEffectOptions {
+    /** Default 'lowpass'. */
+    type?: BiquadFilterType;
+    /** Hz. Default 350, the node's own. */
+    frequency?: number;
+    Q?: number;
+    /** dB, for the shelf and peaking types. */
+    gain?: number;
+}
+interface FilterEffect extends InsertEffect {
+    readonly filter: BiquadFilterNode;
+}
+/** A `BiquadFilterNode`. Write its params through `filter` to sweep it. */
+declare function createFilterEffect(ctx: BaseAudioContext, opts?: FilterEffectOptions): FilterEffect;
+/** A wet/dry mix around an effect, for the effects whose output replaces
+ *  rather than colors the signal. */
+interface WetDryMix {
+    /** 0 is all dry, 1 all wet. */
+    mix(): number;
+    setMix(mix: number, rampMs?: number): void;
+}
+interface ReverbEffectOptions {
+    /** The room: an impulse response, loaded or synthesized like any buffer. */
+    impulse: AudioBuffer;
+    /** Default 0.3. */
+    mix?: number;
+    /** Scale the impulse to a consistent level. Default true, the node's own. */
+    normalize?: boolean;
+}
+interface ReverbEffect extends InsertEffect, WetDryMix {
+    readonly convolver: ConvolverNode;
+}
+/** Convolution reverb from an impulse buffer, with a wet/dry mix. */
+declare function createReverbEffect(ctx: BaseAudioContext, opts: ReverbEffectOptions): ReverbEffect;
+interface DelayEffectOptions {
+    /** ms. Default 250. */
+    time?: number;
+    /** How much of each repeat feeds the next, -1..1 exclusive. Default 0.35. */
+    feedback?: number;
+    /** Default 0.35. */
+    mix?: number;
+    /** The longest `time` the line can be set to later, ms. Default the larger
+     *  of 1000 and `time`. */
+    maxTime?: number;
+}
+interface DelayEffect extends InsertEffect, WetDryMix {
+    readonly delay: DelayNode;
+    setTime(ms: number, rampMs?: number): void;
+    feedback(): number;
+    setFeedback(value: number, rampMs?: number): void;
+    /** Break the feedback loop. Called for you when the slot is removed. */
+    dispose(): void;
+}
+/** A feedback delay with a wet/dry mix. Ramping `setTime` bends the pitch of
+ *  the repeats while it moves, as a tape delay does. */
+declare function createDelayEffect(ctx: BaseAudioContext, opts?: DelayEffectOptions): DelayEffect;
+interface CompressorEffectOptions {
+    /** dB. */
+    threshold?: number;
+    /** dB. */
+    knee?: number;
+    ratio?: number;
+    /** ms. */
+    attack?: number;
+    /** ms. */
+    release?: number;
+    /** Linear gain after the compressor, to win back the level it takes. Default 1. */
+    makeup?: number;
+}
+interface CompressorEffect extends InsertEffect {
+    readonly compressor: DynamicsCompressorNode;
+    readonly makeup: GainNode;
+}
+/** A `DynamicsCompressorNode` into a makeup gain. Unset options keep the
+ *  node's defaults. */
+declare function createCompressorEffect(ctx: BaseAudioContext, opts?: CompressorEffectOptions): CompressorEffect;
+
+/** Clock and timer for `createScheduler`. */
 interface SchedulerOptions {
     /** Engine time in ms. Backed by `AudioContext.currentTime * 1000` in production. */
     now: () => number;
@@ -237,6 +581,7 @@ interface SchedulerOptions {
     /** Time between passes, in ms. Default 25. */
     interval?: number;
 }
+/** A queue of callbacks keyed to engine time. See `createScheduler`. */
 interface Scheduler {
     start(): void;
     /** Stop the timer. The queue survives; `clear()` empties it. */
@@ -270,6 +615,7 @@ interface Scheduler {
  */
 declare function createScheduler(opts: SchedulerOptions): Scheduler;
 
+/** The timer pair `createTickTimer` returns, shaped for `SchedulerOptions`. */
 interface TickTimer {
     /** One-shot, as `createScheduler` expects. */
     setTimer(cb: () => void, ms: number): unknown;
@@ -286,4 +632,97 @@ interface TickTimer {
  */
 declare function createTickTimer(): TickTimer;
 
-export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, type BusGraph, type BusHandle, type PlayOptions, type Scheduler, type SchedulerOptions, type SoundCache, type SoundHandle, type SpatialOptions, type StealPolicy, type TickTimer, type Vec2, type VoiceHandle, type VoicePool, type VoicePoolOptions, type VoiceRecord, createAnalyserTap, createAudioEngine, createBusGraph, createScheduler, createSoundCache, createTickTimer, createVoicePool, spatialize };
+/** A synth note on a step. `length` is its gate in steps, default 1. */
+interface PatternNote extends Omit<NoteOptions, 'when' | 'duration'> {
+    step: number;
+    length?: number;
+}
+/** Noise on a step: a hi-hat, a snare's rattle. `length` is its gate in steps,
+ *  default 1. */
+interface PatternNoise extends Omit<NoiseOptions, 'when' | 'duration'> {
+    step: number;
+    length?: number;
+}
+/** A buffer played on a step: a drum hit, a sample. */
+interface PatternHit extends Omit<PlayOptions, 'when'> {
+    step: number;
+    sound: SoundHandle;
+}
+type PatternEvent = PatternNote | PatternNoise | PatternHit;
+/** Options for `createPatternPlayer`. */
+interface PatternPlayerOptions {
+    /** Beats per minute. */
+    tempo: number;
+    /** Steps per beat. Default 4, so a step is a sixteenth note in 4/4. */
+    stepsPerBeat?: number;
+    events?: readonly PatternEvent[];
+    /** Steps in one pass. Default: through the last event, rounded up to a whole
+     *  beat. */
+    length?: number;
+    /** Default true. */
+    loop?: boolean;
+    /** Called as each step is booked — up to a lookahead ahead of it sounding —
+     *  with its index in the pattern and its engine time in ms. */
+    onStep?: (step: number, when: number) => void;
+}
+/** A running sequence of steps. See `createPatternPlayer`. */
+interface PatternPlayer {
+    /** Start from step 0 at engine time `when`, default now. No-op while playing. */
+    start(when?: number): void;
+    /** Book nothing further, and release every voice the player started. */
+    stop(): void;
+    playing(): boolean;
+    tempo(): number;
+    /** Takes effect from the next step not yet booked. */
+    setTempo(bpm: number): void;
+    /** Takes effect from the next step not yet booked. */
+    setEvents(events: readonly PatternEvent[], length?: number): void;
+}
+/**
+ * A step sequencer over `engine`. Each step is one `engine.schedule` booking;
+ * when it fires, it books that step's events at the step's exact time and then
+ * books the step after it. So nothing is booked further ahead than the
+ * scheduler's lookahead, which is what lets a tempo change or new events land
+ * on the very next step.
+ *
+ * A step that fires more than a step late — a stalled timer, a suspended
+ * context — skips to the next step still ahead of the clock, keeping phase,
+ * rather than playing the missed ones at once.
+ */
+declare function createPatternPlayer(engine: AudioEngine, opts: PatternPlayerOptions): PatternPlayer;
+
+/** Samples of `color` noise, seeded so every context gets the same loop. The
+ *  end is pulled onto the start, so the loop point does not click. */
+declare function noiseSamples(color: NoiseColor, length: number): Float32Array;
+/**
+ * Ready-made inharmonic waves. The ratios are the textbook modes of each
+ * object; the levels and decays are a starting point to spread and adjust.
+ */
+declare const partialPresets: {
+    /** A church bell's hum, prime, tierce, quint and nominal, and above. */
+    bell: {
+        partials: {
+            ratio: number;
+            gain: number;
+            decay: number;
+        }[];
+    };
+    /** A tuned bar: its overtones sit near 4 and 10 times the fundamental and die fast. */
+    marimba: {
+        partials: {
+            ratio: number;
+            gain: number;
+            decay: number;
+        }[];
+    };
+    /** Struck sheet metal: modes nowhere near the harmonic series. */
+    metal: {
+        partials: {
+            ratio: number;
+            gain: number;
+            decay: number;
+        }[];
+    };
+};
+
+export { type Acquisition, type AnalyserTap, type AnalyserTapOptions, type AudioEngine, type AudioEngineOptions, type BusGraph, type BusGraphOptions, type BusHandle, type CompressorEffect, type CompressorEffectOptions, type DelayEffect, type DelayEffectOptions, type Envelope, type EnvelopePoint, type FilterEffect, type FilterEffectOptions, type Glide, type Inharmonic, type InsertAddOptions, type InsertChain, type InsertChainOptions, type InsertEffect, type InsertSlot, type NoiseColor, type NoiseOptions, type NoisePatch, type NoteOptions, type PatternEvent, type PatternHit, type PatternNoise, type PatternNote, type PatternPlayer, type PatternPlayerOptions, type Pitch, type PlayOptions, type ResolvedEnvelope, type ReverbEffect, type ReverbEffectOptions, type Scheduler, type SchedulerOptions, type SoundCache, type SoundHandle, type SpatialOptions, type StealPolicy, type StreamOptions, type SynthPartial, type SynthPatch, type TickTimer, type Vec2, type VoiceFilter, type VoiceHandle, type VoicePool, type VoicePoolOptions, type VoiceRecord, type Waveform, type WetDryMix, createAnalyserTap, createAudioEngine, createBusGraph, createCompressorEffect, createDelayEffect, createFilterEffect, createPatternPlayer, createReverbEffect, createScheduler, createSoundCache, createTickTimer, createVoicePool, envelopeLevel, envelopePoints, midiToFrequency, noiseSamples, noteToMidi, partialPresets, resolveEnvelope, spatialize, toFrequency };