React API reference: useSound, SoundProvider and hooks

API reference for @litlab/audx/react: SoundProvider, useSound, useSequence, usePatch, useAnalyser and useListener.

import { SoundProvider, useSound } from "@litlab/audx/react";

Requires React 18 or later. The module is marked "use client".

Hooks that play audio (useSound, useSequence, usePatch) do nothing when the nearest SoundProvider is disabled, or when the user prefers reduced motion. They work without a provider, using enabled: true and volume: 1.

SoundProvider

Controls sound for every hook below it.

<SoundProvider enabled={soundsOn} volume={0.8}>
  <App />
</SoundProvider>

enabled · boolean · default: "true"

Whether sounds may play.

volume · number · default: "1"

Volume multiplier for every sound, 0 to 1. Multiplied with each sound’s own volume option.

onEnabledChange · (enabled: boolean) => void

Reserved for a future hook that changes the setting from inside the tree. No public API calls it yet; manage enabled with your own state.

onVolumeChange · (volume: number) => void

Reserved, like onEnabledChange.

useSound

function useSound(sound: Sound | SoundDefinition, opts?: PlayOptions): () => VoiceHandle | undefined

Returns a callback that plays the sound. The callback is stable across renders and always uses the latest sound, opts and provider state. It returns undefined when playback is skipped.

import { click } from "@/sounds";

const play = useSound(click, { volume: 0.7 });
<button onClick={play}>Save</button>;

useSequence

function useSequence(steps: SequenceStep[], options?: { loop?: boolean; duration?: number }): {
  play: () => void;
  stop: () => void;
}

Stable play and stop callbacks for a sequence. play stops any run already in progress before starting.

usePatch

function usePatch(source: string | SoundPatch): AudioPatch

Loads a theme from a URL, or wraps an in-memory theme object. Until a URL finishes loading, it returns an empty patch with ready: false whose play does nothing. Load errors are swallowed, so the empty patch stays in place.

const ui = usePatch("/themes/brand.json");
<button onClick={() => ui.play("click")} disabled={!ui.ready}>Save</button>;

useAnalyser

function useAnalyser(opts?: AnalyserOptions): AudioAnalyser

Creates an analyser on the master bus once, and disposes it on unmount. See analysis for the members, and Use with React for an example.

useListener

function useListener(listener: Listener): void

Keeps the 3D audio listener in sync with the given position and orientation. It only updates when one of the numbers changes, so passing a new object each render is fine.