Skip to content

3D engine that AI agents drive

32.1 KB
Raw Blame
// Spatial audio for a live game, as a runtime system. Sounds are defined once, then played from events (input actions,
// physics contacts, animation markers, game code) at a position, on a node, or flat. A listener follows the camera.
// Everything talks to a backend object (play a buffer, move the listener, set a bus volume); the Web Audio backend is the
// default and tests or another engine pass their own. See docs/audio.md.

export const AUDIO_LIMITS = Object.freeze({
  maximumSounds: 256,
  maximumBindings: 256,
  maximumBuses: 16,
  maximumVoices: 64,
  defaultVoices: 32,
  defaultInstancesPerSound: 8,
  maximumInstancesPerSound: 32,
  maximumMarkers: 512,
});

export const DEFAULT_BUSES = Object.freeze(['music', 'effects', 'voice']);
// An occluded source loses this share of its level and is also muffled by a low-pass filter.
export const OCCLUDED_GAIN_LOSS = 0.7;
const OCCLUDED_LOW_PASS_HERTZ = 400;
const OPEN_LOW_PASS_HERTZ = 20000;
const PARAMETER_SMOOTHING_SECONDS = 0.01;
const MINIMUM_VOICE_PITCH = 0.1;
const MAXIMUM_VOICE_PITCH = 16;
const DISTANCE_MODELS = ['inverse', 'linear', 'exponential'];
const GESTURE_EVENTS = ['pointerdown', 'keydown', 'touchend'];

function describe(value) {
  return value === null ? 'null' : typeof value;
}

function requireName(value, label) {
  if (typeof value !== 'string' || value === '') {
    throw new TypeError(`${label} must be a non-empty string, got ${describe(value)}.`);
  }
  return value;
}

function requireNumberInRange(value, label, minimum, maximum) {
  if (!Number.isFinite(value) || value < minimum || value > maximum) {
    throw new RangeError(`${label} must be a number from ${minimum} to ${maximum}, got ${String(value)}.`);
  }
  return value;
}

// A count limit must be a whole number: 2.5 would silently allow a third voice.
function requireWholeNumberInRange(value, label, minimum, maximum) {
  if (!Number.isInteger(value)) {
    throw new RangeError(`${label} must be a whole number from ${minimum} to ${maximum}, got ${String(value)}.`);
  }
  return requireNumberInRange(value, label, minimum, maximum);
}

function requireVector(value, label) {
  if (!Array.isArray(value) && !ArrayBuffer.isView(value)) {
    throw new TypeError(`${label} must be [x, y, z], got ${describe(value)}.`);
  }
  if (value.length < 3 || !Number.isFinite(value[0]) || !Number.isFinite(value[1]) || !Number.isFinite(value[2])) {
    throw new TypeError(`${label} must be three finite numbers [x, y, z].`);
  }
  return [value[0], value[1], value[2]];
}

function clampUnit(value) {
  return Math.min(Math.max(value, 0), 1);
}

// Distance gain from the Web Audio specification, so the level measured here matches what a PannerNode applies.
export function distanceGain(distance, { model = 'inverse', referenceDistance = 1, maximumDistance = 50, rolloff = 1 } = {}) {
  const clamped = Math.min(Math.max(distance, referenceDistance), maximumDistance);
  if (model === 'linear') {
    const span = maximumDistance - referenceDistance;
    return span <= 0 ? 1 : clampUnit(1 - rolloff * (clamped - referenceDistance) / span);
  }
  if (model === 'exponential') return clampUnit((clamped / referenceDistance) ** -rolloff);
  return clampUnit(referenceDistance / (referenceDistance + rolloff * (clamped - referenceDistance)));
}

function normalizeSpatial(spatial, label) {
  if (spatial === undefined || spatial === false) return null;
  const options = spatial === true ? {} : spatial;
  if (options === null || typeof options !== 'object') {
    throw new TypeError(`${label} spatial must be true or { referenceDistance, maximumDistance, rolloff, model, occlusion }, got ${describe(spatial)}.`);
  }
  const model = options.model ?? 'inverse';
  if (!DISTANCE_MODELS.includes(model)) {
    throw new RangeError(`${label} spatial model must be one of ${DISTANCE_MODELS.join(', ')}, got ${String(model)}.`);
  }
  const referenceDistance = requireNumberInRange(options.referenceDistance ?? 1, `${label} spatial referenceDistance`, 0.01, 1000);
  const maximumDistance = requireNumberInRange(options.maximumDistance ?? 50, `${label} spatial maximumDistance`, referenceDistance, 100000);
  // A real PannerNode rejects a linear rolloff above 1, so the range is narrower for that model.
  const maximumRolloff = model === 'linear' ? 1 : 20;
  const rolloff = requireNumberInRange(options.rolloff ?? 1, `${label} spatial rolloff`, 0, maximumRolloff);
  return Object.freeze({ model, referenceDistance, maximumDistance, rolloff, occlusion: options.occlusion === true });
}

// ---- Positions and listener ----

function matrixTranslation(matrix) {
  return [matrix[12], matrix[13], matrix[14]];
}

// A node is { position: [x, y, z] }, { matrix } (a 4x4 column-major array), or a function returning either of those.
export function readNodePosition(node, label = 'node') {
  const resolved = typeof node === 'function' ? node() : node;
  if (resolved === null || typeof resolved !== 'object') {
    throw new TypeError(`${label} must be [x, y, z], { position }, { matrix } or a function returning one of them, got ${describe(resolved)}.`);
  }
  if (Array.isArray(resolved) || (ArrayBuffer.isView(resolved) && resolved.length === 3)) return requireVector(resolved, label);
  if (resolved.position !== undefined) return requireVector(resolved.position, `${label} position`);
  if (resolved.matrix !== undefined && resolved.matrix.length === 16) return requireVector(matrixTranslation(resolved.matrix), `${label} matrix`);
  throw new TypeError(`${label} must be [x, y, z], { position }, { matrix } or a function returning one of them.`);
}

// The listener follows the camera: pass the renderer frame ({ eye, target, up }) or { position, forward, up }.
export function readListener(camera) {
  if (camera === null || typeof camera !== 'object') {
    throw new TypeError(`listener must be a camera frame { eye, target, up } or { position, forward, up }, got ${describe(camera)}.`);
  }
  const up = camera.up === undefined ? [0, 1, 0] : requireVector(camera.up, 'listener up');
  if (camera.eye !== undefined) {
    const position = requireVector(camera.eye, 'listener eye');
    const target = requireVector(camera.target ?? [position[0], position[1], position[2] - 1], 'listener target');
    return { position, forward: normalizeForward([target[0] - position[0], target[1] - position[1], target[2] - position[2]]), up };
  }
  return {
    position: requireVector(camera.position ?? [0, 0, 0], 'listener position'),
    forward: normalizeForward(requireVector(camera.forward ?? [0, 0, -1], 'listener forward')),
    up,
  };
}

function normalizeForward(vector) {
  const length = Math.hypot(vector[0], vector[1], vector[2]);
  if (length < 1e-9) return [0, 0, -1];
  return [vector[0] / length, vector[1] / length, vector[2] / length];
}

function distanceBetween(first, second) {
  return Math.hypot(first[0] - second[0], first[1] - second[1], first[2] - second[2]);
}

// ---- Animation markers ----

// Markers are { time, name } on a clip. Returns the ones crossed when the clip time moves from `fromTime` (exclusive)
// to `toTime` (inclusive). With `loop` and `duration`, a wrap from the end back to the start fires both ends.
export function markersCrossed(markers, fromTime, toTime, { loop = false, duration = Infinity } = {}) {
  if (!Array.isArray(markers) || markers.length > AUDIO_LIMITS.maximumMarkers) {
    throw new RangeError(`markers must be an array of up to ${AUDIO_LIMITS.maximumMarkers} { time, name } entries.`);
  }
  requireNumberInRange(fromTime, 'markers fromTime', -Number.MAX_VALUE, Number.MAX_VALUE);
  requireNumberInRange(toTime, 'markers toTime', -Number.MAX_VALUE, Number.MAX_VALUE);
  const crossed = [];
  const wrapped = loop && toTime < fromTime;
  for (const marker of markers) {
    requireName(marker?.name, 'marker name');
    requireNumberInRange(marker.time, `marker ${marker.name} time`, 0, Number.MAX_VALUE);
    const inRange = wrapped
      ? (marker.time > fromTime && marker.time <= duration) || (marker.time >= 0 && marker.time <= toTime)
      : marker.time > fromTime && marker.time <= toTime;
    if (inRange) crossed.push(marker);
  }
  return crossed;
}

// ---- Web Audio backend ----

function setParameter(parameter, value, now) {
  if (typeof parameter.setTargetAtTime === 'function') parameter.setTargetAtTime(value, now, PARAMETER_SMOOTHING_SECONDS);
  else parameter.value = value;
}

function setPannerPosition(panner, position, now) {
  if (panner.positionX) {
    setParameter(panner.positionX, position[0], now);
    setParameter(panner.positionY, position[1], now);
    setParameter(panner.positionZ, position[2], now);
  } else {
    panner.setPosition(position[0], position[1], position[2]);
  }
}

function setListenerPose(listener, pose, now) {
  if (listener.positionX) {
    setParameter(listener.positionX, pose.position[0], now);
    setParameter(listener.positionY, pose.position[1], now);
    setParameter(listener.positionZ, pose.position[2], now);
    setParameter(listener.forwardX, pose.forward[0], now);
    setParameter(listener.forwardY, pose.forward[1], now);
    setParameter(listener.forwardZ, pose.forward[2], now);
    setParameter(listener.upX, pose.up[0], now);
    setParameter(listener.upY, pose.up[1], now);
    setParameter(listener.upZ, pose.up[2], now);
  } else {
    listener.setPosition(pose.position[0], pose.position[1], pose.position[2]);
    listener.setOrientation(pose.forward[0], pose.forward[1], pose.forward[2], pose.up[0], pose.up[1], pose.up[2]);
  }
}

function occlusionHertz(occlusion) {
  return OPEN_LOW_PASS_HERTZ * (OCCLUDED_LOW_PASS_HERTZ / OPEN_LOW_PASS_HERTZ) ** occlusion;
}

// Graph: voice source -> [low-pass -> panner] -> voice gain -> bus gain -> master gain -> limiter -> destination.
export function webAudioBackend(options = {}) {
  const createContext = options.createContext ?? (() => new globalThis.AudioContext({ latencyHint: 'interactive' }));
  const fetchBytes = options.fetch ?? (globalThis.fetch ? globalThis.fetch.bind(globalThis) : null);
  const gestureTarget = options.gestureTarget === undefined ? globalThis.document : options.gestureTarget;
  let context = null;
  let master = null;
  let limiter = null;
  let removeGestureListeners = null;
  const buses = new Map();

  function requireContext() {
    if (!context) throw new Error('The audio backend has not started. Call audio.init() or add the audio system to a started runtime.');
    return context;
  }

  function unlock() {
    if (context && context.state === 'suspended') {
      const result = context.resume();
      if (result && typeof result.catch === 'function') result.catch(() => {});
    }
  }

  return {
    name: 'web-audio',
    get state() {
      return context ? context.state : 'closed';
    },
    init() {
      if (context) return;
      context = createContext();
      limiter = context.createDynamicsCompressor();
      limiter.threshold.value = -1;
      limiter.knee.value = 0;
      limiter.ratio.value = 20;
      limiter.attack.value = 0.003;
      limiter.release.value = 0.1;
      limiter.connect(context.destination);
      master = context.createGain();
      master.connect(limiter);
      if (gestureTarget && typeof gestureTarget.addEventListener === 'function') {
        const handler = () => {
          unlock();
          if (context.state !== 'suspended' && removeGestureListeners) removeGestureListeners();
        };
        for (const type of GESTURE_EVENTS) gestureTarget.addEventListener(type, handler);
        removeGestureListeners = () => {
          for (const type of GESTURE_EVENTS) gestureTarget.removeEventListener(type, handler);
          removeGestureListeners = null;
        };
      }
    },
    dispose() {
      if (removeGestureListeners) removeGestureListeners();
      if (context && typeof context.close === 'function') context.close();
      context = null;
      buses.clear();
    },
    unlock,
    // A second call for a name keeps the same gain node, so voices already on the bus stay on the bus that setBusVolume moves.
    createBus(name, volume) {
      const existing = buses.get(name);
      if (existing) {
        setParameter(existing.gain, volume, requireContext().currentTime);
        return;
      }
      const gain = requireContext().createGain();
      gain.gain.value = volume;
      gain.connect(master);
      buses.set(name, gain);
    },
    setBusVolume(name, volume) {
      const bus = name === 'master' ? master : buses.get(name);
      setParameter(bus.gain, volume, requireContext().currentTime);
    },
    async decode(source) {
      const audioContext = requireContext();
      if (typeof source === 'string') {
        if (!fetchBytes) throw new Error('No fetch is available to load a sound from a URL. Pass an ArrayBuffer or a decoded AudioBuffer instead.');
        const response = await fetchBytes(source);
        if (!response.ok) throw new Error(`Loading the sound ${source} failed with status ${response.status}.`);
        return audioContext.decodeAudioData(await response.arrayBuffer());
      }
      if (source instanceof ArrayBuffer) return audioContext.decodeAudioData(source);
      if (source && typeof source.duration === 'number') return source;
      throw new TypeError(`A sound source must be a URL string, an ArrayBuffer or a decoded AudioBuffer, got ${describe(source)}.`);
    },
    setListener(pose) {
      const audioContext = requireContext();
      setListenerPose(audioContext.listener, pose, audioContext.currentTime);
    },
    startVoice(voiceOptions) {
      const audioContext = requireContext();
      const now = audioContext.currentTime;
      const source = audioContext.createBufferSource();
      source.buffer = voiceOptions.buffer;
      source.loop = voiceOptions.loop;
      source.playbackRate.value = voiceOptions.pitch;
      const gain = audioContext.createGain();
      gain.gain.value = voiceOptions.volume;
      let filter = null;
      let panner = null;
      let tail = source;
      if (voiceOptions.spatial) {
        const spatial = voiceOptions.spatial;
        if (spatial.occlusion) {
          filter = audioContext.createBiquadFilter();
          filter.type = 'lowpass';
          filter.frequency.value = occlusionHertz(voiceOptions.occlusion);
          tail.connect(filter);
          tail = filter;
        }
        panner = audioContext.createPanner();
        panner.panningModel = 'HRTF';
        panner.distanceModel = spatial.model;
        panner.refDistance = spatial.referenceDistance;
        panner.maxDistance = spatial.maximumDistance;
        panner.rolloffFactor = spatial.rolloff;
        setPannerPosition(panner, voiceOptions.position, now);
        tail.connect(panner);
        tail = panner;
      }
      tail.connect(gain);
      gain.connect(buses.get(voiceOptions.bus));
      let ended = false;
      source.onended = () => {
        ended = true;
        voiceOptions.onEnded();
      };
      source.start(now);
      return {
        update(change) {
          const time = audioContext.currentTime;
          setParameter(gain.gain, change.volume, time);
          setParameter(source.playbackRate, change.pitch, time);
          if (panner) setPannerPosition(panner, change.position, time);
          if (filter) setParameter(filter.frequency, occlusionHertz(change.occlusion), time);
        },
        stop() {
          if (ended) return;
          ended = true;
          source.onended = null;
          try {
            source.stop();
          } catch {
            // A source that never started or already ended throws; either way it is silent.
          }
          source.disconnect();
        },
      };
    },
  };
}

// ---- The audio system ----

function resolveNumber(value, data, label, minimum, maximum) {
  const resolved = typeof value === 'function' ? value(data) : value;
  return requireNumberInRange(resolved, label, minimum, maximum);
}

function createSeededRandom(seed) {
  let state = seed >>> 0;
  return () => {
    state = (state + 0x6d2b79f5) >>> 0;
    let mixed = Math.imul(state ^ (state >>> 15), 1 | state);
    mixed = (mixed + Math.imul(mixed ^ (mixed >>> 7), 61 | mixed)) ^ mixed;
    return ((mixed ^ (mixed >>> 14)) >>> 0) / 4294967296;
  };
}

export function createAudio(options = {}) {
  const backend = options.backend ?? webAudioBackend(options.webAudio);
  const maximumVoices = requireWholeNumberInRange(options.maximumVoices ?? AUDIO_LIMITS.defaultVoices, 'createAudio maximumVoices', 1, AUDIO_LIMITS.maximumVoices);
  const occluder = options.occlusion ?? null;
  if (occluder !== null && typeof occluder !== 'function') {
    throw new TypeError('createAudio occlusion must be a function (from, to) => 0 to 1, or left out.');
  }
  const listenerSource = options.listener ?? null;
  if (listenerSource !== null && typeof listenerSource !== 'function') {
    throw new TypeError('createAudio listener must be a function () => camera frame { eye, target, up }, or left out.');
  }
  const random = createSeededRandom(options.seed ?? 1);
  const sounds = new Map();
  const bindings = new Map(); // event name -> [{ sound, options }]
  const actionEvents = new Map(); // action name -> event name
  const busVolumes = new Map();
  const voices = [];
  let bindingCount = 0;
  let nextVoiceId = 1;
  let started = false;
  let input = options.input ?? null;
  let listenerPose = { position: [0, 0, 0], forward: [0, 0, -1], up: [0, 1, 0] };

  function createBus(name, volume = 1) {
    requireName(name, 'bus name');
    requireNumberInRange(volume, `bus ${name} volume`, 0, 4);
    if (name === 'master') throw new RangeError('The bus name master is reserved for the output level. Use setBusVolume("master", volume) to change it.');
    if (!busVolumes.has(name) && busVolumes.size >= AUDIO_LIMITS.maximumBuses) {
      throw new RangeError(`An audio can have at most ${AUDIO_LIMITS.maximumBuses} buses, so ${name} was not added.`);
    }
    busVolumes.set(name, volume);
    if (started) backend.createBus(name, volume);
  }

  busVolumes.set('master', 1);
  for (const name of DEFAULT_BUSES) busVolumes.set(name, 1);
  for (const [name, volume] of Object.entries(options.buses ?? {})) createBus(name, volume);

  function requireBus(name) {
    if (!busVolumes.has(name) || name === 'master') {
      throw new RangeError(`Unknown bus ${String(name)}. Use one of ${[...busVolumes.keys()].filter(key => key !== 'master').join(', ')} or add it with createBus(name).`);
    }
    return name;
  }

  function requireSound(name) {
    const sound = sounds.get(name);
    if (!sound) {
      throw new RangeError(`Unknown sound ${String(name)}. Define it first with audio.defineSound(name, { buffer }) or await audio.load(name, source). Known: ${[...sounds.keys()].join(', ') || 'none'}.`);
    }
    return sound;
  }

  function defineSound(name, definition) {
    requireName(name, 'sound name');
    if (definition === null || typeof definition !== 'object') {
      throw new TypeError(`defineSound(${name}, definition) needs { buffer, bus, volume, pitch, loop, spatial }, got ${describe(definition)}.`);
    }
    if (!sounds.has(name) && sounds.size >= AUDIO_LIMITS.maximumSounds) {
      throw new RangeError(`An audio can hold at most ${AUDIO_LIMITS.maximumSounds} sounds, so ${name} was not added.`);
    }
    if (!definition.buffer || typeof definition.buffer.duration !== 'number') {
      throw new TypeError(`defineSound(${name}) buffer must be a decoded AudioBuffer. To load a URL or ArrayBuffer use await audio.load(name, source).`);
    }
    const sound = Object.freeze({
      name,
      buffer: definition.buffer,
      bus: requireBus(definition.bus ?? 'effects'),
      volume: requireNumberInRange(definition.volume ?? 1, `sound ${name} volume`, 0, 4),
      pitch: requireNumberInRange(definition.pitch ?? 1, `sound ${name} pitch`, 0.1, 4),
      pitchVariance: requireNumberInRange(definition.pitchVariance ?? 0, `sound ${name} pitchVariance`, 0, 1),
      loop: definition.loop === true,
      maximumInstances: requireWholeNumberInRange(definition.maximumInstances ?? AUDIO_LIMITS.defaultInstancesPerSound, `sound ${name} maximumInstances`, 1, AUDIO_LIMITS.maximumInstancesPerSound),
      spatial: normalizeSpatial(definition.spatial, `sound ${name}`),
    });
    sounds.set(name, sound);
    return sound;
  }

  async function load(name, source, definition = {}) {
    requireName(name, 'sound name');
    backend.init();
    const buffer = await backend.decode(source);
    return defineSound(name, { ...definition, buffer });
  }

  // ---- Voices ----

  function voiceLevel(voice) {
    const sound = voice.sound;
    let level = voice.volume * busVolumes.get(sound.bus) * busVolumes.get('master');
    if (voice.position && sound.spatial) {
      level *= distanceGain(distanceBetween(voice.position, listenerPose.position), sound.spatial);
      level *= 1 - OCCLUDED_GAIN_LOSS * voice.occlusion;
    }
    return level;
  }

  function resolveVoicePosition(voice) {
    return readNodePosition(voice.node, `sound ${voice.sound.name} node`);
  }

  function measureOcclusion(voice) {
    if (!occluder || !voice.sound.spatial?.occlusion || !voice.position) return 0;
    return requireNumberInRange(occluder(listenerPose.position, voice.position), 'occlusion function result', 0, 1);
  }

  // The per-frame path never throws: a bad occlusion value is clamped so one callback cannot halt the runtime loop.
  function measureOcclusionSafely(voice) {
    if (!occluder || !voice.sound.spatial?.occlusion || !voice.position) return 0;
    const measured = Number(occluder(listenerPose.position, voice.position));
    return Number.isFinite(measured) ? Math.min(Math.max(measured, 0), 1) : 0;
  }

  function removeVoice(voice) {
    const index = voices.indexOf(voice);
    if (index >= 0) voices.splice(index, 1);
  }

  function stopVoice(voice) {
    voice.backendVoice.stop();
    removeVoice(voice);
  }

  function makeRoom(sound, level) {
    const sameSound = voices.filter(voice => voice.sound === sound);
    if (sameSound.length >= sound.maximumInstances) stopVoice(sameSound[0]);
    if (voices.length < maximumVoices) return true;
    const quietest = voices.reduce((lowest, voice) => (voice.level < lowest.level ? voice : lowest), voices[0]);
    if (quietest.level >= level) return false;
    stopVoice(quietest);
    return true;
  }

  // Plays a sound. Options: position [x, y, z] or node (follows it), volume, pitch, bus, loop. Returns a handle, or null when
  // the voice limit is full of louder sounds.
  function play(soundName, playOptions = {}) {
    const sound = requireSound(soundName);
    startBackend();
    const volume = sound.volume * requireNumberInRange(playOptions.volume ?? 1, `play ${soundName} volume`, 0, 4);
    const variance = sound.pitchVariance === 0 ? 0 : (random() * 2 - 1) * sound.pitchVariance;
    const basePitch = requireNumberInRange(sound.pitch * requireNumberInRange(playOptions.pitch ?? 1, `play ${soundName} pitch`, 0.1, 4), `play ${soundName} resulting pitch`, MINIMUM_VOICE_PITCH, MAXIMUM_VOICE_PITCH);
    // Random variance is the sound's own setting, so it must never make a valid play throw; it stays inside the playable range.
    const pitch = Math.min(Math.max(basePitch * (1 + variance), MINIMUM_VOICE_PITCH), MAXIMUM_VOICE_PITCH);
    const voice = {
      id: nextVoiceId,
      sound,
      node: playOptions.node ?? null,
      position: null,
      volume,
      pitch,
      loop: playOptions.loop ?? sound.loop,
      occlusion: 0,
      level: 0,
      backendVoice: null,
    };
    if (sound.spatial) {
      if (voice.node === null && playOptions.position === undefined) {
        throw new TypeError(`Sound ${soundName} is spatial, so play it with { position: [x, y, z] } or { node }. For a flat sound define it without spatial.`);
      }
      voice.position = voice.node === null
        ? requireVector(playOptions.position, `play ${soundName} position`)
        : resolveVoicePosition(voice);
    }
    voice.occlusion = measureOcclusion(voice);
    voice.level = voiceLevel(voice);
    if (!makeRoom(sound, voice.level)) return null;
    nextVoiceId += 1;
    voice.backendVoice = backend.startVoice({
      buffer: sound.buffer,
      bus: sound.bus,
      volume: voice.volume,
      pitch: voice.pitch,
      loop: voice.loop,
      spatial: sound.spatial,
      position: voice.position,
      occlusion: voice.occlusion,
      onEnded: () => removeVoice(voice),
    });
    voices.push(voice);
    return Object.freeze({
      id: voice.id,
      sound: soundName,
      stop: () => stopVoice(voice),
      get playing() {
        return voices.includes(voice);
      },
      get level() {
        return voice.level;
      },
    });
  }

  // A sound that follows a node: loops by default, so an engine hum stays on its vehicle until stop() is called.
  function attach(node, soundName, playOptions = {}) {
    return play(soundName, { loop: true, ...playOptions, node });
  }

  function stopAll(soundName) {
    for (const voice of [...voices]) {
      if (soundName === undefined || voice.sound.name === soundName) stopVoice(voice);
    }
  }

  // The active voices, for tests and a debug overlay: level is the predicted output level after bus, distance and occlusion.
  function activeVoices() {
    return voices.map(voice => Object.freeze({
      id: voice.id,
      sound: voice.sound.name,
      bus: voice.sound.bus,
      volume: voice.volume,
      pitch: voice.pitch,
      loop: voice.loop,
      position: voice.position ? [...voice.position] : null,
      occlusion: voice.occlusion,
      level: voice.level,
    }));
  }

  // ---- Events ----

  // Bind an event name to a sound. volume, pitch and position are numbers or functions (eventData) => value, so a contact's
  // impulse can set the loudness: bindEvent('contact', 'thud', { volume: data => Math.min(1, data.impulse / 20) }).
  function bindEvent(eventName, soundName, bindOptions = {}) {
    requireName(eventName, 'event name');
    requireSound(soundName);
    if (bindingCount >= AUDIO_LIMITS.maximumBindings) {
      throw new RangeError(`An audio can hold at most ${AUDIO_LIMITS.maximumBindings} event bindings, so ${eventName} was not bound.`);
    }
    for (const field of ['volume', 'pitch']) {
      const value = bindOptions[field];
      if (value !== undefined && typeof value !== 'function' && !Number.isFinite(value)) {
        throw new TypeError(`bindEvent ${eventName} ${field} must be a number or a function (eventData) => number, got ${describe(value)}.`);
      }
    }
    if (!bindings.has(eventName)) bindings.set(eventName, []);
    const entry = { soundName, options: bindOptions };
    bindings.get(eventName).push(entry);
    bindingCount += 1;
    return () => {
      const list = bindings.get(eventName);
      const index = list ? list.indexOf(entry) : -1;
      if (index >= 0) {
        list.splice(index, 1);
        bindingCount -= 1;
      }
    };
  }

  function playBinding(entry, data) {
    const settings = entry.options;
    const playOptions = {
      volume: settings.volume === undefined ? 1 : resolveNumber(settings.volume, data, `${entry.soundName} volume`, 0, 4),
      pitch: settings.pitch === undefined ? 1 : resolveNumber(settings.pitch, data, `${entry.soundName} pitch`, 0.1, 4),
    };
    const position = typeof settings.position === 'function' ? settings.position(data) : settings.position ?? data?.position;
    if (settings.node !== undefined) playOptions.node = settings.node;
    else if (position !== undefined) playOptions.position = position;
    return play(entry.soundName, playOptions);
  }

  // Fires every sound bound to the event. Returns the handles that started.
  function emit(eventName, data = {}) {
    requireName(eventName, 'event name');
    const handles = [];
    for (const entry of [...(bindings.get(eventName) ?? [])]) {
      const handle = playBinding(entry, data);
      if (handle) handles.push(handle);
    }
    return handles;
  }

  // Input: a pressed action fires the event input:<action>. The input system must run before this one.
  function bindAction(actionName, soundName, bindOptions = {}) {
    requireName(actionName, 'action name');
    if (!input) throw new TypeError('bindAction needs an input: pass createAudio({ input }) or call audio.setInput(input).');
    const eventName = `input:${actionName}`;
    actionEvents.set(actionName, eventName);
    return bindEvent(eventName, soundName, bindOptions);
  }

  function setInput(newInput) {
    if (!newInput || typeof newInput.wasPressed !== 'function') {
      throw new TypeError('setInput needs an input from createInput (it has wasPressed(action)).');
    }
    input = newInput;
  }

  // Physics contacts (the recorded scene's contactEvents): each started event fires contact (or sensor), plus
  // contact:<collider> for both colliders, so a sound can bind to one body. data.position comes from options.position(event).
  function emitContacts(contactEvents, contactOptions = {}) {
    if (!Array.isArray(contactEvents)) {
      throw new TypeError(`emitContacts needs an array of contact events { started, kind, colliderA, colliderB, ... }, got ${describe(contactEvents)}.`);
    }
    for (const event of contactEvents) {
      if (event.started === false) continue;
      const data = contactOptions.position ? { ...event, position: contactOptions.position(event) } : event;
      const kind = event.kind === 'sensor' ? 'sensor' : 'contact';
      emit(kind, data);
      emit(`${kind}:${String(event.colliderA)}`, data);
      emit(`${kind}:${String(event.colliderB)}`, data);
    }
  }

  // Animation markers crossed between two clip times fire marker:<name>, with the marker and extra data in the event data.
  function emitMarkers(markers, fromTime, toTime, markerOptions = {}) {
    for (const marker of markersCrossed(markers, fromTime, toTime, markerOptions)) {
      emit(`marker:${marker.name}`, { ...markerOptions.data, marker, time: marker.time });
    }
  }

  // ---- Mixing ----

  function setBusVolume(name, volume) {
    requireNumberInRange(volume, `bus ${String(name)} volume`, 0, 4);
    if (name !== 'master') requireBus(name);
    busVolumes.set(name, volume);
    if (started) backend.setBusVolume(name, volume);
    for (const voice of voices) voice.level = voiceLevel(voice);
  }

  function getBusVolume(name) {
    if (!busVolumes.has(name)) requireBus(name);
    return busVolumes.get(name);
  }

  function setListener(camera) {
    listenerPose = readListener(camera);
    if (started) backend.setListener(listenerPose);
  }

  function synchronize() {
    if (listenerSource) {
      try {
        setListener(listenerSource());
      } catch {
        // Keep the last good listener pose when the source returns a bad frame.
      }
    }
    for (const voice of [...voices]) {
      if (voice.node !== null && voice.sound.spatial) {
        try {
          voice.position = resolveVoicePosition(voice);
        } catch {
          // The node is gone (a destroyed entity): end this voice and keep the others playing.
          stopVoice(voice);
          continue;
        }
      }
      voice.occlusion = measureOcclusionSafely(voice);
      voice.level = voiceLevel(voice);
      voice.backendVoice.update({ volume: voice.volume, pitch: voice.pitch, position: voice.position, occlusion: voice.occlusion });
    }
  }

  function pollActions() {
    if (!input) return;
    for (const [actionName, eventName] of actionEvents) {
      if (input.wasPressed(actionName)) emit(eventName, { action: actionName });
    }
  }

  // ---- Runtime system ----

  function startBackend() {
    if (started) return;
    backend.init();
    for (const [name, volume] of busVolumes) {
      if (name !== 'master') backend.createBus(name, volume);
    }
    backend.setBusVolume('master', busVolumes.get('master'));
    backend.setListener(listenerPose);
    started = true;
  }

  return {
    name: options.name ?? 'audio',
    init() {
      startBackend();
    },
    fixedUpdate(step, context) {
      // The input system samples in fixed steps in every mode except 'variable', so actions are read where it samples.
      if (context?.mode !== 'variable') pollActions();
      if (context?.mode === 'fixed') synchronize();
    },
    update(delta, context) {
      if (context?.mode === 'variable') pollActions();
      synchronize();
    },
    dispose() {
      stopAll();
      backend.dispose();
      started = false;
    },
    backend,
    defineSound,
    load,
    createBus,
    setBusVolume,
    getBusVolume,
    play,
    attach,
    stopAll,
    activeVoices,
    bindEvent,
    bindAction,
    setInput,
    emit,
    emitContacts,
    emitMarkers,
    setListener,
    synchronize,
    unlock: () => backend.unlock?.(),
  };
}