Three.js Audio

Setup — AudioListener

// One AudioListener per scene, attached to camera
const listener = new THREE.AudioListener();
camera.add(listener);

Global (Non-Spatial) Audio

const sound = new THREE.Audio(listener);
const loader = new THREE.AudioLoader();

// Async load
const buffer = await loader.loadAsync("/audio/music.mp3");
sound.setBuffer(buffer);
sound.setLoop(true);
sound.setVolume(0.5);

// Must start on user gesture (browser autoplay policy)
document.addEventListener("click", () => sound.play(), { once: true });

// Controls
sound.pause();
sound.stop();
sound.isPlaying; // boolean
sound.offset = 10; // start at 10 seconds
sound.playbackRate = 1.5; // 1.5x speed

Positional (Spatial) Audio

// Sound whose volume/pan changes based on distance and angle to camera
const posSound = new THREE.PositionalAudio(listener);

const buffer = await new THREE.AudioLoader().loadAsync("/audio/engine.mp3");
posSound.setBuffer(buffer);
posSound.setLoop(true);
posSound.setRefDistance(2); // distance at which volume = 1 (full)
posSound.setRolloffFactor(1); // how fast volume drops with distance
posSound.setDistanceModel("inverse"); // 'linear', 'inverse', 'exponential'
posSound.setMaxDistance(50); // beyond this distance, volume = 0
posSound.setDirectionalCone(180, 360, 0.1); // innerAngle, outerAngle, outerGain

// Attach to a mesh — sound follows the object
mesh.add(posSound);
document.addEventListener("click", () => posSound.play(), { once: true });

AudioAnalyser (visualization)

const analyser = new THREE.AudioAnalyser(sound, 32); // sound, fftSize

function animate() {
  requestAnimationFrame(animate);

  const data = analyser.getFrequencyData(); // Uint8Array, length = fftSize/2
  const avg = analyser.getAverageFrequency(); // 0–255

  // Drive visuals with audio data
  mesh.scale.setScalar(1 + avg / 255);

  // Per-frequency band control
  for (let i = 0; i < data.length; i++) {
    bars[i].scale.y = (data[i] / 255) * maxHeight;
  }

  renderer.render(scene, camera);
}

Web Audio API (direct access)

// Access underlying Web Audio context and nodes
const audioContext = listener.context;

// Create filter
const filter = audioContext.createBiquadFilter();
filter.type = "lowpass";
filter.frequency.value = 1000;

// Connect: source → filter → destination
sound.setFilter(filter);

// Gain control
sound.setVolume(0.8); // wraps GainNode

// Access raw audio node
const gainNode = sound.gain; // GainNode
gainNode.gain.setValueAtTime(0, audioContext.currentTime);
gainNode.gain.linearRampToValueAtTime(1, audioContext.currentTime + 2);

Multiple Sounds / Preloading

const manager = new THREE.LoadingManager();
const loader = new THREE.AudioLoader(manager);

const sounds = {};
sounds.jump = await loader.loadAsync("/audio/jump.wav");
sounds.land = await loader.loadAsync("/audio/land.wav");
sounds.music = await loader.loadAsync("/audio/bg.mp3");

function playJump() {
  const s = new THREE.Audio(listener);
  s.setBuffer(sounds.jump);
  s.play();
  // one-shot: auto-cleanup on end
  s.onEnded = () => s.disconnect();
}

Common Gotchas

• Browsers block autoplay — always start audio inside a user gesture handler (click, touchstart)
• One AudioListener per scene — multiple listeners cause unexpected behavior
• PositionalAudio must be added to an Object3D (mesh, group) to be positioned
• AudioAnalyser fftSize must be a power of 2 between 32 and 32768 — data array length = fftSize / 2
• sound.stop() resets playback position — sound.pause() preserves it
• Use new THREE.Audio(listener) for one-shot effects (not reusing the same Audio object)
• Audio context may be in 'suspended' state until first user interaction — check listener.context.state