glsl-audio-visualizer

A WebGL particle sphere that reacts to audio. Drop it into any DOM element — it handles everything else.

Inspired by the NCS-style visualizers with the neon glow and bass drops.

Live demo

---

Install

npm install glsl-audio-visualizer three

three is a peer dependency — you need it installed separately.

---

Quick start

import { GLSLAudioVisualizer } from 'glsl-audio-visualizer';

const viz = new GLSLAudioVisualizer(document.getElementById('container')!);

// Load an audio file
fileInput.addEventListener('change', (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) viz.loadAudio(file);
});

// Clean up when done
viz.dispose();

The container must have explicit dimensions (width + height). The canvas fills it 100%.

---

Constructor

new GLSLAudioVisualizer(container: HTMLElement, options?: DeepPartial<VisualizerConfig>)

All config options are optional — defaults are applied for anything you don't specify:

const viz = new GLSLAudioVisualizer(el, {
  color: {
    mode: 'gradient',
    colors: ['#ff0000', '#00aaff', '#00ff88'],
  },
  sphere: { baseRadius: 1.2 },
  bloom:  { strength: 0.4 },
});

---

Config

The config is split into groups matching the visual sections.

color

Property	Type	Default	Description
mode	ColorMode	'audio'	How colors are applied (see modes below)
colors	string[]	['#fa0000','#0066ff']	Color palette — 1 to 16 hex colors
hueSpeed	number	0.05	Rotation speed for hue mode

Color modes:

• solid — uses the first color
• gradient — blends across the color array by vertical position
• audio — blends across the color array by energy level
• hue — rainbow hue rotation, uses first color as base

sphere

Property	Type	Default	Description
baseRadius	number	1.4	Base sphere size
bassScale	number	0.5	How much bass expands the radius
feather	number	0.45	Softness of the sphere edge

displacement

Property	Type	Default	Description
amplitude	number	0.35	Maximum particle displacement
noiseScale	number	2.2	Scale of the noise pattern
flowSpeed	number	0.15	Animation speed of the noise

particles

Property	Type	Default	Description
size	number	5.0	Base particle size in pixels
opacity	number	0.4	Particle opacity (additive blending, keep low)
softness	number	0.12	Edge softness of each particle
sparkle	number	1.5	How much energy adds size variance
variance	number	0.25	Noise-based color variance per particle

bloom

Property	Type	Default	Description
strength	number	0.15	Bloom/glow intensity
radius	number	0.85	Bloom spread radius
threshold	number	0.0	Minimum brightness to bloom

audio

Property	Type	Default	Description
attackSpeed	number	0.3	How fast the sphere reacts to beats (0–1)
releaseSpeed	number	0.05	How fast it decays after a beat (0–1)
bassBoost	number	0.5	Bass frequency amplification
energyBoost	number	1.0	Overall energy amplification

---

API

Audio

viz.loadAudio(file: File): Promise<void>
viz.play(): void
viz.pause(): void
viz.togglePlay(): void
viz.seek(ratio: number): void  // 0–1
viz.eject(): void

External audio source

Connect any Web Audio API node — microphone, oscillator, media element, etc:

// Microphone
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const ctx = viz.getAudioContext();
const source = ctx.createMediaStreamSource(stream);
viz.connectNode(source);

// HTML <audio> element
const source = ctx.createMediaElementSource(audioEl);
viz.connectNode(source);

State

// Subscribe to playback state changes
viz.onAudioStateChange = (state) => {
  console.log(state.playing, state.progress, state.trackName);
  console.log(state.currentTime, state.duration);
};

// Read current state
const state = viz.audioState;

Config

// Update any subset of config at runtime — other values are preserved
viz.setConfig({ bloom: { strength: 1.0 } });
viz.setConfig({ color: { mode: 'hue', colors: ['#ff00ff'] } });

// Read current config
const cfg = viz.getConfig();

Lifecycle

viz.dispose()  // cancels RAF, releases GPU resources, removes canvas

---

Background

Background is controlled via CSS on the container — not through the config. The canvas is always transparent:

#container {
  background: #000;           /* solid black */
  background: transparent;    /* see-through */
  background: rgba(0,0,0,0.5); /* semi-transparent */
}

This keeps the WebGL bloom pipeline clean and lets you composite the sphere over any content.

---

TypeScript

All config types are exported:

import type {
  VisualizerConfig,
  ColorConfig,
  SphereConfig,
  DisplacementConfig,
  ParticlesConfig,
  BloomConfig,
  AudioConfig,
  AudioState,
  ColorMode,
  DeepPartial,
} from 'glsl-audio-visualizer';

---

Playground (dev)

The repo includes a Vue playground with a full settings panel:

npm install
npm run dev        # start playground at localhost:5173
npm run build      # build playground for GitHub Pages
npm run build:lib  # build the library into dist/

---

How it works

• 262,144 particles on a 512×512 grid, projected onto a sphere
• Simplex 3D noise (Ashima Arts) drives displacement — three swizzled axes for smooth 3D flow
• Bass expands the sphere radius with a quadratic response curve (weak bass barely registers, strong beats punch hard)
• Energy drives displacement amplitude — gated by bass so the sphere stays calm without beats
• UnrealBloomPass (Three.js post-processing) for the glow effect
• AdditiveBlending — works best on dark backgrounds
• Up to 16 colors interpolated across the palette based on mode

---

License

MIT