@audio/spatial-ambisonic

import { encode, decode, rotate } from '@audio/spatial-ambisonic'

Encodes mono sources into ambisonic B-format (real spherical harmonics up to order 3, ACN channel order, SN3D normalization — the AmbiX convention), rotates the encoded field by yaw/pitch/roll, and decodes it to a speaker layout or to binaural. SH definitions and SN3D/N3D normalization follow F. Zotter & M. Frank, Ambisonics (Springer Open, 2019) and J. Daniel's 2001 PhD thesis; ACN/SN3D and FuMa conversion follow Nachbar, Zotter, Deleflie & Sontacchi, "AMBIX — A Suggested Ambisonics Format" (Ambisonics Symposium 2011); max-rE weighting follows Gerzon's energy-vector criterion (1973/1985) as formalized by Daniel; the DirAC-style direction() analysis follows Merimaa & Pulkki (2005). For headphone output it decodes to a virtual speaker set and reuses @audio/spatial-binaural's structural (Brown-Duda) binaural panner per speaker.

Convention: azimuth in degrees, counter-clockwise from front (0° = front, +90° = left, -90° = right); elevation in degrees, positive up. This is the opposite sign of spatial-binaural's azimuth (0° front, +right) — decode(..., {layout:'binaural'}) converts explicitly at the boundary; nothing else in this package touches binaural's convention.

let mono = new Float32Array(44100)   // ...fill with a source signal
let bformat = encode(mono, { order: 1, az: 30, el: 0 })   // 4 channels, ACN/SN3D

let rotated = rotate(bformat, { yaw: 90 })                 // new arrays

let [L, R] = decode(rotated, { layout: 'stereo' })          // ±30° stereo
let [l, r] = decode(rotated, { layout: 'binaural' })        // headphones
let speakers = decode(rotated, { layout: 'octagon', weighting: 'maxre' })

encode(input, options)

input is either a mono Float32Array (uses the options above) or an array of { data, az, el, gain } sources, each with its own static direction, summed into the same output. No distance/near-field compensation — encode has no distance option (see Limits).

decode(channels, options)

'5.1'/'7.1' follow the @audio/compile CONTRACT's canonical order (L R C LFE Ls Rs[ Lrs Rrs]) with the LFE channel forced silent — ambisonics carries no LFE content, and decoding one from spatial channels would be fabricated, not derived. method: 'basic' needs the layout to have real angular spread across all (order+1)² dimensions the order requires: a horizontal-only layout (quad/5.1/7.1/octagon/stereo) can never mode-match-decode an order ≥ 1 elevation component (Z is identically zero at every point on the horizon) and throws rather than silently dropping it; use 'sampling' for those, or a genuinely 3-D layout ('cube', or enough custom points spread over the sphere).

rotate(channels, { yaw, pitch, roll })

Degrees. yaw is about the up axis with azimuth's own sign (positive yaw increases a source's azimuth — rotate(encode(az:30), {yaw:-30}) equals encode(az:0), exact to Float32 precision). pitch is about the left axis, positive = nose up. roll is about the front axis. Composition order is fixed: roll, then pitch, then yaw. Built by projecting a dense (≥4×channel-count) spherical-Fibonacci sample of directions through the target rotation and solving the resulting linear map by least squares — exact for band-limited SH (a rotation never mixes SH degrees), not an approximation; equivalent by construction to the Ivanic & Ruedenberg (1996) recursive block method.

Other exports

direction() returns { az, el, diffuseness, frames: [{t, az, el, diff}] }. It needs the first four (W, Y, Z, X) channels: the active-intensity vector I = ⟨W·[X,Y,Z]⟩ (frame-averaged) gives direction, and diffuseness = 1 - |I| / ⟨(W²+X²+Y²+Z²)/2⟩ — 0 for one coherent plane wave, rising toward 1 as sound arrives from many uncorrelated directions at once. Useful for tests and as a "where is the sound" meter; it is not a full DirAC synthesis stage.

Limits

• Sampling/mode-matching decoders only — no AllRAD for irregular layouts. The named layouts (stereo/quad/5.1/7.1/cube/octagon) are all regular enough for 'sampling'; check a custom layout's coverage yourself before relying on 'basic'.
• No near-field compensation — encode() has no distance/NFC-filter option; sources are always encoded as far-field plane waves.
• Binaural decode drops elevation — it decodes to a virtual speaker set and feeds each through spatial-binaural, which is azimuth-only (see that package's README); a virtual speaker's elevation only decides which ambisonic channels feed it, not its final binaural cue.
• Binaural virtual speaker sets are not exact spherical designs — order 1 uses an 8-point horizon ring (octagon); orders 2/3 use a 14/20-point spherical-Fibonacci lattice, inside the usual 12-20-point range but not an optimal t-design.

Use when: spatializing multiple sources into a rotatable, format-agnostic soundfield — game/VR audio, 360° video, or any pipeline that needs to encode once and decode later to whatever speaker layout (or headphones) is actually available.

Part of @audio/spatial — the spatial family umbrella.

MIT © audiojs