use-stream-levels

(no submodules)

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

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

Usage: Advanced

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.

1.9 KiB Raw Permalink Blame History