AmbiTap

A target-independent C++20 library for higher-order ambisonics (HOA), using the AmbiX convention throughout (ACN channel ordering, SN3D normalization).

AmbiTap is the shared core for three wrapper targets:

• Native C++ applications — link the library directly
• Max/MSP — multichannel (mc.) externals via min-api (planned)
• Pure Data — multichannel externals, Pd ≥ 0.54 (planned)

What's here

include/ambitap/
├── ambitap.h            umbrella header
└── math/
    ├── core/            spherical harmonics, ACN indexing, SN3D/N3D, SH rotation
    ├── geometry/        3D convex hull, VBAP speaker layouts, presets, T-designs
    ├── decoding/        mode-matching, ALLRAD, EPAD decoder construction, max-rE
    └── binaural/        Ooura real-FFT wrapper, partitioned overlap-save convolver,
                         embedded SH-domain MIT KEMAR HRTF (order 5, LS + MagLS),
                         optional SOFA reader

The library is header-only apart from one tiny static target (AmbiTap::fft, the vendored Ooura fftsg.c). A stateful DSP "processor" layer (ambitap::dsp) and UI-feeding analysis (ambitap::analysis) build on the math layer; the processors are runtime-sized with a wait-free real-time process() path.

Building

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
ctest --test-dir build --output-on-failure

Requirements: CMake ≥ 3.21, a C++20 compiler. Eigen is found via an existing Eigen3::Eigen target, an installed Eigen, or a pinned FetchContent download — in that order. GoogleTest is fetched automatically when tests are enabled.

Consuming

add_subdirectory(path/to/AmbiTap)   # or find_package(AmbiTap) once installed
target_link_libraries(my_target PRIVATE AmbiTap::ambitap)

Options:

Option	Default	Effect
AMBITAP_ENABLE_SOFA	OFF	FetchContent libmysofa v1.3.4 and define AMBITAP_HAS_SOFA, enabling ambitap/math/binaural/sofa_reader.h
AMBITAP_BUILD_TESTS	ON when top-level	Build the GTest suite

Conventions

• Channel ordering: ACN. Normalization: SN3D (AmbiX). FuMa conversion lives in the wrapper targets, not here.
• Angles: radians; azimuth 0 = front, +π/2 = left; elevation 0 = horizon, +π/2 = zenith.
• Decoder constructors return Eigen matrices shaped (speakers × channels) with speaker_signals = D * hoa.

Third-party

• Ooura FFT (third_party/ooura/) — Takuya Ooura's split-radix FFT package; freely usable with attribution (see third_party/ooura/readme.txt).
• Eigen — MPL2, header-only, not vendored.
• MIT KEMAR HRTF — math/binaural/hrtf_data.h is a spherical-harmonic projection of the MIT KEMAR (normal pinna) measurements of W. G. Gardner and K. D. Martin (HRTF Measurements of a KEMAR Dummy-Head Microphone, MIT Media Lab Tech. Report #280, 1994), generated via scripts/generate_hrtf.py. The KEMAR data is distributed free by the MIT Media Lab on the condition that the authors are credited.
• libmysofa — BSD-3, optional, fetched only with AMBITAP_ENABLE_SOFA=ON.
• Hardin–Sloane spherical t-designs — math/geometry/tdesigns.h is generated by scripts/generate_tdesigns.py from the original, freely distributed tables of R. H. Hardin and N. J. A. Sloane (McLaren's Improved Snub Cube and Other New Spherical Designs in Three Dimensions, Discrete & Computational Geometry 15 (1996), 429–441), hosted at http://neilsloane.com/sphdesigns/. The point coordinates are mathematical facts taken from that catalogue rather than from any redistribution-licensed repackaging.

License

MIT — © 2025–2026 Timothy Place. See LICENSE. The bundled and fetched third-party components above keep their own permissive licenses; their notices and attribution requirements are collected in THIRD_PARTY_NOTICES.md.