# use-stream-levels

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`useStreamLevels` projects realtime peak/RMS samples out of the session. Called without
an argument it returns the local-microphone level; called with a peer id it returns the
named peer's level. The level numbers come from chunks A/B's analyzer slot (which lives
on each peer's plugin chain alongside the `StreamSourcePlugin`), and this hook is a
zero-state projection — it does not compute anything itself.

The reading is intentionally synchronous: the provider's render-bump version is what
schedules re-renders, and the session is responsible for batching analyzer ticks into
the `levels-changed` event channel at a sane cadence (typically 60 Hz).

## Features

- Same hook for local and per-peer levels — the `peerId?` argument selects.
- Re-renders on every `levels-changed` event via the provider's version counter.
- Throws `REACT_AUDIO_STREAM.NO_PROVIDER` when used outside a `<StreamProvider>`.

## Usage: Basic

```tsx
const { peak, rms } = useStreamLevels();
return <LevelMeter peak={peak} rms={rms} />;
```

## Usage: Advanced

```tsx
const peers = useStreamPeers();
return peers.map((p) => {
    const { peak } = useStreamLevels(p.id);
    return <PeerLevelBar key={p.id} peerId={p.id} peak={peak} />;
});
```

(Real apps should hoist the per-peer call into a child component to keep the hook count
stable across renders.)

## API Reference

- `useStreamLevels(peerId?: string): LevelSample` — `LevelSample` is `{ peak: number; rms: number }`.

## Implementation Notes

The hook does not pull from `@suaveplan/audio-analysis-spectrum` directly — that module
runs inside the audio engine (browser tier, owned by chunks A/B). The React boundary
only ever sees the peak/RMS scalars produced by the engine's analyzer. Keeping the
hook this thin guarantees zero DSP work happens during React rendering.