Decode 2nd and 3rd Order Ambisonics in FFmpeg

This guide explains how to decode 2nd-order (9-channel) and 3rd-order (16-channel) Higher-Order Ambisonics (HOA) audio files into standard speaker formats or binaural headphone audio using FFmpeg. You will learn how to verify Ambisonic channel counts, remap non-standard channel ordering into standard ACN/SN3D configurations using the pan filter, and decode the resulting stream using matrix coefficients or the sofalizer filter.

1. Understand Channel Counts and Standards

Higher-Order Ambisonics requires a specific number of channels determined by the formula \((N + 1)^2\), where \(N\) represents the Ambisonic order:

  • 2nd-Order Ambisonics: \((2 + 1)^2 = 9\text{ channels}\) (ACN 0 through 8)
  • 3rd-Order Ambisonics: \((3 + 1)^2 = 16\text{ channels}\) (ACN 0 through 15)

Most modern spatial audio pipelines expect AmbiX format, which combines ACN (Ambisonic Channel Number) ordering and SN3D normalization. If your input source uses a proprietary, interleaved, or non-standard order, you must first remap it to ACN before decoding.

2. Remapping Custom Channels to Standard ACN

If your input channels are in an unusual sequence, use FFmpeg's pan filter to reroute the audio channels into proper ACN order.

Remapping 2nd-Order (9 Channels)

Suppose an incoming 9-channel file has its height channels placed out of order. You can define an explicit 9-channel output map:

ffmpeg -i input_custom_2nd_order.wav -filter_complex \
"pan=9c|c0=c0|c1=c2|c2=c1|c3=c3|c4=c4|c5=c5|c6=c6|c7=c7|c8=c8" \
-c:a pcm_s24le standardized_2nd_order.wav

Remapping 3rd-Order (16 Channels)

To standardize a 16-channel layout:

ffmpeg -i input_custom_3rd_order.wav -filter_complex \
"pan=16c|c0=c0|c1=c1|c2=c2|c3=c3|c4=c4|c5=c5|c6=c6|c7=c7|c8=c8|c9=c9|c10=c10|c11=c11|c12=c12|c13=c13|c14=c14|c15=c15" \
-c:a pcm_s24le standardized_3rd_order.wav

(Swap the source channel numbers on the right-hand side of each equal sign to match your specific layout).

3. Decoding to Binaural (Headphones) via SOFA

The most accurate method for decoding 2nd- or 3rd-order Ambisonics directly to headphones is using the sofalizer filter with a Spatially Oriented Format for Acoustics (SOFA) file that contains measured impulse responses corresponding to your HOA order.

2nd-Order to Binaural

ffmpeg -i standardized_2nd_order.wav -af \
"sofalizer=sofa=/path/to/impulse_response_order2.sofa:type=freq:gain=0" \
-c:a pcm_s24le binaural_output.wav

3rd-Order to Binaural

ffmpeg -i standardized_3rd_order.wav -af \
"sofalizer=sofa=/path/to/impulse_response_order3.sofa:type=freq:gain=0" \
-c:a pcm_s24le binaural_output.wav

4. Decoding to Discrete Speakers (5.1 or 7.1)

To decode Ambisonic signals to traditional speaker systems, you must apply a decoding matrix. The pan filter handles this by applying gain coefficients to mix Ambisonic channels into specific speaker destinations.

Example: Decoding 2nd-Order to 5.1 Surround

In this matrix example, incoming ACN channels (\(c0\) to \(c8\)) are weighted to create Left, Right, Center, LFE, Left Surround, and Right Surround outputs:

ffmpeg -i standardized_2nd_order.wav -filter_complex \
"pan=5.1| \
FL = 0.35*c0 + 0.35*c1 + 0.25*c3 + 0.15*c6 + 0.15*c8 | \
FR = 0.35*c0 - 0.35*c1 + 0.25*c3 + 0.15*c6 - 0.15*c8 | \
FC = 0.50*c0 + 0.50*c3 + 0.25*c6 | \
LFE = 0.0 | \
BL = 0.35*c0 + 0.35*c1 - 0.25*c3 - 0.15*c6 + 0.15*c8 | \
BR = 0.35*c0 - 0.35*c1 - 0.25*c3 - 0.15*c6 - 0.15*c8" \
-c:a pcm_s24le decoded_5.1.wav

5. Combining Remapping and Decoding in One Command

You do not need to generate intermediate files. Chain the custom remapping and the decoding step together in a single -filter_complex call:

ffmpeg -i input_custom_raw_16ch.wav -filter_complex \
"[0:a]pan=16c|c0=c0|c1=c3|c2=c1|c3=c2|c4=c4|c5=c5|c6=c6|c7=c7|c8=c8|c9=c9|c10=c10|c11=c11|c12=c12|c13=c13|c14=c14|c15=c15[acn]; \
 [acn]sofalizer=sofa=/path/to/impulse_response_order3.sofa:type=freq[out]" \
-map "[out]" -c:a pcm_s24le final_binaural.wav

This command takes your non-standard 16-channel input, realigns channels 1, 2, and 3 into standard ACN sequence, and renders the 3rd-order soundfield straight to binaural stereo.