Version v26.11.20 Size 6.8 KB gzip Dependencies Zero dependencies
Why Bard?
The Web Audio API gives you nodes and params but no lifecycle: nothing stops voices, removes gesture listeners, or closes the context when your feature unmounts. Bard wraps a lazily created AudioContext in one disposable engine with named buses, ducking, voice caps, and a crossfading music deck.
// Before: hand-rolled graph, listeners, and teardown you must remember
const ctx = new AudioContext();
const source = ctx.createBufferSource();
source.connect(ctx.destination);
// ...who disconnects this on unmount?
// After
const bard = createBard({ ducking: [{ source: 'voice', target: 'music', gain: 0.3 }] });
await bard.load({ confirm: '/confirm.wav' });
bard.play('confirm');
bard.dispose(); // stops voices, removes listeners, closes the context| Feature | Native Web Audio | Bard | Howler.js |
|---|---|---|---|
| Bundle size | 0 B | 6.8 KB | ~30 kB |
| Root dependencies | |||
| Lifecycle | Manual node teardown | dispose() + Symbol.dispose | Per-sound unload |
| Mixing | Hand-built gain graph | Named buses, ducking rules, voice caps | Per-sound volume only |
| Music transitions | Manual crossfade scheduling | deck.transition() with loop points, queue | Not built in |
Use Bard when an interactive app needs owned audio: UI SFX with voice caps, narration that ducks music, or game-state music transitions with crossfades and loop points.
Consider a plain HTMLAudioElement when you need one background track with no mixing, sprites, or lifecycle requirements.
Installation
pnpm add @vielzeug/bardnpm install @vielzeug/bardyarn add @vielzeug/bardQuick Start
Create the engine once per app, load assets, and dispose it when the owning feature unmounts. Nothing touches AudioContext or the DOM until the first call that needs audio, so server rendering is safe.
import { createBard } from '@vielzeug/bard';
const bard = createBard({
ducking: [{ source: 'voice', target: 'music', gain: 0.3 }],
});
await bard.load({
music: { src: '/theme.mp3', stream: true },
dice: { src: '/sfx.wav', sprites: { roll: [0, 1.2] } },
});
const deck = bard.createDeck();
deck.transition('music', { loop: true });
bard.play('dice:roll', { detune: [-60, 60] });
bard.dispose();Features
createBard(): one disposable owner for the context, buses, voices, and decks.bus(): named gain buses (music,sfx,voice) with click-free volume ramps.ducking: declarative rules that ramp a target bus while a source bus has active voices.play(): buffered playback with sprites, voice caps, oldest-first stealing, and detune/rate variance.synth(): zero-asset oscillator and noise voices with ADSR and frequency sweeps.createDeck(): two-slot crossfader with loop points, queue with shuffle, and opt-in Media Session.tap(): observability events for state changes, steals, ducks, and track changes.
Documentation
See Also
- Necromancer: pair visual transitions with deck music transitions from the same game-state change.
- Arsenal: general-purpose utilities used across the monorepo.