Scope and limitations.

What webaudio-kit is for

Use webaudio-kit when an app needs short browser-generated sounds and React-friendly controls: alert cues, confirmation sounds, test tones, analyser visuals, and conservative volume defaults.

What webaudio-kit is not

It is not a DAW, sampler, sequencer, medical system, Tone.js competitor, or full synthesizer graph. It is also not a custom DSP package for AudioWorklets.

webaudio-kit:
  good fit: safe procedural UI audio
  good fit: React hooks + provider graph
  escape hatch: core primitives and raw Web Audio

not the target:
  full synthesizer graph
  transport / measures / loops
  AudioWorklets
  medical or calibrated hearing tests

When hooks are enough

Start with @webaudio-kit/react hooks when playback belongs to React UI state and the sound fits tone, sweep, noise, volume, analyser, or test-mode behavior.

• Use hooks for stable play, stop, and isPlaying controls.
• Use hooks when visualizers should follow provider output.
• Use hooks when provider stopAll should cancel active cues.
• Use hooks when safe defaults matter more than graph freedom.

When core primitives are enough

Use @webaudio-kit/core when React is not involved or when a small custom graph already owns the AudioContext and destination node.

const context = new AudioContext();
const destination = context.createGain();
destination.connect(context.destination);

const handle = playTone(context, {
  durationMs: 240,
  frequency: 660,
  gain: 0.12,
}, destination);

handle.stop();

When to use raw Web Audio

Use raw Web Audio directly when your product owns complex routing, buses, sends, sidechains, a routing matrix, long-lived node graphs, or scheduling rules that should outlive React components.

When to use Tone.js or a full audio engine

Use Tone.js or another full audio engine when the product needs transport, tempo, synced loops, instruments, samplers, effects chains, modulation matrices, polyphonic note management, or musical scheduling.

Current limitations

The main limits today are no full synthesizer graph, no AudioWorklets, no microphone pipeline, no advanced routing matrix, limited modulation, and a young ecosystem with fewer outside examples than older packages.

The package does include envelopes, patterns, filters, and richer recipes, but those stay focused on short UI cues rather than becoming a general-purpose synth engine.

Decision checklist