Tiny high-performance audio visualizer hook for React
npm install @tkhdev/react-audio-visualizer!npm version
!npm downloads
!license
!bundle size
!TypeScript
!React
A tiny, high-performance audio visualizer hook for React using Web Audio API + Canvas
Features • Installation • Quick Start • API Reference • Examples • Performance • Live Demo
---
- Overview
- Visual Gallery
- Features
- Installation
- Quick Start
- Visualization Modes
- API Reference
- Usage Examples
- Advanced Usage
- Performance
- Browser Support
- Troubleshooting
- Architecture
- Contributing
- License
---
@tkhdev/react-audio-visualizer is a lightweight, performant React hook that provides real-time audio visualization capabilities. Built on top of the Web Audio API and HTML5 Canvas, it offers 38 unique visualization modes with zero React re-renders per frame, making it perfect for music players, voice analysis tools, and interactive audio experiences.
- 🚀 Zero Re-renders: Uses requestAnimationFrame for smooth 60 FPS animations without triggering React re-renders
- 📦 Tree-shakeable: Dynamic imports ensure only used renderers are bundled
- 🎨 38 Visualization Modes: From classic waveforms to artistic patterns
- 🔧 Fully Typed: Complete TypeScript support with comprehensive type definitions
- 🌐 SSR Safe: Works seamlessly with Next.js and other SSR frameworks
- 🎤 Dual Input Support: Works with microphone input or HTML audio elements
- 📱 Mobile Ready: Optimized for mobile browsers with high-DPI display support
---
Here are some examples of the visualizations in action:
![]() | ![]() | ![]() |
![]() | ![]() | ![]() |
![]() | ![]() | ![]() |
![]() | ![]() | ![]() |
![]() | ![]() | ![]() |
---
- Multiple Audio Sources
- 🎤 Microphone input with device selection
- 🎵 HTML audio/video element support
- 🔄 Automatic source management and cleanup
- Rich Visualization Options
- 📊 38 built-in visualization modes
- 🎨 Customizable colors (static or dynamic functions)
- 🔄 Mirror mode for symmetric visualizations
- 📐 Configurable FFT sizes (256, 512, 1024, 2048)
- 🎚️ Adjustable smoothing and decibel ranges
- Performance Optimizations
- ⚡ Zero React re-renders per frame
- 🖼️ High-DPI canvas scaling
- 💾 Renderer caching and lazy loading
- 🧹 Automatic resource cleanup
- 📦 Code splitting for smaller bundle sizes
- Developer Experience
- 📘 Full TypeScript support
- 🎯 Comprehensive error handling
- 🔔 Lifecycle callbacks (onStart, onStop, onError)
- 📖 Extensive documentation and examples
---
``bash`
npm install @tkhdev/react-audio-visualizer
or
`bash`
yarn add @tkhdev/react-audio-visualizer
or
`bash`
pnpm add @tkhdev/react-audio-visualizer
- react >= 17
---
`tsx
import { useAudioVisualizer } from '@tkhdev/react-audio-visualizer';
function App() {
const { canvasRef, start, stop, isRunning } = useAudioVisualizer({
source: 'mic',
mode: 'spectrum',
});
return (
$3
`tsx
import { useRef } from 'react';
import { useAudioVisualizer } from '@tkhdev/react-audio-visualizer';function App() {
const audioRef = useRef(null);
const { canvasRef, start, stop } = useAudioVisualizer({
source: audioRef.current!,
mode: 'waveform',
});
return (
ref={audioRef}
controls
src="/path/to/audio.mp3"
onPlay={start}
onPause={stop}
/>
);
}
`---
🎨 Visualization Modes
The library provides 38 visualization modes organized by category:
$3
- waveform - Classic time-domain waveform
- dual-waveform - Dual mirrored waveforms
- oscilloscope - Oscilloscope-style display
- waveform-bars - Waveform represented as bars
- waveform-fill - Filled waveform area
- radial-waveform - Circular waveform pattern
- waveform-history - Waveform with history trail
- energy-waves - Energy-based wave visualization$3
- spectrum - Classic frequency spectrum bars
- line-spectrum - Frequency spectrum as lines
- radial-spectrum - Circular frequency spectrum
- frequency-bands - Grouped frequency bands
- rounded-bars - Rounded frequency bars
- frequency-dots - Frequency data as dots
- frequency-lines - Frequency lines visualization
- frequency-arcs - Arced frequency display
- frequency-rings - Concentric frequency rings$3
- circular - Circular visualization
- spiral - Spiral pattern
- star - Star-shaped visualization
- flower - Flower-like pattern
- mandala - Mandala pattern
- kaleidoscope - Kaleidoscope effect
- light-rays - Light ray effects
- glow - Glowing visualization
- bubbles - Bubble effects
- particles - Particle system
- particle-trails - Particles with trails
- matrix - Matrix-style visualization
- pulse - Pulsing visualization
- nebula - Flowing organic patterns with particles and gradients$3
- loudness - Overall loudness meter
- vu-meter - VU meter display
- equalizer - Equalizer visualization
- spectrogram - Spectrogram (frequency over time)
- sound-waves - Sound wave patterns
- lissajous - Lissajous curves
- combined - Combined waveform and spectrum$3
`tsx
import { useState } from 'react';
import { useAudioVisualizer, type VisualizerMode } from '@tkhdev/react-audio-visualizer';const modes: VisualizerMode[] = [
'waveform',
'spectrum',
'spiral',
'circular',
'particles',
// ... more modes
];
function App() {
const [mode, setMode] = useState('spectrum');
const { canvasRef, start, stop } = useAudioVisualizer({
source: 'mic',
mode,
barColor: '#00ffcc',
});
return (
);
}
`---
📚 API Reference
$3
The main hook that provides audio visualization capabilities.
#### Parameters
#####
options: UseAudioVisualizerOptions| Option | Type | Default | Required | Description |
|--------|------|---------|----------|-------------|
|
source | 'mic' \| HTMLAudioElement | - | ✅ | Audio source. Use 'mic' for microphone input or pass an HTMLAudioElement reference. |
| mode | VisualizerMode | - | ✅ | Visualization mode. See Visualization Modes for all available options. |
| fftSize | 256 \| 512 \| 1024 \| 2048 | 1024 | ❌ | FFT (Fast Fourier Transform) size. Higher values provide more frequency resolution but use more CPU. |
| smoothing | number | 0.85 | ❌ | Smoothing time constant (0-1). Higher values create smoother transitions but slower response. |
| minDecibels | number | -90 | ❌ | Minimum decibel value for frequency analysis. |
| maxDecibels | number | -10 | ❌ | Maximum decibel value for frequency analysis. |
| barColor | string \| (value: number) => string | '#00ffcc' | ❌ | Color for bars/lines. Can be a static color string or a function that returns a color based on the normalized value (0-1). |
| backgroundColor | string | '#000' | ❌ | Canvas background color. Use 'transparent' for transparent background. |
| lineWidth | number | 2 | ❌ | Line width for waveform-based visualizations (in pixels). |
| deviceId | string | undefined | ❌ | Specific microphone device ID. Use navigator.mediaDevices.enumerateDevices() to get available devices. |
| mirror | boolean | false | ❌ | Enable mirror mode for symmetric visualizations. |
| onStart | () => void | undefined | ❌ | Callback function called when visualization starts. |
| onStop | () => void | undefined | ❌ | Callback function called when visualization stops. |
| onError | (err: Error) => void | undefined | ❌ | Error callback function. Called when an error occurs during initialization or runtime. |#### Returns
#####
UseAudioVisualizerReturn| Property | Type | Description |
|----------|------|-------------|
|
canvasRef | RefObject | React ref to attach to a