ambisonicDecoderMatrix

Generate matrix for ambisonics decoding

Since R2025a

Syntax

dec = ambisonicDecoderMatrix(order,speakers)

dec = ambisonicDecoderMatrix(order,speakers,Name=Value)

Description

dec = ambisonicDecoderMatrix(order,speakers) returns an ambisonics decoder matrix for the specified order and loudspeaker layout. An ambisonics-encoded signal represents spatial audio as a 3-D sound field using spherical harmonics.

dec = ambisonicDecoderMatrix(order,speakers,Name=Value) specifies options using one or more name-value arguments.

Examples

Perform Ambisonics Decoding

Encode five random sound sources using first-order ambisonics.

x = randn(1e4,5);
elements = [0 0; 0 45; 45 0; 45 45; 45 0];
enc = ambisonicEncoderMatrix(1,elements);
y = x*enc;

Create an ambisonic decoding matrix of the first order. Decode the audio to a uniform tetrahedron loudspeaker layout.

u = [1    1    1
     1   -1   -1
    -1    1   -1
    -1   -1    1];
[az,el] = cart2sph(u(:,1),u(:,2),u(:,3));
az = rad2deg(az);
el = rad2deg(el);

speakers = [az el];
dec = ambisonicDecoderMatrix(1,speakers);

Use the decoder matrix to decode the ambisonics signal.

z = y*dec;

Specify Channel Order and Normalization for Ambisonics

Create a random signal representing five sound sources and define the locations of the sound elements.

x = randn(1e4,5);
elements = [0 0; 0 45; 45 0; 45 45; 45 0];

Encode the signal using second-order ambisonics. Specify the Normalization and ChannelOrder arguments to use N3D normalization and the FuMa channel ordering convention.

order = 2;
normMethod = "n3d";
chnlOrder = "fuma";
enc = ambisonicEncoderMatrix(order,elements, ...
    Normalization=normMethod,ChannelOrder=chnlOrder);
y = x*enc;

Decode the encoded signal to a uniform tetrahedron loudspeaker layout. Use the same order, normalization method, and channel convention used to encode the signal.

u = [1    1    1
     1   -1   -1
    -1    1   -1
    -1   -1    1];
[az,el] = cart2sph(u(:,1),u(:,2),u(:,3));
az = rad2deg(az);
el = rad2deg(el);

speakers = [az el];
dec = ambisonicDecoderMatrix(order,speakers, ...
     Normalization=normMethod,ChannelOrder=chnlOrder);
z = y*dec;

Select Subsets of Elements and Loudspeakers for Ambisonics

When using ambisonicEncoderMatrix and ambisonicDecoderMatrix to encode and decode ambisonics signals, you can specify which sound sources should be active in the resulting signal.

Create a random signal representing five sound sources and define the locations of the sound elements.

x = randn(1e4,5);
elements = [0 0; 0 45; 45 0; 45 45; 45 0];

Add a third column to elements that turns off the third sound element.

elements = [elements, [1 1 0 1 1].'];

Encode the signal using first-order ambisonics. You can inspect the encoder matrix to see that the third row contains only zeros, which shows that the third element does not contribute to the encoded signal.

enc = ambisonicEncoderMatrix(1,elements);
y = x*enc;

Define a uniform tetrahedron loudspeaker layout for decoding the ambisonic signal. Add a third column to speakers that turns off the first loudspeaker.

u = [1    1    1
     1   -1   -1
    -1    1   -1
    -1   -1    1];
[az,el] = cart2sph(u(:,1),u(:,2),u(:,3));
az = rad2deg(az);
el = rad2deg(el);

speakers = [az el];
speakers = [speakers, [0 1 1 1].'];

Decode the ambisonic signal. You can see the decoded channel corresponding to the first loudspeaker contains only zeros because it was turned off.

dec = ambisonicDecoderMatrix(1,speakers);
z = y*dec;

Input Arguments

order — Ambisonics order

integer in range [0,7]

The ambisonics order of the encoded signal, specified as an integer in the range [0,7].

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

speakers — Spatial location of each speaker

N-by-2 matrix | N-by-3 matrix

The spatial location of each speaker in degrees, specified as an N-by-2 matrix where N is the number of elements, the first column corresponds to the azimuth, and the second column corresponds to the elevation. The azimuth values are in the range [0,360], and the elevation values are in the range [-90,90].

The matrix can optionally have a third column which holds a logical value for each speaker specifying whether the speaker is on or off.

Data Types: single | double | logical

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: dec = ambisonicsDecoderMatrix(1,speakers,ChannelOrder="fuma")

Normalization — Normalization method

"sn3d" (default) | "n3d" | "3d" | "maxn" | "fuma"

Normalization method used for the encoded ambisonics signal, specified as "sn3d", "n3d", "3d", "maxn", or "fuma".

• "sn3d" — Schmidt semi-normalized 3-D (SN3D) method.

• "n3d" — Fully-normalized (N3D) method.

• "3d" — The 3-D normalization specified in [2].

• "maxn" — Max-normalization (MaxN) method.

• "fuma" — Furse-Malham (FuMa) method.

For more information about these normalization methods for ambisonics, see [1].

Data Types: char | string

ChannelOrder — Channel order convention

"acn" (default) | "fuma"

Channel ordering convention used for the ambisonic encoding, specified as "acn" or "fuma". Set this argument to "acn" to decode from the Ambisonic Channel Number (ACN) format. Set this argument to "fuma" to decode from the Furse-Malham higher-order format.

Data Types: char | string

Decoder — Decoder type

"sad" (default) | "mmd" | "epad" | "allrad"

Decoder type, specified as "sad", "mmd", "epad", or "allrad".

• "sad" — Use the sampling ambisonic decoder (SAD).

• "mmd" — Use the mode matching decoder (MAD).

• "epad" — Use the energy-preserving ambisonic decoder (EPAD).

• "allrad" — Use the all-round ambisonic decoder (AllRAD).

For more information about these ambisonics decoders, see chapter 4, section 9 of [4]. For an example that demonstrates performance analysis on decoders, see Analyze Ambisonic Decoders.

Data Types: char | string

ApplyMaxREWeighting — Apply max-RE weighting

false (default) | true

Apply max-RE weighting, specified as true or false. For more information about max-RE weighting for ambisonics decoding, see [3].

Data Types: logical

OutputDataType — Output data type

"double" (default) | "single"

Output data type, specified as "double" or "single". Set this argument to "single" to force all matrix computations to be performed in single precision.

Data Types: char | string

Output Arguments

dec — Decoder matrix

matrix

Ambisonic decoder matrix, returned as an M-by-N matrix, where M is equal to (1+order)^2, and N is the number of speakers specified by speakers. Multiply an ambisonics-encoded signal by this matrix to decode the audio.

References

[1] Carpentier, Thibaut. "Normalization Schemes in Ambisonic: Does It Matter?" In 142nd Convention of the Audio Engineering Society, May 2017, Berlin, Germany.

[2] Politis, Archontis. Compact Higher-Order Ambisonic Library. Department of Signal Processing and Acoustics, Aalto University, 2015.

[3] Zotter, Franz, and Matthias Frank. "All-round Ambisonic Panning and Decoding." Journal of the Audio Engineering Society 60, no. 10 (October 2012): 807-820.

[4] Zotter, Franz. Ambisonics: A Practical 3D Audio Theory for Recording, Studio Production, Sound Reinforcement, and Virtual Reality. 1st ed. Springer Topics in Signal Processing Series, v. 19. Cham: Springer International Publishing AG, 2019.

Version History

Introduced in R2025a