vu-meter-react

React VU meter component designed to work from legacy React (16.8+) up to React 19. It computes RMS from Web Audio in real time and drives the needle with VU ballistics (~300 ms attack/release). Comes with light/dark themes and responsive sizing.

Demo

CodeSandBox

Installation

When published on npm:

npm i vu-meter-react

Quick start

import { VUMeter } from "vu-meter-react";

// Stereo (L/R)
<VUMeter
  audioContext={audioContext}
  sourceNode={sourceNode}
  referenceLevel={-18}
  options={{ width: 300, theme: "light" }}
/>

// Mono
<VUMeter
  audioContext={audioContext}
  sourceNode={sourceNode}
  mono
  referenceLevel={-20}
  options={{ width: 260, theme: "dark" }}
/>

API

Component

• VUMeter(props: VUMeterProps)
  • Single component that renders either a single (mono) meter or a stereo pair (L/R)

Types

• VUMeterProps

  • audioContext: AudioContext | null
  • sourceNode: AudioNode | null
  • mono?: boolean — mono meter when true, stereo when false (default: false)
  • label?: string — mono: "MONO", stereo: "L"/"R" by default
  • referenceLevel?: number — dBFS treated as 0 VU (default: -18)
  • options?: VUMeterOptions

• VUMeterOptions

  • theme?: 'dark' | 'light' (default: 'light')
  • needleColor?: string
  • labelColor?: string
  • backgroundColor?: string
  • boxColor?: string
  • fontFamily?: string
  • width?: number — height is auto-calculated by aspect ratio when unspecified
  • height?: number — width is auto-calculated by aspect ratio when unspecified
  • peakHoldMs?: number — peak lamp hold time after the last clip in milliseconds (default: 1000)
  • peakFadeMs?: number — peak lamp fade-out duration in milliseconds (default: 5000)
  • clipThresholdDeg?: number — needle angle threshold in degrees to treat as clip (default: 23)

Rendering and metering

• SVG scale rendering with color accents for warning zones
• Needle is rotated via CSS transform; tuned for smooth animation
• Peak lamp turns on near the upper range; once the signal falls below the clip threshold it stays on for peakHoldMs and then fades out over peakFadeMs (defaults: hold 1s, fade 5s)
• RMS via getFloatTimeDomainData(), converted to dBFS, then mapped to VU with measured piecewise interpolation
• VU ballistics (~300 ms attack/release) for natural motion

Notes

• Due to browser autoplay policies, create/resume AudioContext from a user gesture (e.g., clicking Play)
• In stereo mode, the component internally uses a ChannelSplitterNode to meter L/R

Build / Types / Docs

• Build (ESM/CJS + d.ts): npm run build → dist/index.mjs, dist/index.cjs, dist/index.d.ts
• Generate docs (TypeDoc): npm run docs → outputs to docs/

License

MIT