# Metaverse Spatial Audio Pipeline

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
```
