# webaudio-kit

React and TypeScript primitives for browser-safe Web Audio tone tools,
frequency sweeps, noise bursts, volume control, analyser UI, and agent-friendly
documentation. Sound is generated, so there are no audio files to ship.

## When to use

Reach for webaudio-kit when you need to generate audio (beeps, chimes, alerts,
frequency sweeps, shaped noise) or visualize live audio (waveform and spectrum
canvases) without shipping audio assets. To play recorded sound files instead,
use a file-playback library — see the comparison page.

## Hosted docs

- Docs overview: https://webaudio-kit.afaqrashid.com/docs
- API reference: https://webaudio-kit.afaqrashid.com/docs/api
- Hooks vs Core: https://webaudio-kit.afaqrashid.com/docs/hooks-vs-core
- Comparison: https://webaudio-kit.afaqrashid.com/docs/comparison
- Recipes: https://webaudio-kit.afaqrashid.com/docs/recipes
- Examples: https://webaudio-kit.afaqrashid.com/docs/examples
- Framework setup: https://webaudio-kit.afaqrashid.com/docs/frameworks
- Demos: https://webaudio-kit.afaqrashid.com/demos
- Changelog: https://webaudio-kit.afaqrashid.com/changelog

## Markdown docs

- Docs directory: https://github.com/i-afaqrashid/webaudio-kit/tree/main/docs
- Quick start: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/quick-start.md
- API reference: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/api.md
- Hooks vs Core: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/hooks-vs-core.md
- Comparison: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/comparison.md
- Recipes: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/recipes.md
- Browser audio guide: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/browser-audio.md
- Troubleshooting: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/troubleshooting.md
- Agent brief CLI: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/agent-brief.md
- Fetch access note: https://github.com/i-afaqrashid/webaudio-kit/blob/main/docs/fetch-access.md

## Npm packages

- @webaudio-kit/core: https://www.npmjs.com/package/@webaudio-kit/core
- @webaudio-kit/react: https://www.npmjs.com/package/@webaudio-kit/react
- @webaudio-kit/cli: https://www.npmjs.com/package/@webaudio-kit/cli

## Key React hooks

- useTone — play a tone
- useFrequencySweep — sweep between two frequencies
- useNoise — play shaped noise bursts
- useVolumeControl — provider-backed master volume control
- useAnalyser — time- and frequency-domain data for visualizations
- useAudioTestMode — short low-gain diagnostic sequence
- useAudioUnlock — explicit enable-audio control

Canvases: `WaveformCanvas`, `SpectrumCanvas`. Provider: `AudioProvider`.

## Minimal example

```tsx
import { AudioProvider, useTone } from "@webaudio-kit/react";

function ToneButton() {
  const tone = useTone({ frequency: 440 });
  return <button onClick={() => void tone.play()}>Play tone</button>;
}

export function App() {
  return (
    <AudioProvider>
      <ToneButton />
    </AudioProvider>
  );
}
```

## Source and examples

- Repository: https://github.com/i-afaqrashid/webaudio-kit
- Example apps: https://github.com/i-afaqrashid/webaudio-kit/tree/main/examples
- StackBlitz starter: https://webaudio-kit.afaqrashid.com/new

## Scope boundary

webaudio-kit is for browser audio UI, developer tools, demos, and prototypes.
It is not certified medical, audiology, life-safety, or calibrated test
software.