ambiX B-format to Binaural — Spat5 Decode+HRTF

Decodes an ambiX B-format master (ACN/SN3D) to binaural stereo via a two-stage Spat5 chain: HOA decoder → virtual loudspeaker feeds → HRTF convolution. Supports 1st–5th order, multiple layouts, and SOFA HRTFs.

Author: Shai Cohen Affiliation: Department of Music, Bar-Ilan University, Israel Version: 1.8 (2026) License: MIT License Repo: https://github.com/ShaiCohen-ops/Praat-plugin_AudioTools

Contents:

What this does Quick start Two-Stage Pipeline Speaker Layouts Dependencies Applications

What this does

This script implements a two-stage ambiX B-format to binaural renderer using IRCAM's Spat5 tools. It takes an ambiX B-format master (ACN/SN3D, Full 3D), decodes it to virtual loudspeaker feeds via spat5.hoa.decoder~, then convolves those feeds with a SOFA HRTF via spat5.virtualspeakers~ to produce a binaural stereo output. The input is ALREADY B-format — this script decodes it and NEVER re-encodes it.

What this is NOT: This is not the loudspeaker-feed tool. The loudspeaker tool takes speaker feeds and applies HRTF to make them binaural. This tool takes B-format (W,Y,Z,X...), decodes it to speaker feeds, then applies HRTF. The input channels are Ambisonic components, not loudspeaker feeds. If you have loudspeaker feeds, use Multichannel_to_Binaural.praat instead.

Key Features:

Orders 1–5 — auto-detected from channel count (4, 9, 16, 25, 36 ch)
8 Speaker Layouts — Auto (3rd order → 22.2), 2.0, 4.0, 5.0, 7.0, 7.1, 3D 22.2, plus Custom
SOFA HRTF support — customise with any SOFA file
Room acoustics — Direct, Hall, Livingroom, Studio
Processing headroom — adjustable pre-gain to prevent clipping
Validation — WAV re-read, channel/sample-rate/sample-count checks
Visualisation — input W/omni component, binaural L/R waveforms, parameter summary

Third-order Auto policy: When using a 3rd-order (16-channel) input with the Auto layout, the script uses Spat5's built-in 22.2 full-sphere 24-speaker layout and an energy-preserving (EPAD) decoder. This provides a genuine 3-D decode, avoiding the under-determined 7.1 layout that would collapse vertical detail.

Quick start

Ensure Spat5 is installed and the tools folder is correct (e.g., C:/Users/User/Documents/Max 9/Packages/spat5-x64/media/tools/).
In Praat, select one Sound object — an ambiX B-format master (4, 9, 16, 25, or 36 channels, ACN/SN3D).
Run script… → ambiX_Bformat_to_Binaural.praat.
Set the Tools_folder to your Spat5 tools directory.
Choose a Layout_preset (Auto, 2.0, 4.0, 5.0, 7.0, 7.1, 3D 22.2, or Custom).
Select Render_mode (Fast preview or Final).
Set SOFA_file (e.g., kemar for the default Spat5 HRTF, or a path to a .sofa file).
Click OK — the script calls the Python bridge, which runs the two-stage Spat5 pipeline, imports the binaural result, and validates it.

Quick tip: Use Auto layout for most inputs — it selects the appropriate layout based on the order (3rd order → 22.2). Use Fast preview for quick checks. The SOFA_file can be a built-in token (kemar, bi, etc.) or a full path to a .sofa file. The output is a 2-channel binaural Sound in Praat memory — no final WAV is saved.

Important: The input channels are Ambisonic components (W, Y, Z, X, ...), not loudspeaker feeds. The script decodes them first and never re-encodes them. Ensure your B-format uses the ACN/SN3D convention with the ambiX azimuth convention (CCW from front, +Y = left). This script auto-detects order from channel count and validates the decoder preset before running Spat5. Processing headroom is applied before Spat5 and is not restored — no post-normalisation occurs.

Two-Stage Pipeline

Stage 1 HOA Decoder

spat5.hoa.decoder~ — B-format → virtual loudspeaker feeds

Input: ambiX B-format (ACN/SN3D, Full 3D)
Decoder preset: OSC command list with /order, /dimension 3, /norm SN3D, speaker positions
Output: N-channel WAV (virtual loudspeaker feeds)

Auto 22.2 preset: For 3rd order, the script expands a compact marker to the full 24-speaker 22.2 EPAD preset — no long command-line arguments on Windows.

Stage 2 HRTF Convolution

spat5.virtualspeakers~ — loudspeaker feeds → binaural stereo

Input: virtual loudspeaker feeds (from Stage 1)
HRTF: SOFA file or built-in token (e.g., kemar)
Optional: ITD percentage, room acoustics (hall, livingroom, studio)
Output: 2-channel binaural WAV

Decoder OSC preset validation: The script validates the decoder preset before launching Spat5, checking for /order, /dimension 3, /norm SN3D, /speaker/number, and /speaker/N/ae messages. This catches common failures (e.g., using a symbolic preset name like "hoa1_cube") and gives a useful log entry.

Speaker Layouts

Layout	Speakers	Description
Auto	varies	3rd order → 22.2 (24 speakers); lower orders → 7.1 or 4.0
2.0	2	Stereo pair (±30°)
4.0	4	Quad (FL, FR, RL, RR)
5.0	5	Pentagon (5 evenly spaced)
7.0	7	7.0 surround
7.1	8	7.1 surround (LFE silent)
3D 22.2	24	Full-sphere 22.2 layout (24 speakers)
Custom	user	Advanced: set custom_layout$ and custom_decoder_preset$ in the script

22.2 layout: The 24-speaker layout used by Spat5's built-in 22.2 token. Channel order: FL, FR, FC, LFE1, BL, BR, FLc, FRc, BC, LFE2, SiL, SiR, TpFL, TpFR, TpFC, TpC, TpBL, TpBR, TpSiL, TpSiR, TpBC, BtFC, BtFL, BtFR. Azimuth/elevation coordinates follow the ambiX convention.

Dependencies

Spat5 (IRCAM)

spat5.hoa.decoder~ — HOA decoder
spat5.virtualspeakers~ — HRTF convolution
Part of the IRCAM Spat5 package (Max/MSP externals and command-line tools)
Tools folder: .../Packages/spat5-x64/media/tools/

Python 3

The bridge script spat_bformat_bridge.py (sits next to this Praat script)
Stdlib only — no numpy required
Version handshake prevents an old bridge from running silently

SOFA HRTF

Built-in tokens: kemar, bi, etc.
Custom: path to a .sofa file
If it looks like a path and isn't found, the script exits with a clear error

Python discovery: The script probes for python, py, and python3 on Windows, and python3, python, py on macOS/Linux. A stdlib dependency check is run (sys, os, subprocess, struct, math) to confirm the Python environment is working before launching the bridge.

Applications

Ambisonic binaural monitoring

Use case: Listen to a B-format master over headphones with proper spatialisation.

Settings: Auto layout, SOFA = kemar, Room = Direct. The output is binaural stereo ready for headphone listening.

Quality control / verification

Use case: Verify that an encoded B-format file sounds correct before delivering it.

Settings: Fast preview mode, 2.0 or 4.0 layout for quick checks. The validation report includes peak, RMS, and L/R correlation.

Room acoustics simulation

Use case: Place the ambisonic soundfield in a simulated room (hall, livingroom, studio).

Settings: Room = hall/livingroom/studio. Spat5's virtualspeakers applies room impulse responses in addition to HRTF.

Higher-order ambisonic delivery

Use case: Create binaural renders from 4th- or 5th-order ambisonic masters.

Settings: Input with 25 or 36 channels (orders 4–5), Auto layout. The script auto-detects the order and uses the appropriate decoder.

Workflow: 3rd-order ambiX → binaural for headphone listening

Input: 16-channel ambiX Sound (ACN/SN3D).
Settings: Auto layout, SOFA = kemar, Room = Direct, Render_mode = Final.
Result: A 2-channel binaural Sound in Praat memory. The output is validated (peak, RMS, correlation) and can be played directly. No final WAV is saved.

Workflow: 5.1 binaural preview from ambisonic master

Input: 3rd-order ambiX master.
Settings: Layout = 5.1, SOFA = kemar, Room = Direct.
Result: The ambisonic master is decoded to 5.1 speaker feeds, then binauralised. The 5.1 decode is approximate (non-uniform layout), but the output provides a surround-sound preview over headphones.

Workflow: Room acoustics check

Input: Any B-format master.
Settings: Auto layout, Room = hall, Render_mode = Fast preview.
Result: The binaural output includes the hall's room impulse response — a quick way to hear how the soundfield would sound in a different space.

Troubleshooting:
• "spat5.hoa.decoder~ not found" — Check the Tools Folder in the form. It should point to the tools/ directory inside your Spat5 package.
• "Python bridge version mismatch" — The bridge file (spat_bformat_bridge.py) is outdated. Update it from the repository.
• Output validation fails — The script re-reads the output WAV to confirm channel count, sample rate, and sample count. If validation fails, the file is deleted and the script aborts.
• Binaural output is silent or has L/R correlation near 1 — Check the decoder-layout correspondence. A mismatch can collapse the image to dual-mono. The log reports the decoder speaker count and the layout's expected count.
• Under-determined decode warning — If the number of speaker feeds is fewer than the Ambisonic channel count, the spatial image may be degraded. Use a layout with more speakers (e.g., 22.2 for 3rd order).

Visualisation

When Draw_visualization is enabled, the script generates:

Input B-format — W / omni component (channel 1 / ACN0) of the input.
Output binaural — L ear (blue) and R ear (orange) waveforms.
Parameters panel — order, decoder preset, layout, SOFA, ITD, room, mode, tail, headroom.
Summary bar — result name, duration, peak dBFS, validation status.

The visualisation helps verify that the binaural output has the expected stereo image and amplitude.