> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audx.site/llms.txt
> Use this file to discover all available pages before exploring further.

# React API reference: useSound, SoundProvider and hooks

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

```tsx theme={null}
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.

```tsx theme={null}
<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

```ts theme={null}
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.

```tsx theme={null}
import { click } from "@/sounds";

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

## useSequence

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

Stable `play` and `stop` callbacks for a [sequence](https://docs.audx.site/reference/core-api.md#definesequence). `play` stops any run already in progress before starting.

## usePatch

```ts theme={null}
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.

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

## useAnalyser

```ts theme={null}
function useAnalyser(opts?: AnalyserOptions): AudioAnalyser
```

Creates an analyser on the master bus once, and disposes it on unmount. See [analysis](https://docs.audx.site/reference/core-api.md#analysis) for the members, and [Use with React](https://docs.audx.site/guides/react.md#visualize-output) for an example.

## useListener

```ts theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.