Skip to content

API Overview ​

SymbolPurposeExecutionCommon gotcha
createBardCreates the disposable audio engineSyncContext is still created lazily on first audio use
BardErrorBase error for invalid keys, buses, regions—Subclasses: BardLoadError, BardDisposedError, BardUnsupportedError
BardLoadErrorA manifest entry failed to fetch or decode—Original failure is in cause
BardDisposedErrorA method ran after dispose()—Thrown by every engine method except dispose
BardUnsupportedErrorNo AudioContext in the runtime—unlock() rejects with it on servers without Web Audio

Package Entry Point ​

ImportPurpose
@vielzeug/bardComplete public Bard API
@vielzeug/bard/testingDeterministic Web Audio fakes for tests

Engine ​

createBard ​

ts
function createBard(options?: BardOptions): Bard;

Creates the engine. Touches no browser global until the first method that needs audio.

OptionTypeDefaultNotes
busesreadonly string[]['music', 'sfx', 'voice']'master' is reserved and throws if declared
volumenumber1Master volume, linear 0..1
duckingreadonly DuckingRule[][]See Ducking
maxVoicesnumber32Engine-wide concurrent voice cap
autoUnlockbooleantrueGesture listeners resume a suspended context
autoSuspendOnHiddenbooleanfalseSuspend on page hide, resume on show (only resumes its own suspends)
context() => AudioContextlazy new AudioContext()Injection seam for tests; injected contexts are never closed by dispose()

Returns the Bard engine.

ts
import { createBard } from '@vielzeug/bard';

const bard = createBard({ volume: 0.9 });

Bard ​

MemberSignatureNotes
state'idle' | 'suspended' | 'running' | 'interrupted' | 'closed''idle' until first lazy context creation; 'interrupted' occurs on iOS calls
contextAudioContext | nullNative context for advanced graph work
unlock()() => Promise<void>Creates and resumes the context
load(manifest, options?)(AssetManifest, { signal? }) => Promise<void>Deduplicates concurrent fetches per URL
unload(keys?)(string | readonly string[]) => voidStops active voices for the dropped keys
has(key)(string) => booleanResolves 'key:sprite' to its parent asset
play(key, options?)(string, PlayOptions?) => SoundHandleThrows BardError for unknown keys and streamed assets
synth(options)(SynthOptions) => SoundHandleProcedural voice, self-cleaning
bus(name)(string) => BusController'master' is valid; unknown names throw
createDeck(options?)(DeckOptions?) => MusicDeckMultiple decks share the engine
suspend() / resume()() => Promise<void>Engine-wide pause for the whole context
tap(handler, options?)(BardEvent) => void → unsubscribeHandler errors are swallowed; auto-detaches on signal
dispose()() => voidStops voices and decks, aborts loads, removes listeners, closes an owned context; idempotent
disposed / disposalSignalboolean / AbortSignalStandard disposal contract

Playback ​

SoundHandle ​

Returned by play() and synth().

MemberSignatureNotes
stop(options?)(FadeOptions?) => voidFades (default 15 ms micro-fade) then stops
setVolume(volume, options?)(number, FadeOptions?) => voidRamped, never clicks
setPan(pan)(-1..1) => voidEvery voice has a panner
finishedPromise<void>Resolves on natural end, stop, or dispose
dispose() / disposed / [Symbol.dispose]Immediate stop and node release

PlayOptions ​

OptionTypeDefaultNotes
busstring'sfx'Destination bus
volumenumber1Linear 0..1
pannumber0-1..1; voices always route via a panner
loopbooleanfalseLoops the buffer or sprite region
loopStart / loopEndnumber—Absolute buffer seconds
offsetnumber0Start offset in seconds
detunenumber | [min, max]—Cents; ranges sampled per voice
ratenumber | [min, max]—Playback rate; shifts pitch on buffers
maxVoicesnumber—Per-key cap; oldest copy is stolen
fadeInnumber—Seconds from 0 to volume
random() => numberMath.randomDeterministic sampling in tests

SynthOptions ​

OptionTypeDefaultNotes
type'sine' | 'square' | 'sawtooth' | 'triangle' | 'noise''sine''noise' uses a cached white-noise buffer
freqnumber | [from, to]440Tuple sweeps exponentially; maps to filter cutoff for 'noise'
durationnumber0.3Total seconds including release; must be positive
envelopeSynthEnvelope{ attack: 0.005, decay: 0.05, sustain: 0.6, release: 0.1 }ADSR; sustain is a level
filterSynthFilter—Biquad stage before the envelope
bus / volume / pan / detuneas in PlayOptions

Mixing ​

DuckingRule ​

ts
interface DuckingRule {
  readonly source: string;
  readonly target: string;
  readonly gain: number; // duck level, linear 0..1
  readonly attack?: number; // seconds, default 0.2
  readonly release?: number; // seconds, default 0.8
}

While the source bus has active voices, target ramps to gain; when they end it ramps back to 1. Multiple rules on one target take the lowest active gain.

BusController ​

MemberNotes
nameBus name
volume / setVolume(v, options?)User volume stage, ramped
muted / mute() / unmute()Ramped mute
duckLevelCurrent duck multiplier (1 = unducked)

Music Deck ​

MusicDeck ​

MemberSignatureNotes
currentstring | nullActive track key
playingbooleanfalse while paused or stopped
transition(key, options?)(string, TransitionOptions?) => voidCrossfades; transitioning to the live key is a no-op
queue(keys, options?)(readonly string[], QueueOptions?) => voidReplaces the queue and starts its first track
next() / previous()() => voidNo-op without a queue
pause() / play()() => voidplay() resumes from the paused offset
stop(options?)(FadeOptions?) => voidStops and clears queue and slot
dispose() / disposed / [Symbol.dispose]Releases a Media Session claim

TransitionOptions: fade, loop, loopStart, loopEnd, offset. QueueOptions: shuffle, crossfade, repeat, random.

DeckOptions ​

OptionTypeDefaultNotes
busstring'music'Destination bus
mediaSessionbooleanfalseClaims navigator.mediaSession; a second claim throws
fadenumber2Default crossfade seconds

Assets ​

AssetManifest ​

ts
type AssetManifest = Readonly<Record<string, string | AssetDefinition>>;

interface AssetDefinition {
  readonly src: string;
  readonly sprites?: Readonly<Record<string, readonly [start: number, duration: number]>>;
  readonly stream?: boolean; // deck-only playback via an owned <audio> element
  readonly meta?: AssetMeta; // Media Session metadata
}

A bare string is shorthand for { src }. Sprite regions are [startSeconds, durationSeconds] and play as 'key:sprite'; out-of-bounds regions throw BardError.


Observability ​

BardEvent ​

EventPayloadFires
statestateContext lifecycle changes
loadkeyA manifest entry finished loading
load-errorkey, errorA load failed
stealkeyA voice was stolen past a cap
duckbus, level, rampA bus duck level changed
trackkey | nullThe deck changed tracks
dispose—Emitted once at the start of dispose()

Testing ​

@vielzeug/bard/testing exports FakeAudioContext (manual clock via advance(seconds), recorded FakeAudioParam automation), FakeMediaElement, FakeMediaSession, and flush(). Inject the fake with createBard({ context: () => fake }).


Errors ​

ErrorTriggerNotes
BardErrorUnknown key/bus/sprite, reserved bus name, streamed-asset misuseBase class
BardLoadErrorFetch or decodeAudioData failurecause carries the original error or { status }
BardDisposedErrorEngine use after dispose()Also BardUnsupportedError when no AudioContext exists