Web Audio + Three.js Starter

A minimal React starter for turning a local audio file into audio-reactive 3D visuals with the Web Audio API, Three.js, and React Three Fiber.

Live demo | Related full visualizer | MIT License

Features

• Local audio loading with no media upload or backend
• Live volume, bass, mids, highs, and waveform analysis
• Reactive wireframe mesh and GPU-rendered particle field
• Adjustable sensitivity, analyser smoothing, seeking, and particle density
• Responsive controls for desktop and mobile layouts
• Audio graph, animation frame, event listener, and object URL cleanup
• Strict TypeScript, ESLint, Vitest, GitHub Actions CI, and GitHub Pages deployment

Quick Start

Requires Node.js 22.13 or newer.

git clone https://github.com/7g3n/web-audio-threejs-starter.git
cd web-audio-threejs-starter
npm ci
npm run dev

Open the local Vite URL, choose a browser-supported audio file, and press Play. The file stays on your device.

Commands

npm run lint
npm run typecheck
npm test
npm run build
npm run preview

How It Works

useAudioAnalyzer creates an AudioContext, routes an HTMLAudioElement through an AnalyserNode, and samples time-domain and frequency-domain data on animation frames. Pure helpers in src/audio/analysis.ts calculate RMS volume, frequency-band energy, and a downsampled waveform.

The latest values are kept in a ref so the React Three Fiber render loop can animate the mesh and particles without rebuilding the scene. A throttled React state snapshot drives the visible meters and waveform.

Frequency ranges:

Feature	Range
Bass	20-250 Hz
Mids	250-2,000 Hz
Highs	2,000-8,000 Hz

Project Structure

src/
  audio/
    analysis.ts
    analysis.test.ts
    useAudioAnalyzer.ts
  components/
    Meter.tsx
    Waveform.tsx
  visual/
    Visualizer.tsx
  App.tsx
  styles.css

Browser Notes

Audio playback must begin after a user gesture because browsers suspend new audio contexts by default. Codec support depends on the browser and operating system. Current Chrome, Edge, Firefox, and Safari releases are recommended.

Deployment

Pushes to main run CI and deploy dist through GitHub Pages. The Vite build uses relative asset paths, so the same output also works from a subdirectory.

Contributing

See CONTRIBUTING.md. Please report security concerns using the private process in SECURITY.md.

License

MIT. See LICENSE.