🌊 SonicWave

Canvas-Based Audio Waveform & Spectrum Visualization Library

SonicWave is a zero-dependency JavaScript library for rendering beautiful audio waveform visualizations, interactive equalizer bars, and frequency spectrum displays using the HTML5 Canvas API. A lightweight, modern alternative to WaveSurfer.js.

Use it standalone or pair it with SonicMotion to create real-time audio-reactive Canvas visuals driven by live music stem analysis.

✨ Features

• 🎵 Waveform Renderer: Draw audio waveforms from AudioBuffer or real-time frequency data — replaces WaveSurfer.js.
• 🎚️ Equalizer Bars: Animated, color-coded frequency bars for bass, mid and treble ranges.
• 📊 Spectrum Display: Full frequency spectrum visualization with configurable colors and bar counts.
• 🎨 Fully Customizable: Colors, bar counts, smoothing, gradients and canvas size — all configurable.
• ⚡ Zero Dependencies: Pure Canvas API, no external libraries required.
• 🔗 SonicMotion Compatible: Feed real-time stem data directly into any SonicWave renderer.

💻 Installation

npm install sonicwave

import SonicWave from 'sonicwave';

🚀 Quick Start

Equalizer Bars

<canvas id="eq-canvas"></canvas>

import SonicWave from 'sonicwave';

const eq = SonicWave.createEqualizer({
    canvas: document.getElementById('eq-canvas'),
    bars: 32,
    color: '#7928ca',
    backgroundColor: '#0a0a0a'
});

// Feed real-time data from SonicMotion
sonic.onFrame((data) => {
    eq.update(data.bass.bands);  // { bass, mid, treble }
});

Frequency Spectrum

<canvas id="spectrum-canvas"></canvas>

const spectrum = SonicWave.createSpectrum({
    canvas: document.getElementById('spectrum-canvas'),
    barCount: 64,
    colors: {
        bass: '#ff0080',
        mid: '#7928ca',
        treble: '#00d4ff'
    }
});

sonic.onFrame((data) => {
    spectrum.update(data);
});

Waveform Renderer (Static)

const waveform = SonicWave.createWaveform({
    canvas: document.getElementById('waveform-canvas'),
    color: '#00d4ff',
    backgroundColor: '#111'
});

// Render from AudioBuffer
const response = await fetch('/audio/master.mp3');
const arrayBuffer = await response.arrayBuffer();
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
waveform.renderBuffer(audioBuffer);

⚙️ Configuration Options

createEqualizer(config)

| Option | Default | Description | |---|---|---| | canvas | required | HTMLCanvasElement to render on | | bars | 32 | Number of equalizer bars | | color | '#7928ca' | Bar fill color (or gradient array) | | backgroundColor | '#000' | Canvas background | | gap | 2 | Pixel gap between bars | | smoothing | 0.8 | Smoothing factor (0–1) | | mirror | false | Mirror bars from center |

createSpectrum(config)

| Option | Default | Description | |---|---|---| | canvas | required | HTMLCanvasElement to render on | | barCount | 64 | Number of frequency bars | | colors | { bass, mid, treble } | Color per frequency band | | backgroundColor | '#000' | Canvas background | | smoothing | 0.75 | Smoothing factor (0–1) |

createWaveform(config)

| Option | Default | Description | |---|---|---| | canvas | required | HTMLCanvasElement to render on | | color | '#00d4ff' | Waveform stroke color | | backgroundColor | '#000' | Canvas background | | lineWidth | 2 | Waveform stroke width |

🔌 JavaScript API

// Equalizer
const eq = SonicWave.createEqualizer(config);
eq.update(bandsData)  // { bass, mid, treble } values 0–1
eq.resize()           // Call on window resize
eq.destroy()          // Clean up canvas

// Spectrum
const spectrum = SonicWave.createSpectrum(config);
spectrum.update(frameData)  // Full frame data object
spectrum.resize()
spectrum.destroy()

// Waveform
const waveform = SonicWave.createWaveform(config);
waveform.renderBuffer(audioBuffer)   // Render from AudioBuffer
waveform.renderLive(frequencyData)   // Render from real-time byte array
waveform.clear()
waveform.destroy()

🎵 Works Best With

• sonicmotion — Audio stem analysis and DOM animation engine
• sonicfx — Advanced audio-reactive visual effects
• sonicscroll — Scroll-triggered animations with audio-aware mode

📄 License

MIT © 2025 axscq