FoaEncoderMatrix | SuperCollider 3.13.0 Help

Description

Generates encoding matrices required by the Ambisonic Toolkit's first order encoder, FoaEncode.

NOTE: The ATK matrices are required for using some of the matrix encoders. Please see Atk: Installation of ATK dependencies for instructions.

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.¹

.newDirection

Planewave encoder (monophonic).

Arguments:

theta	Azimuth angle, in radians: pi to -pi
phi	Elevation angle, in radians: pi/2 to -pi/2

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 provide dynamically changing theta and phi at the audio and control rates.

.newStereo

Stereophonic encoder.

Arguments:

angle

Soundfield distortion angle, in radians: pi/2 to -pi/2

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.

NOTE: The authors also suggest reviewing the Super Stereo² encoding technique, the classic method for encoding stereophonic signals into B-format: FoaEncoderKernel: *newSuper

.newQuad

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.

.new5_0

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.

.new7_0

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.

.newPanto

Pantophonic (2D) regular polygon encoder.

Arguments:

numChans	number of input channel feeds
orientation	`'flat'` or `'point'`

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.

.newPeri

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

Arguments:

numChanPairs	Number of channel pairs. (Half the total number of input channel feeds.)
elevation	Elevation of the upper ring, measured from the origin. In radians.
orientation	`'flat'` or `'point'`

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.

.newDirections

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

Arguments:

directions

An array of directions of the virtual loudspeakers or microphones. Specify in radians.

Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,// 2D: ~directions = [ theta0, theta1, ... thetaN ];

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

pattern

Virtual microphone pattern, nil, or 0 to 1.

nil

directions specifies virtual loudspeaker positions

0 to 1

directions specifies a microphone array with patterns:

pattern	microphone
0.0	Omni
0.5	Cardioid
(3-sqrt(3))/2	Super-cardioid
0.75	Hyper-cardioid
1.0	Bi-directional

If pattern is an Array, individual microphone patterns are specified.

For equivalences to decoder k, please see FoaDecoderMatrix: decoder k.

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;

.newZoomH2

ZoomH2 (pantophonic) encoder.

Arguments:

angles

Angles for front left and back left microphones, in radians. (The corresponding right microphones are mirrored across the y-axis.) Defaults to [pi/3, 3/4*pi] .

NOTE: The encoder reverses the labels for front and back of the ZoomH2. This is done so that directions are are preserved from the point of view of a field recording operator. With the ZoomH2's display facing the operator (for ease of monitoring), sounds arriving in front of the operator will be encoded in the front of the soundfield. See also Discussion below.

pattern

Microphone pattern³ , 0 to 1:

pattern	virtual microphone
0.0	Omni
0.5	Cardioid
(3-sqrt(3))/2	Super-cardioid
0.75	Hyper-cardioid
1.0	Bi-directional

Post-encoding Y scalar.

NOTE: Please see further discussion of k here

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[0], SRxxxR[1], SRxxxF[0], SRxxxF[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.

NOTE: k = 1.7378 is a value that has been found suitable for matching Courville's ZoomH2 ⁴ and Soundfield recordings.⁵

.newZoomH2n

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.

NOTE: Requires a device firmware update to H2n System Version 2.00 or higher. Set the ZoomH2n to record in the SPATIAL AUDIO mode. Further details may be reviewed in the manual addendum found here. You may also like to review the H2n: Spatial Audio Setup video.⁶

.newAtoB

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

Arguments:

orientation

Orientation of the A-format tetrahedron.

orientation	angles ([theta, phi] in degrees)
`'flu'`	`[[45.0, 35.3], [-45.0, -35.3], [135.0, -35.3], [-135.0, 35.3]]`
`'fld'`	`[[45.0, -35.3], [-45.0 , 35.3], [135.0, 35.3], [-135.0, -35.3]]`
`'flr'`	`[[54.7, 0.0], [-54.7, 0.0], [180.0, 54.7], [ 180.0, -54.7]]`
`'fud'`	`[[ 0.0, 54.7], [ 0.0, -54.7], [125.7, 0.0], [-125.7, 0.0]]`
`'fbd'`	`[[ 0.0, 0.0], [180.0, -70.5], [112.2, 28.1], [-112.2, 28.1]]`
`'fbu'`	`[[ 0.0, 0.0], [180.0, 70.5], [112.2, -28.1], [-112.2, -28.1]]`
`'flru'`	`[[67.8, 28.1], [-67.8, 28.1], [ 0.0, -70.5], [ 180.0, 0.0]]`
`'flrd'`	`[[67.8, -28.1], [-67.8, -28.1], [ 0.0, 70.5], [ 180.0, 0.0]]`

weight

The W weight factor.

For convenience, equivalent virtual microphone pattern and decoding k are also listed.

weight	kind	W scale	virtual microphone	pattern	decoding	k
`'dec'`	Decorrelated (on the sphere)	1/sqrt(3)	Hyper-cardioid	0.75	strict soundfield	`'velocity'`
`'can'`	Canonical (B-format)	1/sqrt(2)		sqrt(6)/(1+sqrt(6))		sqrt(2/3)
`'uns'`	Unscaled	1	Super-cardioid	(3-sqrt(3))/2	energy optimised	`'energy'`
`'car'`	Cardioid	sqrt(3)	Cardioid	0.5	controlled opposites	`'controlled'`

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.

.newHoa1

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

Arguments:

ordering

Input Ambisonic channel component ordering.

ordering	kind
`'acn'`	Ambisonic Channel Number (ACN)
`'sid'`	Single Index Designation (SID)

normalisation

Spherical harmonic normalisation method.

normalisation	kind
`'n3d'`	Orthonormal basis for 3D decomposition (N3D)
`'sn3d'`	Semi-normalised basis for 3D decomposition (SN3D)

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.

NOTE: Hoa1 in the method name *newHoa1 refers to Higher Order Ambisonic (HOA) encoding format, Ambisonic order = 1. The input signal should have four channels, with the given encoding format as specified in the arguments.

.newAmbix1

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

Discussion:

Matrix & File

.newFromFile

Create an FoaEncoderMatrix by loading a matrix from a file.

Arguments:

filePathOrName

Can be a path relative to your /extensions/matrices/FOA/encoders folder:Atk.getMatrixExtensionSubPath(\FOA, \encoders).fullPath

Otherwise a full path to your matrix file.

Discussion:

See the Guide-to-ATK-Matrix-Files for more information.

Instance Methods

Information

.type

Returns:

'encoder'

.kind

Answers the kind of encoder.

Discussion:

.dim

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

Discussion:

.numChannels

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

Discussion:

.dirChannels

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

Returns:

A rank 1 array for pantophonic, and rank 2 array for periphonic. E.g.,// 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

.numInputs

A synonym for -numChannels

.dirInputs

A synonym for -dirChannels

.numOutputs

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

.dirOutputs

A convenience method providing polymorphism with FoaDecoderMatrix: -dirOutputs.

Returns:

for 2D: [ inf, inf, inf ]
for 3D: [ inf, inf, inf , inf ]

Matrix

File handling

Examples

Encoding-FOA

[1] - In combination with distance scaling, *newOmni and FoaPush can be used to implement Menzies' "W-panning" technique. See: D. Menzies, "W-panning and O-format, tools for object spatialization," in Proceedings of the Audio Engineering Society 22nd International Conference on Virtual, Synthetic and Entertainment Audio, Espoo, Finland, 2002.

[2] - See https://en.wikipedia.org/wiki/Ambisonic_UHJ_format#Super_stereo for further information.

[3] - The default value, 0.5857, is derived from measurements made by Farina, and is a hyper-cardioid response with a zero at 135 degrees. See: http://pcfarina.eng.unipr.it/Public/Brahma/Zoom-H2/Polar-ZoomH2.xls

[4] - Courville orients his ZoomH2 so that the labelled front of the device faces the front of the sound scene. This is front/back reversed as regards -newZoomH2. If you choose to encode Courville's example files, you'll need to follow with FoaMirrorX.

[5] - See: http://www.radio.uqam.ca/ambisonic/comparative_recording.html

[6] - These last two links are best opened in a browser window:

helpfile source: HelpSource/Classes/FoaEncoderMatrix.schelp
link::atk-sc3/Classes/FoaEncoderMatrix::

FoaEncoderMatrixExtension

.newOmni

Discussion:

.newDirection

Arguments:

Discussion:

.newStereo

Arguments:

Discussion:

.newQuad

Discussion:

.new5_0

Discussion:

.new7_0

Discussion:

.newPanto

Arguments:

Discussion:

.newPeri

Arguments:

Discussion:

.newDirections

Arguments:

Discussion:

.newZoomH2

Arguments:

Discussion:

.newZoomH2n

Discussion:

.newAtoB

Arguments:

Discussion:

.newHoa1

Arguments:

Discussion:

.newAmbix1

Discussion:

.newFromFile

Arguments:

Discussion:

.type

Returns:

.kind

Discussion:

.dim

Discussion:

.numChannels

Discussion:

.dirChannels

Returns:

.numInputs

.dirInputs

.numOutputs

.dirOutputs

Returns:

FoaEncoderMatrix
Extension