Eve library

Metaverse Spatial Audio Pipeline

Guide

Revision 1

On this page

The metaverse client now exposes a unified spatial audio layer that marries the Web Audio API graph with a Resonance Audio ambisonic scene. This document outlines how to configure virtual rooms, attach media sources, and inspect runtime metrics inside the AdvancedAudioEngine.

Room configuration#

Use configureSpatialAudioRoom to initialise or update a Resonance Audio scene. The helper normalises reflection, ambisonic order, and reverb gain before routing the scene output back into the engine’s master bus.

ts
const engine = AdvancedAudioEngine.getInstance();
await engine.configureSpatialAudioRoom({
  dimensions: { width: 18, height: 5, depth: 26 },
  materials: {
    left: 'brick-bare',
    right: 'curtain-heavy',
    front: 'glass-thin',
    back: 'wood-paneled',
    floor: 'wood-parquet',
    ceiling: 'acoustic-ceiling-tiles',
  },
  reflectionCoefficient: 0.68,
  reverbGain: 0.42,
  ambisonicOrder: 3,
  listener: {
    position: { x: 0, y: 1.6, z: -1.2 },
    orientation: {
      forward: { x: 0, y: 0, z: -1 },
      up: { x: 0, y: 1, z: 0 },
    },
  },
});

The engine computes Sabine RT60 estimates from the supplied materials (see RESONANCE_MATERIAL_ABSORPTION) and keeps a cached SpatialAudioRoomState for diagnostics.

Attaching spatial sources#

Audio elements loaded via loadAudio can be routed through Resonance Audio with attachSpatialAudioSource. The helper rewires the media element node, sets the source pose, directivity, and gain, and records runtime metrics such as distance-from-listener and room-send ratios.

ts
await engine.loadAudio('forest-bed', '/audio/forest/stream.mp3');
await engine.attachSpatialAudioSource({
  sourceId: 'forest-bed',
  audioId: 'forest-bed',
  position: { x: 2.4, y: 1.5, z: -3.2 },
  orientation: { x: 0, y: 0, z: -1 },
  directivity: { alpha: 0.6, sharpness: 0.75 },
  gain: 0.72,
  rolloff: 'logarithmic',
  spread: 90,
  roomContribution: 0.65,
});

When Resonance Audio is unavailable the engine automatically falls back to Web Audio PannerNode spatialisation so features degrade gracefully during SSR or simplified previews.

Runtime diagnostics#

getSpatialAudioSnapshot() exposes the current room state plus every registered source:

ts
const snapshot = engine.getSpatialAudioSnapshot();
// snapshot.room.metrics.predictedReverberationMs -> RT60 estimate
// snapshot.sources[0].metrics.distanceFromListener -> spatial mix cues

Use these metrics to surface telemetry overlays within the metaverse canvas or to validate ambience mixes in automated checks.

Verification#

Run the dedicated Vitest coverage to confirm the room setup, source wiring, and fallback behaviour:

bash
cd web && timeout -k 5 30000 npm run test -- src/lib/__tests__/advanced-audio-engine.test.ts