API reference
Public package exports and resource limits.
AudioBits API · 0.2.0 · Available on npm.
Imports use public package exports. audiobits/schema.json supplies structural
recipe JSON Schema; audiobits/capabilities.json supplies this package version's
shipped primitives and browser gate. Semantic limits still require
validateRecipe; sample-rate constraints are checked at playback.
| Export | Responsibility |
|---|---|
createAudio(options?) | Own an engine; defaults: 32 voices, eight per sound, -12 dB master |
defineSound(input) | Author typed recipe data; validate and freeze; throws AudioBitsError |
validateRecipe(input) | Return a recipe or bounded path-specific issues |
recipeSchema | Published recipe schema version 1 |
AudioBitsError | Error with code and validation issues |
Creative recipes live in the copy-owned catalog. Import them from local application files after copying or installing their source.
Public types include Recipe, its layer/source/envelope/filter/value and
parameter types, ValidationResult, RecipeIssue, AudioEngine, AudioOptions,
AudioState, Sound, Voice, PlayOptions, RecipeControls, LiveControls,
and Bus.
Playback options
sound.play({ at, gainDb, pan, parameters, seed, bus }) uses absolute context
time for at; omit it for immediate play. Past times are rejected. Gain is
-60–0 dB, pan is -1–1, and seed is an unsigned 32-bit integer. Future voices
reserve capacity. Invalid options fail before stealing or graph allocation.
Engine and per-sound limits are integers from 1–128. Oldest-voice stealing uses a
5 ms output fade with at most one extra retiring voice. audio.counts separates
active/stopping reservations from retirees. Stopping voices retain capacity until
cleanup; further steals finalize the previous retiree before creating another.
masterGainDb accepts -60–0 dB; playback gain and pan default to 0.
At most 32 buses, including master, may be live.
Errors
AudioBitsError exposes code and validation issues. Invalid recipes use
invalid-recipe; invalid controls use invalid-control and invalid seeds use
invalid-seed. Playback before activation uses not-ready; failed activation
uses retryable start-failed. See Lifecycle for gesture retry
and cleanup. Control updates on a stopped or completed voice use ended-voice.
Guides
Recipes, Lifecycle, Parameters, Buses, and Native interop explain the contracts and cleanup paths.
Defaults provide headroom for the curated sounds; arbitrary recipes, resonance, or concurrency require application-specific signal and listening checks.
Buses provide gain, mute, and routing. Shared effects are deferred until multiple real sound requirements justify an API.