Skip to content
bard logoBardUtilities
Lifecycle-owned Web Audio mixing: buses with ducking, buffered SFX and sprites, procedural synth, streamed tracks, and crossfading music decks
Version
v26.11.20
Size
6.8 KB gzip
Dependencies
Zero dependencies
BrowserNode ≥22
createBardBardErrorBardLoadError

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.

ts
// 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
FeatureNative Web AudioBardHowler.js
Bundle size0 B6.8 KB~30 kB
Root dependencies
LifecycleManual node teardowndispose() + Symbol.disposePer-sound unload
MixingHand-built gain graphNamed buses, ducking rules, voice capsPer-sound volume only
Music transitionsManual crossfade schedulingdeck.transition() with loop points, queueNot 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 ​

sh
pnpm add @vielzeug/bard
sh
npm install @vielzeug/bard
sh
yarn add @vielzeug/bard

Quick 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.

ts
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.