FoaEncoderMatrix

Extension

Omnidirectional encoder (monophonic).

Discussion:

An omnidirectional soundfield can be regarded in two ways: a soundfield with an infinite number of planewaves arriving in all directions, or a soundfield with no directions. In a well aligned, dampend studio environment, this usually sounds "in the head", while in concert hall listening usually appears as omnipresent.

To control the soundfield, FoaPush and FoaFocus can be applied to either "push" or "focus" an omnidirectional soundfield into a planewave, giving the soundfield an angle of arrival.¹

Planewave encoder (monophonic).

Arguments:

Discussion:

This is the classic Ambisonic encoding (panning) function. SuperCollider's inbuilt PanB and the Ambisonic Toolkit's FoaPanB implement this encoder as a UGen, and allow dynamically changing theta and phi.

Stereophonic encoder.

Arguments:

Discussion:

The stereophonic signal is encoded as two planewaves. When angle = 0, the left and right channels of the input signal arrive at [90, -90] degrees. angle = pi/4 distorts the arrivals to [45, -45] degrees. angle = pi/2, places both the left and right inputs at front centre, [0, 0] degrees. This behaviour matches that of the Ambisonic Toolkit's first order image warping UGens: FoaFocus, FoaZoom, FoaPush, and FoaPress.

Quadraphonic encoder.

Discussion:

The quadraphonic signal is encoded as four planewaves arriving at [ 45, 135, -135, -45 ] degrees. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.

5.0 encoder.

Discussion:

The 5.0 signal is encoded as five planewaves arriving at [ 0, 30, 110, -110, -30 ] degrees. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.

7.0 encoder.

Discussion:

The 7.0 signal is encoded as seven planewaves arriving at [ 0, 30, 90, 135, -135, -90, -30 ] degrees. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.

Pantophonic (2D) regular polygon encoder.

Arguments:

Discussion:

Inputs are in anti-clockwise order. The position of the first input channel is either centre or left of centre. -dirChannels may be used to query resulting input channel directions. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.

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

Arguments:

Discussion:

Inputs 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. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.

Virtual loudspeaker or microphone encoder, suitable for varied periphonic and pantophonic arrays.

Arguments:

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

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

Discussion:

-newDirections is the Ambisonic Toolkit's most versatile first order encoder. Arbitrary input loudspeaker and/or microphone arrays may be specified.

// Periphonic (3D) encoder, a 1/2 dome of 13 loudspeakers
// [[0, 0], [45, 0], [90, 0], [135, 0], [-180, 0], [-135, 0], [-90, 0], [-45, 0],
//  [45, 35.3], [135, 35.3], [-135, 35.3], [-45, 35.3], [0, 90]]

~directions = [[0, 0], [45, 0], [90, 0], [135, 0], [-180, 0], [-135, 0], [-90, 0],
    [-45, 0], [45, 35.3], [135, 35.3], [-135, 35.3], [-45, 35.3], [0, 90]].degrad;
~encoder = FoaEncoderMatrix.newDirections(~directions);

// inspect
~encoder.dirChannels.raddeg;

// Periphonic (2D) encoder, 3 cardioid microphones
// See: http://www.michaelgerzonphotos.org.uk/microphones-calrecs.html
// [60, -180, -60]

~directions = [60, -180, -60].degrad;
~pattern = 0.5;
~encoder = FoaEncoderMatrix.newDirections(~directions, ~pattern);

// inspect
~encoder.dirChannels.raddeg;

// Periphonic (2D) encoder, 1 omni and 2 cardioid microphones
// [0, 45, -45]

~directions = [0, 45, -45].degrad;
~pattern = [0, 0.5, 0.5];
~encoder = FoaEncoderMatrix.newDirections(~directions, ~pattern);

// inspect
~encoder.dirChannels.raddeg;

ZoomH2 (pantophonic) encoder.

Arguments:

Discussion:

 A four channel recording made by the ZoomH2 will be returned as two stereo .wav files named:

• SRxxxF.wav
• SRxxxR.wav

Presuming the ZoomH2 is oriented as described here, the following illustrates correct input for the encoder:

// ZoomH2 records two stereo .wav files:
//       SRxxxF.wav
//       SRxxxR.wav
// correct input for FoaEncoderMatrix.newZoomH2 is:

~in = [ SRxxxR.at(0), SRxxxR.at(1), SRxxxF.at(0), SRxxxF.at(1) ]

 The encoder includes a Y scalar, k, and an auditioned adjustment is usually necessary to improve the resulting image. As the ZoomH2's polar patterns are not consistent across frequency, and the capsules are not coincident, imaging is not always consistent. Touching k can go some way towards remedy-ing this.

A first order Ambisonic format exchange encoder, for use with the ZoomH2n. Encodes from AmbiX to traditional B-format. A convenience alias to *newHoa1.

Discussion:

Encoding means encoding from one Ambisonic channel componenent orderding and normalisation to that of traditional B-format. In this case, from AmbiX encoding scheme (ACN ordering, SN3D normalisation) to Gerzon (aka Furse-Malham) ordering, MaxN normalisation.

A-format to B-format encoder. Encodes to a variety of tetrahedral orientations and W channel weights.

Arguments:

Discussion:

The A-format encoder is often used in conjunction with the FoaDecoderMatrix: *newBtoA B-format decoder to form signal processing networks which preserve the spatial encoding as is described here.

On its own, *newAtoB is often used to author immersive, periphonic (3D) decorrelated soundfields.

A first order Ambisonic format exchange encoder. Encodes a variety of formats to traditional B-format.

Arguments:

Discussion:

Encoding means encoding from one Ambisonic channel componenent orderding and normalisation to that of traditional B-format. In other words, from some standard scheme to Gerzon (aka Furse-Malham) ordering with MaxN normalisation.

A first order Ambisonic format exchange encoder. Encodes from AmbiX to traditional B-format. A convenience alias to *newHoa1.

Discussion:

Encoding means encoding from one Ambisonic channel componenent orderding and normalisation to that of traditional B-format. In this case, from AmbiX encoding scheme (ACN ordering, SN3D normalisation) to Gerzon (aka Furse-Malham) ordering, MaxN normalisation.

Create an FoaEncoderMatrix by loading a matrix from a file.

Arguments:

Atk.getMatrixExtensionPath('encoders').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 encoder.

Discussion:

// encoder
~encoder = FoaEncoderMatrix.newQuad

// inspect
~encoder.kind

// encoder
~encoder = FoaEncoderMatrix.newPeri

// inspect
~encoder.kind

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

Discussion:

// encoder
~encoder = FoaEncoderMatrix.newQuad

// inspect
~encoder.dim

// encoder
~encoder = FoaEncoderMatrix.newPeri

// inspect
~encoder.dim

Answers the number of input channels (virtual loudspeakers or microphones).

Discussion:

// encoder
~encoder = FoaEncoderMatrix.newQuad

// inspect
~encoder.numChannels

// encoder (two rings of 6)
~encoder = FoaEncoderMatrix.newPeri(6)

// inspect
~encoder.numChannels

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

Returns:

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

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

// encoder
~encoder = FoaEncoderMatrix.newQuad

// inspect
~encoder.dirChannels.raddeg

// encoder (two rings of 6)
~encoder = FoaEncoderMatrix.newPeri(6)

// inspect
~encoder.dirChannels.raddeg

Answers the encoding matrix

Answers the number of outputs for the encoder. 3 for 2D and 4 for 3D.

A convenience method providing polymorphism with FoaEncoderMatrix: -dirOutputs.

Returns:

A synonym for -numChannels

A synonym for -dirChannels

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.