spaudio

Spatial audio for the Web Audio API. Multichannel panning, flexible speaker layouts, offline rendering to WAV.

Status: pre-1.0. API may change between minor versions.

Quick start

import { SpatialLayout, SpatialRouter, SpatialSource } from './src/index.js';

const ctx = new AudioContext();
const layout = SpatialLayout.octo();
const router = new SpatialRouter({ context: ctx, layout });
router.output.connect(ctx.destination);

const buffer = await fetch('sample.wav').then(r => r.arrayBuffer()).then(b => ctx.decodeAudioData(b));
const node = new AudioBufferSourceNode(ctx, { buffer });

const source = new SpatialSource({ node, position: { x: 0.5, y: -0.3 } });
router.add(source);
node.start();

source.setPosition({ x: -0.2, y: 0.4 });

Coordinate system

Positions are normalized to [-1, 1] on each axis. Origin (0, 0) is the centroid of the layout. x grows to the right, y grows forward (away from the listener). z is reserved for future height support.

API

SpatialLayout

Immutable description of a speaker arrangement.

SpatialLayout.stereo();
SpatialLayout.quad();                    // 4 speakers, 90° apart
SpatialLayout.octo();                    // 8 speakers, 45° apart
new SpatialLayout(speakers);             // custom

speakers is an array of { angle, radius, channel }:

• angle — degrees, 0° = front, clockwise
• radius — normalized distance from center, typically 1
• channel — output channel index (0-based)

Properties:

• layout.channels — number of output channels
• layout.speakers — readonly array of speaker descriptors

SpatialSource

Wraps a Web Audio source node with spatial metadata.

const source = new SpatialSource({
  node,                           // any AudioNode
  position: { x: 0, y: 0 }        // normalized -1..1
});

source.setPosition({ x, y });     // triggers router update if attached
source.position;                  // { x, y }
source.node;                      // underlying AudioNode

SpatialRouter

Routes sources to the layout's output channels using a panning algorithm.

const router = new SpatialRouter({
  context,                        // AudioContext or OfflineAudioContext
  layout,                         // SpatialLayout
  mode: 'dbap'                    // 'dbap' (default) | 'vbap' | 'equal-power'
});

router.add(source);
router.remove(source);
router.output;                    // AudioNode with layout.channels outputs
router.gainSnapshot(source);      // number[] — current gain per speaker, for visualizations
router.schedulePosition(source, { x, y }, time); // schedule DBAP gains at an explicit audio time

Connect router.output to context.destination for realtime playback, or let it feed an OfflineAudioContext destination for rendering.

Use schedulePosition() instead of source.setPosition() inside SpatialRenderer.toWav() callbacks — during offline setup currentTime is always 0, so setPosition() would collapse all keyframes to the same instant.

SpatialRenderer

Helper for offline rendering to WAV.

import { SpatialRenderer } from './src/index.js';

const wavBlob = await SpatialRenderer.toWav({
  layout: SpatialLayout.octo(),
  duration: 420,                  // seconds
  sampleRate: 48000,
  schedule: (ctx, router) => {
    // Build the scene inside the OfflineAudioContext.
    // Add sources to `router`, schedule `.start(time)` on nodes.
    // Use router.schedulePosition(source, { x, y }, time) to animate positions.
  }
});

Returns a Blob ready for download or upload.

Planned

Future classes, not yet implemented:

• SpatialListener — listener position and orientation for off-center audiences
• SpatialScene — aggregate of sources, listener, router, layout
• SpatialBus — submix with spatial metadata
• Ambisonic encoding (AmbiX, up to 5th order)

Requirements

• Web Audio API (all modern browsers)
• Multichannel playback requires Chrome 110+ with a multichannel audio interface recognized by the OS
• Offline rendering works on any browser supporting OfflineAudioContext

License

MIT