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.
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.
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:
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:
cd web && timeout -k 5 30000 npm run test -- src/lib/__tests__/advanced-audio-engine.test.ts