webaudio-kit
Documentation

Install, wrap, play, stop.

The first release is deliberately small: it proves safe tone playback, frequency sweeps, volume control, and analyser output for React applications.

Start

Install the packages.

Install both packages in app projects so React hooks and core helpers resolve explicitly.

package install
pnpm add @webaudio-kit/react @webaudio-kit/core

Provider

Put AudioProvider around the part of the app that owns playback controls. The provider creates the audio context only after a hook needs playback, resumes it from user-initiated handlers, and keeps default master gain at 0.2.

provider setup
import { AudioProvider } from "@webaudio-kit/react";

export function Root() {
  return (
    <AudioProvider>
      <AppControls />
    </AudioProvider>
  );
}

Tone hook

useTone returns stable play, stop, and isPlaying controls. A play call creates a fresh oscillator, gain node, and pan node, then cleans them up when stopped.

tone control
const tone = useTone({
  frequency: 440,
  gain: 0.15,
  type: "sine",
  pan: 0,
});

await tone.play({ durationMs: 500 });
tone.stop();

Sweep hook

useFrequencySweep clamps both frequency endpoints and schedules an exponential ramp from from to to. Keep sweep controls conservative in demos.

sweep control
const sweep = useFrequencySweep({
  from: 250,
  to: 8000,
  durationMs: 2400,
  gain: 0.12,
});

await sweep.play();
sweep.stop();

Core helpers

AudioProvider

Creates AudioContext lazily, owns master gain, connects analyser, and exposes audio state to hooks.

useTone

Plays one oscillator with optional gain, pan, waveform, and duration controls.

useFrequencySweep

Ramps frequency between two clamped values over a controlled duration.

useAnalyser

Returns the analyser node so UI can render waveform or spectrum data.

math helpers
import { clampFrequency, dbToGain, gainToDb } from "@webaudio-kit/core";

const frequency = clampFrequency(inputFrequency); // 20..20000 by default
const gain = dbToGain(-14);
const db = gainToDb(0.2);

Browser behavior

Autoplay noteBrowsers may block audio until the user clicks, taps, or presses a key. Call play from a user action and let the provider resume the context there.
Safety noteKeep default volume low, clamp frequencies, and avoid medical or audiology claims unless a separate certified system validates the whole product.

More docs

The repository also keeps source Markdown docs for API details, safety, browser behavior, deployment, testing, and performance.