Higher-Order Ambisonic Decoder — HOA to Speakers

Decodes 1st-, 2nd-, or 3rd-order ACN/SN3D ambisonic channels to fixed horizontal loudspeaker layouts using Basic, Max-rE, or In-phase per-order weighting. The decoder accepts either one combined 4/9/16-channel Sound or separate mono ACN channels.

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

Contents:

What this does Quick start Input & validation Speaker layouts Decode matrix Output & peak protection Visualization Limits / troubleshooting

What this does

Higher-Order Ambisonic Decoder converts ACN/SN3D B-format channels into one feed per loudspeaker for one of eight fixed layouts. It is designed to match the companion encoder's channel order, normalization, and azimuth convention: 0° = front, angles increase counter-clockwise, +Y = left.

Horizontal decoder: Every loudspeaker direction in the decode matrix has elevation 0°. The script therefore does not reconstruct a vertical loudspeaker dimension. It evaluates the 3-D SN3D basis on the horizontal plane; some height-related components are zero on that plane while others can still contribute through their equatorial basis values. Do not describe the result as full 3-D speaker reproduction.

Sampling/projection approach: The decoder uses equal normalization by the number of directional speakers and evaluates the spherical-harmonic basis at the speaker directions. This is straightforward for regular horizontal arrays. The 5.1 and 7.1 presets are non-uniform and are explicitly reported by the script as approximate horizontal sampling decodes, not AllRAD/EPAD solutions.

Quick start

For the companion encoder's combined output, select exactly one 4-, 9-, or 16-channel Sound and leave Input_mode = Combined ambiX Sound.
For separate objects, choose Separate ACN channels and select exactly 4, 9, or 16 mono Sounds in ACN order, according to the chosen Ambisonic_order.
Choose a fixed Speaker_preset.
Choose Basic, Max-rE, or In-phase.
Leave Peak_protect_only enabled if you want attenuation only when the decoded output exceeds 0.99.
Click OK. The script creates one multichannel Sound in speaker-channel order and, by default, plays it.

Input & validation

Combined ambiX Sound

Requires exactly one selected Sound. The script accepts only 4, 9, or 16 channels and auto-detects 1st, 2nd, or 3rd order from that count. In this mode the form's Ambisonic_order choice is ignored. Each channel is extracted temporarily as ACN0, ACN1, … in file order.

Separate ACN channels

The form's selected order determines the required count: 4, 9, or 16. Every selected input must be mono and all must have identical sample rate and exact sample count. The script assumes the selected-object order is ACN0, ACN1, ….

Convention is assumed, not detected: A combined 4/9/16-channel Sound passes the channel-count test regardless of its actual channel ordering or normalization. The decoder does not read ambisonic metadata and cannot verify that an arbitrary input is really ACN/SN3D. Compatibility is by construction when used with the companion encoder.

Control	Default	Code behavior
Input_mode	Combined ambiX Sound	Combined auto-detects order; Separate uses the order menu and exact selected-object count.
Ambisonic_order	1st	Used only in Separate mode. Ignored and overwritten by channel-count detection in Combined mode.
Speaker_preset	Stereo pair	Selects one of eight fixed layouts below.
Decode_method	Basic	Selects the per-order weighting used in the matrix.
Peak_protect_only	yes	Shared attenuation only when the largest speaker-feed peak exceeds 0.99.
Draw_visualization	yes	Draws layout, decoder-row norms, mono output downmix, and summary.
Play_result	yes	Plays the decoded multichannel speaker-feed Sound directly.

Speaker layouts

Preset	Output channels in order	Azimuths	Directional count
Stereo pair	Spk1, Spk2	30°, 330°	2
Triangle	Spk1…3	0°, 120°, 240°	3
Quad	FL, FR, RL, RR	45°, 315°, 135°, 225°	4
Pentagon	Spk1…5	0°, 72°, 144°, 216°, 288°	5
Hexagon	Spk1…6	0°, 60°, 120°, 180°, 240°, 300°	6
Surround 5.1	L, R, C, LFE, Ls, Rs	30°, 330°, 0°, LFE, 110°, 250°	5; LFE silent
Surround 7.1	L, R, C, LFE, Ls, Rs, Lb, Rb	30°, 330°, 0°, LFE, 90°, 270°, 135°, 225°	7; LFE silent
Octagon	Spk1…8	0°, 45°, 90°, 135°, 180°, 225°, 270°, 315°	8

LFE handling: In 5.1 and 7.1, channel 4 is created but receives no ambisonic sum and remains silent. It is excluded from numDirectionalSpeakers, so it does not dilute the decode normalization.

The script computes a warning heuristic minSpeakers = 2 × order + 1 and compares it with the number of directional speakers. If the layout is below that threshold, it warns that direction and level reconstruction will be poor. This is a script heuristic, not a proof that meeting the threshold makes an arbitrary layout optimal.

Decode matrix

For each loudspeaker, the script evaluates the same real SN3D spherical-harmonic basis used by the encoder, at the loudspeaker's azimuth and at elevation 0°. It then applies one order-dependent decoder weight and divides by the number of directional loudspeakers.

For ambisonic order n and speaker s:
D[s,n,m] = Y[n,m](speaker_s) × (2n+1) × a_n / N_directional

Basic (projection)

a0 = a1 = a2 = a3 = 1. The only order weighting is the SN3D decode factor (2n+1), followed by division by the number of directional speakers.

Max-rE (energy vector)

The script computes rE = cos(137.9° / (N + 1.51)) and uses Legendre weights a_n = P_n(rE) through n=3.

In-phase

Uses the 3-D spherical weights a_n = N!(N+1)! / ((N+n+1)!(N-n)!). Implemented values are: N=1 → a1=1/3; N=2 → a1=1/2, a2=1/10; N=3 → a1=3/5, a2=1/5, a3=1/35.

The (2n+1) factor is part of this script's SN3D projection decode. The encoder and decoder use matching corrected 3rd-order basis terms, including sqrt(5/8) and sqrt(3/8) for ACN9/11/13/15-related terms.

5.1 / 7.1

The code itself labels these presets as non-uniform and an approximate horizontal sampling decode, adding that AllRAD/EPAD would be preferable for irregular arrays. No speaker-specific quadrature weights, optimization, bass management, or LFE derivation are implemented.

Output & peak protection

For each non-LFE loudspeaker, the decoder creates a silent mono Sound and sums every ambisonic channel multiplied by its matrix coefficient. LFE channels are left at zero. The speaker Sounds are then combined in preset order into one multichannel Sound named:

AmbiDecode_order_preset_method

The decoded Sound keeps the source duration and sample rate. Temporary speaker-feed objects are removed after the multichannel result is created. When the input was a combined ambisonic Sound, the temporary extracted ACN channels are also removed; the user's original input remains untouched.

Peak protection

With Peak_protect_only = yes, the script finds the largest absolute peak over all output speaker feeds. If it is above 0.99, every speaker feed receives the same factor 0.99 / globalPeak. Otherwise the levels are unchanged. This is attenuation-only; it does not normalize a quiet decode upward.

The decoder does not save a speaker-layout WAV and does not perform bass management. A 5.1/7.1 result therefore contains a silent LFE channel exactly as described above.

Visualization

With Draw_visualization = yes, v0.5.1 draws:

Speaker layout: top view with listener, directional labels, numbered speaker squares, and radial lines. The plot mirrors screen X so +90° appears on the left, matching the encoder.
Decoder row norm per speaker: sqrt(sum(coeff[speaker,ch]^2)) for each matrix row.
Mono downmix: the final decoded multichannel result converted to mono for waveform display.
Summary: order, method, layout, duration, and speaker azimuth list; LFE is labelled as LFE rather than an angle.

Row-norm interpretation: The row-norm chart is a property of the decoder matrix, not a measurement of the actual audio level sent to each speaker. For the order-only weighting used here, directional rows have the same theoretical norm at a given method/order. In 5.1/7.1 the code also computes and draws a matrix row norm for the LFE position even though the synthesis stage deliberately leaves the LFE audio silent. Therefore the LFE bar must not be read as an active LFE feed.

Limits / troubleshooting

Combined input is rejected

Combined mode accepts exactly one Sound with exactly 4, 9, or 16 channels. The order is inferred from that count.

Separate inputs are rejected

Select exactly the number required by the order, in ACN order. Every object must be mono and have the same sample rate and sample count.

Height is not reproduced

This is expected: every loudspeaker has elevation 0°. Use a decoder with elevated loudspeakers or a binaural/HRTF renderer if vertical reproduction is required.

5.1/7.1 should not be treated as a standardized optimized decode

The script uses the listed angles and the same equal sampling normalization as the regular arrays. It does not implement AllRAD, EPAD, speaker remapping, bass management, or room calibration.

Internal version text

The script header and visualization identify v0.5.1. One Info-window line still prints “Higher-Order Ambisonic Decoder v0.5”; this is a reporting-label discrepancy only and does not change the decoder math.