Public API reference.

function AudioProvider(props: AudioProviderProps): JSX.Element;

type AudioProviderProps = {
  children: ReactNode;
  initialGain?: number;
};

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

export function App() {
  return (
    <AudioProvider initialGain={0.2}>
      <AudioControls />
    </AudioProvider>
  );
}

function useAudioContext(): AudioProviderValue;

type AudioProviderValue = {
  audioContext: AudioContext | null;
  masterGain: GainNode | null;
  analyser: AnalyserNode | null;
  state: AudioContextState | "idle";
  gain: number;
  ensureAudioContext(): Promise<AudioRuntime>;
  setGain(gain: number): Promise<void>;
  stopAll(): void;
};

import { useAudioContext } from "@webaudio-kit/react";

function AudioStateControls() {
  const audio = useAudioContext();

  return (
    <>
      <span>{audio.state}</span>
      <button onClick={() => audio.stopAll()}>Stop all</button>
    </>
  );
}

function useAudioUnlock(): AudioUnlockControls;

type AudioUnlockControls = {
  unlock(): Promise<AudioRuntime>;
  status: "idle" | "unlocking" | "suspended" | "running" | "closed" | "error";
  state: AudioContextState | "idle";
  isUnlocked: boolean;
  isUnlocking: boolean;
  error: Error | null;
};

import { useAudioUnlock } from "@webaudio-kit/react";

function EnableAudioButton() {
  const audio = useAudioUnlock();

  return (
    <>
      <button disabled={audio.isUnlocked} onClick={() => void audio.unlock()}>
        {audio.isUnlocked ? "Audio enabled" : "Enable Audio"}
      </button>
      <span>{audio.status}</span>
      {audio.error ? <span>unlock failed</span> : null}
    </>
  );
}

function useAudioEngine(): AudioEngineControls;

type AudioEngineControls = AudioProviderValue & {
  playTone(options): Promise<PlaybackHandle>;
  playFrequencySweep(options): Promise<PlaybackHandle>;
  playNoise(options): Promise<PlaybackHandle>;
  withAudioRuntime<T>(
    callback: (runtime: AudioRuntime) => T | Promise<T>,
  ): Promise<T>;
};

import { useAudioEngine } from "@webaudio-kit/react";

function LayeredAlertButton() {
  const engine = useAudioEngine();

  async function playLayeredAlert() {
    await engine.playTone({
      frequency: 880,
      durationMs: 160,
      gain: 0.1,
      type: "square",
    });
    await engine.playNoise({
      durationMs: 120,
      gain: 0.025,
      type: "pink",
    });
  }

  return (
    <>
      <button onClick={() => void playLayeredAlert()}>Play alert</button>
      <button onClick={() => engine.stopAll()}>Stop all</button>
    </>
  );
}

function useTone(): {
  play(options: ToneOptions): Promise<void>;
  stop(): void;
  isPlaying: boolean;
};

function useTone(options: ToneOptions): {
  play(overrides?: Partial<ToneOptions>): Promise<void>;
  stop(): void;
  isPlaying: boolean;
};

import { useTone } from "@webaudio-kit/react";

function AlertCueButton() {
  const tone = useTone();

  return (
    <>
      <button onClick={() => void tone.play({
        frequency: 880,
        durationMs: 120,
        gain: 0.12,
        type: "square",
        envelope: { attackMs: 8, releaseMs: 45 },
        filter: { frequency: 1800, q: 0.7 },
        pattern: { repeat: 3, gapMs: 90 },
        voices: { count: 2, spreadCents: 10 },
      })}>
        Play alert cue
      </button>
      <button onClick={tone.stop}>Stop</button>
    </>
  );
}

function useFrequencySweep(): {
  play(options: FrequencySweepOptions): Promise<void>;
  stop(): void;
  isPlaying: boolean;
};

function useFrequencySweep(options: FrequencySweepOptions): {
  play(overrides?: Partial<FrequencySweepOptions>): Promise<void>;
  stop(): void;
  isPlaying: boolean;
};

import { useFrequencySweep } from "@webaudio-kit/react";

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

  return <button onClick={() => void sweep.play()}>Run sweep</button>;
}

function useNoise(): {
  play(options: NoiseOptions): Promise<void>;
  stop(): void;
  isPlaying: boolean;
};

function useNoise(options: NoiseOptions): {
  play(overrides?: Partial<NoiseOptions>): Promise<void>;
  stop(): void;
  isPlaying: boolean;
};

import { useNoise } from "@webaudio-kit/react";

function NoiseButton() {
  const noise = useNoise({
    type: "pink",
    durationMs: 800,
    gain: 0.08,
  });

  return <button onClick={() => void noise.play()}>Play pink noise</button>;
}

function useVolume(): {
  gain: number;
  setGain(gain: number): Promise<void>;
};

import { useVolume } from "@webaudio-kit/react";

function VolumeSlider() {
  const volume = useVolume();

  return (
    <input
      max={0.5}
      min={0}
      onChange={(event) => void volume.setGain(event.currentTarget.valueAsNumber)}
      step={0.01}
      type="range"
      value={volume.gain}
    />
  );
}

function useVolumeControl(options?: VolumeControlOptions): VolumeControlControls;

type VolumeControlOptions = {
  defaultGain?: number;
  label?: string;
  maxGain?: number;
  minGain?: number;
  step?: number;
  storageKey?: string;
};

type VolumeControlControls = {
  gain: number;
  db: number;
  inputProps: VolumeControlInputProps;
  resetGain(): Promise<void>;
  setGain(gain: number): Promise<void>;
};

import { useVolumeControl } from "@webaudio-kit/react";

function ControlledVolumeSlider() {
  const volume = useVolumeControl({
    label: "Master volume",
    maxGain: 0.5,
    storageKey: "app-master-gain",
  });

  return (
    <>
      <input {...volume.inputProps} />
      <span>{volume.gain.toFixed(2)}</span>
      <button onClick={() => void volume.resetGain()}>Reset volume</button>
    </>
  );
}

function useAnalyser(): AnalyserNode | null;

import { useAnalyser } from "@webaudio-kit/react";

function Meter() {
  const analyser = useAnalyser();

  if (!analyser) {
    return <span>Idle</span>;
  }

  return <span>{analyser.fftSize} point analyser</span>;
}

function WaveformCanvas(props: WaveformCanvasProps): JSX.Element;

type WaveformCanvasProps = Omit<
  CanvasHTMLAttributes<HTMLCanvasElement>,
  "children"
> & {
  backgroundColor?: string;
  idleStrokeColor?: string;
  lineWidth?: number;
  strokeColor?: string;
};

import { WaveformCanvas } from "@webaudio-kit/react";

function Signal() {
  return (
    <WaveformCanvas
      aria-label="Waveform analyser"
      height={180}
      idleStrokeColor="#394135"
      lineWidth={2}
      strokeColor="#c8ea3a"
      style={{ width: "100%", height: 140 }}
      width={720}
    />
  );
}

function SpectrumCanvas(props: SpectrumCanvasProps): JSX.Element;

type SpectrumCanvasProps = Omit<
  CanvasHTMLAttributes<HTMLCanvasElement>,
  "children"
> & {
  backgroundColor?: string;
  barColor?: string;
  barCount?: number;
  barGap?: number;
  idleBarColor?: string;
  minBarHeight?: number;
};

import { SpectrumCanvas } from "@webaudio-kit/react";

function Spectrum() {
  return (
    <SpectrumCanvas
      aria-label="Spectrum analyser"
      backgroundColor="#10110f"
      barColor="#8ed8ff"
      barCount={48}
      barGap={2}
      height={140}
      idleBarColor="#394135"
      minBarHeight={2}
      style={{ width: "100%", height: 120 }}
      width={720}
    />
  );
}

function useAudioTestMode(options?: AudioTestModeOptions): AudioTestModeControls;

type AudioTestModeOptions = {
  gapMs?: number;
  steps?: AudioTestModeStep[];
};

type AudioTestModeControls = {
  currentStep: AudioTestModeStep | null;
  currentStepIndex: number;
  isRunning: boolean;
  previewStep: AudioTestModeStep | null;
  previewStepIndex: number;
  run(): Promise<void>;
  stop(): void;
  steps: AudioTestModeStep[];
};

import { useAudioTestMode } from "@webaudio-kit/react";

function AudioSelfCheck() {
  const testMode = useAudioTestMode();

  return (
    <>
      <button onClick={() => void testMode.run()}>Run test</button>
      <button onClick={testMode.stop}>Stop</button>
      <span>{testMode.previewStep?.label ?? "Idle"}</span>
    </>
  );
}