ambisonicEncoderMatrix

Generate matrix for ambisonics encoding

Since R2025a

Syntax

enc = ambisonicEncoderMatrix(order,elements)

enc = ambisonicEncoderMatrix(order,elements,Name=Value)

Description

enc = ambisonicEncoderMatrix(order,elements) returns the ambisonic encoder matrix for the specified order and elements. Use ambisonics to encode spatial audio as a 3-D sound field with spherical harmonics. You can decode the encoded audio to a desired loudspeaker layout using ambisonicDecoderMatrix.

enc = ambisonicEncoderMatrix(order,elements,Name=Value) specifies options using one or more name-value arguments.

Examples

Perform Ambisonics Encoding

Create a random signal representing five sound sources.

x = randn(1e4,5);

Define the spatial location of the sound elements in degrees, using azimuth and elevation.

elements = [0 0; 0 45; 45 0; 45 45; 45 0];

Create an ambisonic encoder matrix of the first order.

enc = ambisonicEncoderMatrix(1,elements);

Encode the audio.

y = x*enc;

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, specified as an integer in the range [0,7]. A higher ambisonics order more accurately represents the 3-D sound field with more spherical harmonics. The encoded signal contains (1+order)^2 channels.

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

elements — Spatial location of sound elements

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

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

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

Data Types: double | single | 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: enc = ambisonicsEncoderMatrix(1,elements,ChannelOrder="fuma")

Normalization — Normalization method

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

Normalization method used for the spherical harmonics, specified as "sn3d", "n3d", "3d", "maxn", or "fuma".

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

• "n3d" — Use the fully-normalized (N3D) method.

• "3d" — Use the 3-D normalization method specified in [2].

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

• "fuma" — Use the 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 for the ambisonic encoding, specified as "acn" or "fuma". Set this argument to "acn" to use the Ambisonic Channel Number (ACN) format. Set this argument to "fuma" to use the Furse-Malham (FuMa) higher-order format. For more information about ambisonics channel ordering, see Channel Ordering.

Data Types: char | string

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

enc — Encoder matrix

matrix

Ambisonic encoder matrix, returned as an N-by-M matrix, where N is the number of elements specified by elements, and M is equal to (1+order)^2. Multiply a spatial audio signal by this matrix to generate the ambisonics encoding.

Algorithms

Ambisonics

Ambisonics provide a full-sphere surround sound format that can be decoded to arbitrary loudspeaker layouts. The encoded channels do not correspond to specific loudspeakers, but instead they use the spherical harmonics series of functions to encode the entire 3-D sound field. A 3-D sound field can be perfectly represented by an infinite series of spherical harmonics.

The ambisonicEncoderMatrix function uses the first N orders of spherical harmonics to approximate the sound field, where N is specified by order. This results in (N + 1)² encoded ambisonics channels.

Channel Ordering

The ordering of the encoded ambisonics channels with respect to the spherical harmonics can vary. The two main channel ordering conventions are ACN and FuMa. In ACN, the channel corresponding to the spherical harmonic Y^m_ℓ corresponds to the index 1 + ℓ² + ℓ + m. In FuMa, the first four channels correspond to the classic B-format for first order ambisonics. Then for each higher order the channels start with the spherical harmonic that is rotationally symmetric about the z-axis (m=0) and move outward alternating between right (m+1) and left (m-1). See the following table depicting the indices for the ACN and FuMa channels up to the third order.

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.

Version History

Introduced in R2025a