FoaDecoderMatrix

Extension

Virtual microphone monophonic decoder.

Arguments:

Discussion:

The virtual microphone decoder returns a single monophonic channel, and can be used to "listen in" to the soundfield at the specified azimuth and elevation.

Virtual microphone stereophonic decoder.

Arguments:

Discussion:

Standard coincident stereo microphone configurations¹ :

// Default: Cardioids at 180 deg
~decoder = FoaDecoderMatrix.newStereo

// Cardioids at 131 deg
~angle = (131/2).degrad
~pattern = 0.5
~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern)

// Super-cardioids at 115 deg
~angle = (115/2).degrad
~pattern = (3-sqrt(3))/2
~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern)

// Hyper-cardioids at 105 deg
~angle = (105/2).degrad
~pattern = 0.75
~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern)

// Blumlein
~angle = (90/2).degrad
~pattern = 1.0
~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern)

Optimised quadraphonic decoder with variable loudspeaker angle.

Arguments:

Discussion:

The outputs are in anti-clockwise order. The position of the first speaker is left of centre. -dirChannels may be used to query resulting loudspeaker directions.

Varying angle allows a number of flexible quadraphonic decoders to be generated. E.g, angle = pi/6 returns a decoder with loudspeakers at [ 30, 150, -150, 30 ] degrees.

Please see decoder%20k for further discussion on k.

Bruce Wiggins' optimised ITU 5.0 decoders.³

Arguments:

Discussion:

The outputs are in anti-clockwise order. The position of the first speaker is centre. -dirChannels may be used to query resulting loudspeaker directions.

irregKind = 'focused' returns a focused, but front weighted image. 'equal' equalises the angles across the image. 'four' is similar to 'equal', but doesn't use the centre speaker.

Pantophonic (2D) regular polygon decoder.

Arguments:

Discussion:

The outputs are in anti-clockwise order. The position of the first speaker is either centre or left of centre. -dirChannels may be used to query resulting loudspeaker directions.

Used in conjunction with FoaDecode: *ar the resulting decoder is equivalent to DecodeB2: *ar (SuperCollider's inbuilt decoder), albeit with the addition of variable k and dual-band optimised psychoacoustic decoding. DecodeB2: *ar is a "controlled opposites" decoder ( k = 'controlled' ) with a gain of 6dB greater than *newPanto.

Please see decoder%20k for further discussion on k.

Periphonic (3D) dual ring, regular cylindrical decoder.

Arguments:

Discussion:

The outputs are in anti-clockwise order, beginning with the top ring. The position of the first speaker is either centre or left of centre. -dirChannels may be used to query resulting loudspeaker directions.

Please see decoder%20k for further discussion on k.

Gerzon's classic diametric decoder, suitable for varied periphonic and pantophonic loudspeaker arrays.⁴

Arguments:

// 2D:
~directions = [ theta0, theta1, ... thetaN ];

// 3D:
~directions = [ [ theta0, phi0 ], [ theta1, phi1 ], ... [ thetaN, phiN ] ];

Discussion:

directions specifies only half of the loudspeakers for the resulting array, the remaining loudspeakers are diametrically opposite (through the origin). -dirChannels may be used to query resulting loudspeaker directions.

// Pantophonic (2D) decoder with four channels arranged in a rectangle:
// [ 30, -30, -150, 150 ]

// specify 1/2 the desired directions
~directions = [ 30, -30 ].degrad;
~decoder = FoaDecoderMatrix.newDiametric(~directions);

// inspect
~decoder.dirChannels.raddeg

// Periphonic (3D) decoder with eight channels arranged in a bi-rectangle:
// [ [ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ -90, 35.3 ],
//   [ -150, -0 ], [ 150, -0 ], [ -90, -35.3 ], [ 90, -35.3 ] ]

// specify 1/2 the desired directions
~directions = [[ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ -90, 35.3]].degrad;
~decoder = FoaDecoderMatrix.newDiametric(~directions);

// inspect
~decoder.dirChannels.raddeg

Please see decoder%20k for further discussion on k.

B-format to A-format decoder. Decodes to a variety of tetrahedral orientations and W channel weights.

Arguments:

Discussion:

 The B-format to A-format decoder is primarily intended to be used in conjuction with the A-format to B-format encoder, FoaEncoderMatrix: *newAtoB. Though the use of BtoA/AtoB decoder/encoder pairs, signal processing networks can be constructed which preserve the spatial encoding found in the original input B-format signal.

In order to reconstruct the original B-format signal, matching orientation and weight for both decoding and encoding should be chosen. For most applications the default weight ('dec') is a good choice. This weight decodes to four planewaves. Setting weight to 'uns' returns an energy optimised decoding. For Dynamic Range Control processing, 'uns' is often a good choice.

// ------------------------------------------------------------
// Single stage allpass ambience in A-format
//
// mono pink noise source
// FoaPanB encoder
//
// quad decoder


// decoder matrix
~decoder = FoaDecoderMatrix.newQuad

// b-to-a, a-to-b matrices
~b2a = FoaDecoderMatrix.newBtoA
~a2b = FoaEncoderMatrix.newAtoB

// inspect
~decoder.kind
~decoder.numChannels
~decoder.dirChannels.raddeg

(
{
    var sig;                            // audio signal
    var azim;                        // azimuth control
    var fl, bl, br, fr;                 // quad output channels
    var delaytime, decaytime;        // allpass parameters


    // display decoder
    "Ambisonic decoding via % decoder".format(~decoder.kind).postln;

    // ------------------------------------------------------------
    // parameters
    delaytime = 0.1;
    decaytime = 0.2;

    // azimuth -> hard left     = back
    //            centre        = centre
    //            hard right    = back
    azim = MouseX.kr(pi, -pi);

    // ------------------------------------------------------------
    // test sig
    sig = PinkNoise.ar * LFPulse.ar(2.0); // enveloped mono pink noise


    // ------------------------------------------------------------
    // encode to b-format
    sig = FoaPanB.ar(sig, azim);

    // ------------------------------------------------------------
    // b-to-a --> allpass --> a-to-b
    sig = FoaDecode.ar(sig, ~b2a);
    sig = AllpassN.ar(sig, delaytime, Array.fill(4, {delaytime}).rand, decaytime);
    sig = FoaEncode.ar(sig, ~a2b);


    // ------------------------------------------------------------
    // decode (to quad)
    #fl, bl, br, fr = FoaDecode.ar(sig, ~decoder);
    [fl, fr, bl, br]    // reorder output to match speaker arrangement

}.scope;
)
// ------------------------------------------------------------

A first order Ambisonic format exchange decoder. Decodes traditional B-format to a variety of formats.

Arguments:

Discussion:

Decoding means decoding from traditional B-format to another Ambisonic channel componenent orderding and normalisation. In other words, from Gerzon (aka Furse-Malham) ordering with MaxN normalisation to some other standard scheme.

A first order Ambisonic format exchange decoder. Decodes traditional B-format to AmbiX. A convenience alias to *newHoa1.

Discussion:

Decoding means decoding from traditional B-format to another Ambisonic channel componenent orderding and normalisation. In this case, from Gerzon (aka Furse-Malham) ordering, MaxN normalisation to the AmbiX encoding scheme (ACN ordering, SN3D normalisation).

Create an FoaEncoderMatrix by loading a matrix from a file.

Arguments:

Atk.getMatrixExtensionPath('decoders').fullPath

Discussion:

See the Guide to ATK Matrix Files for more information.

Create an instance from a raw 2D Matrix.

Arguments:

Matrix.with([[row1],[row2],...[rowN]])

Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.

Answers 'FOA', aka traditional B-format:

Ambisonic Order	Channel Ordering	Channel Normalisation
1st	Gerzon (aka Furse-Malham)	MaxN

Returns:

Answers 'matrix', i.e. the type of operation used to compute the resulting signals.

Answers the kind of decoder

Discussion:

// decoder
~decoder = FoaDecoderMatrix.newQuad

// inspect
~decoder.kind

// decoder
~decoder = FoaDecoderMatrix.newPeri

// inspect
~decoder.kind

Answers the number of decoder dimensions: 2D or 3D.

Discussion:

// decoder
~decoder = FoaDecoderMatrix.newQuad

// inspect
~decoder.dim

// decoder
~decoder = FoaDecoderMatrix.newPeri

// inspect
~decoder.dim

Answers the number of loudspeaker feeds (output channels).

Discussion:

// decoder (narrow quad)
~decoder = FoaDecoderMatrix.newQuad(pi/6)

// inspect
~decoder.numChannels

// decoder (two rings of 6)
~decoder = FoaDecoderMatrix.newPeri(6)

// inspect
~decoder.numChannels

Answers the direction of loudspeaker feeds, with angles in radians.

Returns:

// 2D:
[ theta0, theta1, ... thetaN ]

// 3D
[ [ theta0, phi0 ], [ theta1, phi1 ], ... [ thetaN, phiN ] ]

Discussion:

Loudspeakers should be place at the angles returned (with equal radii).

// decoder (narrow quad)
~decoder = FoaDecoderMatrix.newQuad(pi/6)

// inspect
~decoder.dirChannels.raddeg

// decoder (two rings of 6)
~decoder = FoaDecoderMatrix.newPeri(6)

// inspect
~decoder.dirChannels.raddeg

// Pantophonic (2D) decoder with four channels arranged in a rectangle:
~directions = [ 30, -30 ].degrad
~decoder = FoaDecoderMatrix.newDiametric(~directions)

// inspect
~decoder.dirChannels.raddeg

// Periphonic (3D) decoder with eight channels arranged in a bi-rectangle:
~directions = [[ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ -90, 35.3]].degrad
~decoder = FoaDecoderMatrix.newDiametric(~directions)

// inspect
~decoder.dirChannels.raddeg

Answers the decoding matrix

If the decoder is dual-band psychoacoustically optimised, get or set the shelf filter frequency, in Hz.

Discussion:

shelfFreq defaults to 400Hz, which is suitable for a well aligned domestic or studio space. shelfFreq may be set up to 700Hz, for a tight sweet-spot, and very focused single user listening.

If the decoder is dual-band psychoacoustically optimised, get or set the shelf k.

Discussion:

If set, shelfK is optimised for the chosen decoder, and should be left at the assigned value unless one is an expert user.

A synonym for -numChannels

A synonym for -dirChannels

Answers the number of inputs for the decoder. 3 for 2D and 4 for 3D.

A convenience method providing polymorphism with FoaEncoderMatrix: -dirInputs.

Returns:

A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a .yml file.

If the instance was created by loading a .yml file, this method returns the IdentityDictionary containing the parsed metadata. This can be useful if anything was stored in the metadata that can be subsequently used once reloaded, such as encoding directions, rotations, etc.

Answers the path of the file used to create the instance, or nil if not created by loading a matrix from a file.

Answers the name of the file used to create the instance, or nil if not created by loading a matrix from a file.

Write the matrix to a file

Arguments:

Discussion:

The Guide to ATK Matrix Files offers examples and more discussion regarding writing and reading matrices and metadata, including how to generate matrices for use in Reaper.