API

A Bus is a named mix bucket with its own gain stage, optional FX inserts, a voice-concurrency limit, and an optional sidechain key. Voices are connected to bus.input. The master receives bus.output. level/mute use 10ms ramps to avoid clicks; raw gain.value writes would pop audibly on browsers that don't smooth the parameter.

Dynamics compressor as a bus FX insert. Wraps DynamicsCompressorNode and a make-up gain node, and exposes

Sidechain ducker. Inserts on the *target* bus (e.g. music) and listens to the level of a source bus (e.g. voice). When the source is loud, the target's gain drops; when quiet, it returns. Implementation: an envelope follower running on the source bus's RMS, driving an additional gain node spliced into the target's FX chain. The envelope follower runs on the main thread at ~60 Hz — fine for a speech ducker, not for sample-accurate audio-rate sidechaining. For that, use a custom AudioWorklet (planned).

Common FX insert contract. Every FX exposes a single input + a single output node so the bus can splice it into the (fxInput → output) hop.

The Master stage. Headroom-aware gain into an optional brick-wall limiter, then to destination. Buses connect their output to master.input. Headroom is a static gain offset; the limiter is a fast-attack DynamicsCompressorNode that catches peaks the headroom can't tame when heavy FX stack on top of busy mixes.

A named float you can drive at runtime. Set it from anywhere; subscribers (bus levels, FX wet, voice gain) update immediately. Bind a target to a parameter with

Convolution reverb. Mixes a dry signal with a wet path that runs through a ConvolverNode. If no impulse response is provided, a synthetic noise decay is generated — quick and free, but not as nice as a real IR.

A captured mix-state preset. Capture it once with the engine in a known good state ("menu mood"), then

A loaded sample — owns one decoded AudioBuffer, spawns Voices on play(). Sound is created via engine.loadSound() / bank load; constructor is package-private.

PannerNode wrapper. Inserted between a Voice and its Bus when a play call passes a

One buffer, many named regions, one fetch. Use for cascades, UI variants, low-latency one-shots — anything where the cost of N separate decodes outweighs the cost of N region offsets into a single buffer. Built on top of an underlying Sound (the buffer); regions are cooperative — overlapping regions just produce overlapping voices.

Stream a long media file through HTMLAudioElement → MediaElementAudioSource. Use for music tracks > 30s where decoding the whole file into RAM (the loadSound path) would waste memory and stall on iOS. The element handles progressive download and seek; we just route its output into the engine's bus graph so it picks up the same FX/sidechain as buffer-based voices. Created lazily — the underlying MediaElementAudioSource is only built on first play(), since it can't be reattached to a different bus once created.

Pitch-preserving time-stretch via overlap-add granular synthesis with cross-correlation alignment (a SOLA-style approximation). Used to render an offline stretched copy of an AudioBuffer at load time — not realtime. For realtime tempo control, see the (planned) AudioWorklet implementation. stretchFactor > 1 = play faster (shorter buffer). stretchFactor < 1 = not currently supported (use rate via PlaybackRate).

One playback instance, returned from sound.play(). Owns its source node and gain stage; disposes itself on natural end, signal abort, or stop(). Voice constructor is package-private — callers obtain instances via Sound.play().

Common FX insert contract. Every FX exposes a single input + a single output node so the bus can splice it into the (fxInput → output) hop.

RMS-based loudness normalization on a decoded AudioBuffer.

Codec capability + asset-source picking. Recommended encoding pipeline: - Primary: WebM/Opus — smallest, best quality/byte, supported in Chrome, Firefox, Edge, and Safari 14.1+ on macOS / iOS 17+. - Fallback: AAC in M4A — required for older iOS Safari (≤16) and older macOS Safari without Opus support. Ship both; pickSource() returns the first URL the browser can decode. canPlay() uses HTMLAudioElement.canPlayType — it gives a sound (no pun intended) prediction without actually fetching anything. The Web Audio decoder will accept anything HTMLAudioElement says it can play, plus a few extras (uncompressed WAV always works), so canPlay is conservative.