Sound

let optionalProps = {
  autoPlay: Boolean,
  loop: Boolean,
  positional: false, // use positional audio when true
  // Optional: 0 mixes the source to mono, 1 preserves its original stereo.
  // Omit this property to use the normal audio path with no width processor.
  stereoWidth: 0.5,
  // "inherit" follows world.audio.panningModel (default: "equalpower")
  panningModel: "inherit", // "inherit", "equalpower", or "HRTF"
    // saves the sound as a url, e.g. sound.url, useful for Tone.js
  loadURL: Boolean,
  volume: 0.7
};

// Create a new U.PositionalAudio object using an asset name
const song = await Sound("melody.mp3", optionalProps);

// Load using an array buffer, this might be from a download or p2p data
const song = await Sound(arrayBuffer);

// Load from a URL
const audioClip = await Sound("https://sound.com/mp3.com");

// Load data without creating any Web Audio nodes.
const impactBuffer = await SoundBuffer("impact.mp3");

// Reuse a bounded number of complete playback graphs with many buffers.
const impacts = SoundPool(12, {
  positional: true,
  panningModel: "equalpower"
});
for (const voice of impacts.voices) world.add(voice);
impacts.play(impactBuffer, {
  position: hitPosition,
  volume: 0.5,
  refDistance: 5,
  priority: 10,
  tag: "impact"
});

// Remove scene ownership before disposing the pool itself.
for (const voice of impacts.voices) world.remove(voice);
impacts.dispose();

// Example usage
song.play()

world.add(song);

// Change the engine-wide default. Existing positional sounds using
// "inherit" update immediately.
world.audio.setPanningModel("HRTF");
world.audio.panningModel = "equalpower";

// Override one positional sound without changing the global setting.
song.setPanningModel("HRTF");

// Resume following the global setting.
song.setPanningModel("inherit");

// Inspect the configured mode and effective Web Audio model.
song.getPanningModelMode(); // "inherit"
song.getPanningModel(); // "equalpower" or "HRTF"

// Stops playback and disconnects all Web Audio nodes owned by the sound.
// world.remove(song) calls this automatically.
song.dispose();

Sound() applies autoPlay, loop, and volume before installing the decoded buffer, so autoplay begins with the requested playback settings. Invalid or unsupported audio rejects the returned promise; callers loading optional audio should handle that rejection with try/catch.

Repeated Sound() calls for the same resolved asset key or URL share one decoded AudioBuffer. Each call still returns an independent audio object with its own playback, gain, and positional state, so creating voice pools does not decode or retain duplicate PCM data.

SoundBuffer() uses the same decoded-buffer cache but creates no audio nodes. SoundPool() owns a fixed number of reusable voices. It uses idle voices first, then steals the oldest lowest-priority voice; lower-priority playback is dropped when every voice is occupied by something more important. Use stopTag(), stopAll(), and dispose() for pool lifecycle management.

dispose() is safe to call more than once. It stops the active source, disconnects filters, stereo-width nodes, positional panners, and gain nodes, releases the decoded buffer, and revokes a generated loadURL object URL. world.remove() disposes audio objects automatically. Stopping or changing a project disposes all remaining scene audio and clears the decoded-buffer cache.

stereoWidth is a creation parameter rather than a runtime setter. It accepts values from 0 to 1 and is useful only for source files containing stereo information. Buffer-backed sounds apply the width once to a shared derived buffer, avoiding a permanent channel-mixing graph per voice. Dynamic node and media sources bypass the graph for identity width and mono buffers.

equalpower is the engine default because it provides efficient left/right spatialization. Use HRTF when higher-quality headphone spatialization is worth the additional audio-processing cost. A sound-level override remains unchanged when the global setting changes.

For more info check three.js Audio and PositionalAudio