# useMasterBus

> A master output bus with a safety limiter: every source connects into one gain node that a single fader governs.

```bash
npx shadcn@latest add @audio-ui/use-master-bus
```

```ts
import { useMasterBus } from "@/hooks/use-master-bus";
```

- Files: `hooks/use-master-bus.ts`
- Depends on: `web-audio`; npm: nothing
- Used by: `block-auto-pan`, `block-bass-enhancer`, `block-binaural-panner`, `block-channel-eq`, `block-chorus`, `block-compander`, `block-compressor`, `block-deesser`, `block-delay`, `block-distortion`, `block-drum-rack`, `block-drum-synth`, `block-ducker`, `block-electric-piano`, `block-equalizer`, `block-exciter`, `block-expander`, `block-filter`, `block-fm-synth`, `block-frequency-shifter`, `block-gate`, `block-graphic-eq`, `block-guitar`, `block-limiter`, `block-lofi`, `block-mid-side`, `block-mono-synth`, `block-multiband`, `block-organ`, `block-overdrive`, `block-phaser`, `block-piano-roll`, `block-pocket-synth`, `block-poly-synth`, `block-redux`, `block-reverb`, `block-rotary`, `block-sampler`, `block-saturator`, `block-string-machine`, `block-stutter`, `block-synth-panel`, `block-tape-keys`, `block-tilt-eq`, `block-transient`, `block-unlimiter`, `block-utility`, `block-vibe`, `block-wah`, `block-wave-shaper`, `pad-demo`, `piano-roll-playback-demo`, `sequencer`, `spectrum-analyzer-demo`

| Export | Kind | What it is |
| --- | --- | --- |
| `useMasterBus` | function | A master output bus: one persistent GainNode kept in sync with a volume control, then a safety limiter, then the shared AudioContext's destination. |

## Usage

Connect every sound of a screen into one master bus, never straight into `ctx.destination`. One fader then sets the level of everything, and a limiter at the end keeps a loud mix from clipping.

```tsx
import { useMasterBus } from "@/hooks/use-master-bus";

const [volume, setVolume] = useState(0.7);
const output = useMasterBus(volume);

const voices = useSynthVoices({ destination: output });

<Fader aria-label="Volume" max={1} min={0} onValueChange={setVolume} value={volume} />;
```

The bus is a gain, a limiter and a trim that cancels the limiter's make-up gain, so below its threshold (-3 dBFS) the sound passes unchanged. A change of `volume` ramps over 10 ms, so dragging the fader never clicks. The limiter adds a few milliseconds of latency.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `useMasterBus(volume)` | `GainNode \| null` |  | The node to connect sources into. `null` on the server and in the first render, before the context exists. |
| `volume` | `number` |  | The bus's gain, 0 to 1 for silence to unity. |