AUDIOSYNC — Music Visualizer v2

React Three Fiber · GSAP · Framer Motion · Tone.js

⚡ Quick Start

npm install
npm run dev
# → http://localhost:3000

📦 Stack

Library	Role
@react-three/fiber	React renderer for Three.js — declarative 3D
@react-three/drei	R3F helpers: Stars, Bloom, EffectComposer, AdaptiveDpr
@react-three/postprocessing	Bloom glow + Vignette effects
three	Underlying 3D engine
tone	Audio engine: Player, FFT, Waveform, Transport
gsap	Tweens, timelines, THREE.Color animation
framer-motion	UI animations, spring physics, AnimatePresence
zustand	Shared audio state (no prop drilling)

🏗 Architecture

hooks/
  useAudioEngine.ts   ← Tone.js wrapper: play/pause/file load, readFrame()

lib/
  audioContext.tsx    ← React Context + Zustand store for shared audio state
  shaders.ts          ← All GLSL shaders (DRY: shared uniforms injected per shader)

components/
  VisualizerCanvas.tsx          ← R3F Canvas + AudioFramePump + post-processing
  visualizers/
    BaseVisualizer.tsx           ← Abstract: shared uniforms, useFrame, GSAP intro
    SphereVisualizer.tsx         ← Fibonacci sphere cloud
    WaveformVisualizer.tsx       ← Frequency bars + oscilloscope
    DNAVisualizer.tsx            ← Double helix
    TunnelVisualizer.tsx         ← Infinite zoom tunnel
  ui/
    TransportControls.tsx        ← Play/Pause/Stop + audio source selector
    VisualizerSelector.tsx       ← Mode switcher
    ThemeSelector.tsx            ← Color palette
    FrequencyMeter.tsx           ← FFT bars + band meters

🎨 Visualizer Modes

Mode	Description
SPHERE	6000 particles on a Fibonacci sphere, displaced by FFT bins
WAVE	128 frequency bars + waveform oscilloscope overlay
HELIX	DNA double helix — strands pulse with bass/treble
TUNNEL	Infinite zoom tunnel — rings scale with frequency

🔑 Key Concepts

React Three Fiber (R3F)

• Declarative Three.js — <Canvas>, <points>, <shaderMaterial> as JSX
• useFrame(cb) — runs inside the render loop, no React re-render
• useMemo for geometry — build BufferGeometry once, never recreate
• forwardRef + useImperativeHandle — expose Three.js controls to React

Tone.js Audio

• Tone.FFT(128) — real-time frequency analysis
• Tone.Waveform(256) — oscilloscope data
• Tone.Player — load and play audio files
• Tone.PolySynth — generative demo mode
• Signal chain: [Source] → [FFT] → [Waveform] → [Destination]

GSAP

• gsap.fromTo(scale, {xyz:0}, {xyz:1}) — intro animation
• Tweening THREE.Color.r/g/b — smooth palette transitions
• overwrite: true — cancel conflicting tweens

Framer Motion

• useMotionValue + useSpring + useTransform — 60fps mouse parallax
• AnimatePresence — panel slide in/out with exit animations
• layoutId — active indicator morphs between buttons
• Spring physics — stiffness/damping for physical feel

Zustand Store

• useAudioStore.getState() inside useFrame — reads state without subscription (subscriptions would re-render on every frame — bad for perf)

🎛 Features

• 4 visualizer modes — switchable live
• 6 color themes — smooth GSAP color transitions
• Tone.js demo — works out of the box, no audio file needed
• MP3 upload — drag any audio file in
• Mic input — live audio visualization
• Bloom glow — post-processing via @react-three/postprocessing
• Mouse parallax — spring-physics 3D tilt
• Adaptive DPR — auto-adjusts pixel ratio for performance