Generates decoding matrices required by the Ambisonic Toolkit's first order decoder, FoaDecode.
Virtual microphone monophonic decoder.
theta 
Azimuth angle, in radians: pi to pi.neg.  
phi 
Elevation angle, in radians: pi/2 to pi.neg/2.  
pattern 
Virtual microphone pattern, 0 to 1:
For equivalences to decoder k, please see Decoder k. 
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.
angle 
The half angle of the stereo pair, in radians: 0 to pi., Default: pi/2  
pattern 
Virtual microphone pattern, 0 to 1:
For equivalences to decoder k, please see Decoder k. 
Standard coincident stereo microphone configurations^{1} :
Optimised quadraphonic decoder with variable loudspeaker angle.
angle 
The half angle of the front (and rear) loudspeaker pair. Defaults to pi/4, a square. In radians. 
k 
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

The outputs are in anticlockwise 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 k for further discussion on k.
Bruce Wiggins' optimised ITU 5.0 decoders.^{3}
irregKind 
Three kinds are available:

The outputs are in anticlockwise 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.
numChans 
number of loudspeaker feeds 
orientation 

k 
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

The outputs are in anticlockwise 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 dualband optimised psychoacoustic decoding. DecodeB2: *ar is a "controlled opposites" decoder ( k = 'controlled'
) with a gain of 6dB greater than *newPanto.
Please see Decoder k for further discussion on k.
Periphonic (3D) dual ring, regular cylindrical decoder.
numChanPairs 
Number of channel pairs. (Half the total number of loudspeaker feeds.) 
elevation 
Elevation of the upper ring, measured from the origin. In radians. 
orientation 

k 
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

The outputs are in anticlockwise 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 k for further discussion on k.
Gerzon's classic diametric decoder, suitable for varied periphonic and pantophonic loudspeaker arrays.^{4}
directions 
An array of directions for half of the loudspeaker feeds for the desired decoder. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,

k 
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

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.
Please see Decoder k for further discussion on k.
Bformat to Aformat decoder. Decodes to a variety of tetrahedral orientations and W channel weights.
orientation 
Orientation of the Aformat tetrahedron.
 
weight 
The W weight factor. For convenience, equivalent virtual microphone pattern and decoding k are also listed.

The Bformat to Aformat decoder is primarily intended to be used in conjuction with the Aformat to Bformat 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 Bformat signal.
In order to reconstruct the original Bformat 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.
A first order Ambisonic format exchange decoder. Decodes traditional Bformat to a variety of formats.
ordering 
Input Ambisonic channel component ordering.
 
normalisation 
Spherical harmonic normalisation method.

Decoding means decoding from traditional Bformat to another Ambisonic channel componenent orderding and normalisation. In other words, from Gerzon (aka FurseMalham) ordering with MaxN normalisation to some other standard scheme.
Hoa1
in the method name *newHoa1 refers to Higher Order Ambisonic (HOA) encoding format, Ambisonic order = 1.A first order Ambisonic format exchange decoder. Decodes traditional Bformat to AmbiX. A convenience alias to *newHoa1.
Decoding means decoding from traditional Bformat to another Ambisonic channel componenent orderding and normalisation. In this case, from Gerzon (aka FurseMalham) ordering, MaxN normalisation to the AmbiX encoding scheme (ACN ordering, SN3D normalisation).
Create an instance from a raw 2D Matrix.
matrix 
A Matrix in the form of 
directions 
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,

Create an FoaDecoderMatrix by loading a matrix from a file.
filePathOrName 
Can be a path relative to your Otherwise a full path to your matrix file. 
See the Guide to ATK Matrix Files for more information.
The default k ( 'single'
), for decoders accepting k as an argument, returns an 'energy'
optimised (aka "maximum energy" or "max rE") decoder. 'dual'
returns a dualband psychoacoustically optimised decoder.^{5} The 'dual'
decoder is the optimum choice for small scale studio or domestic settings. 'single'
is suitable for larger, midscale environments. 'velocity'
returns "strict soundfield" (aka "planewave" or "basic") decoding.^{6} 'controlled'
returns "controlled opposites" decoding (aka "minimum energy" or "in phase"), which is often preferred in largescale, concert environments.^{7} (SuperCollider's inbuilt decoder, DecodeB2: *ar, is a "controlled opposites" decoder. See this discussion.)
Given a uniform periphonic (3D) distribution of loudspeakers, e.g. a Platonic solid, some useful virtual microphone equivalences:
keyword  decoding  virtual microphone  pattern 
'velocity'  strict soundfield  Hypercardioid  0.75 
'energy'  energy optimised  Supercardioid  (3sqrt(3))/2 
'controlled'  controlled opposites  Cardioid  0.5 
The k keywords translate to numerical values as follows:
keyword  k for pantophonic (2D)  k for periphonic (3D) 
'velocity'  1  1 
'energy'  1/sqrt(2)  1/sqrt(3) 
'controlled'  1/2  1/3 
'energy'
and 'controlled'
.A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a .yml
file.
Ambisonic order.
Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.
Ambisonic Toolkit designation indicating Ambisonic order and encoding format. E.g., \FOA
, \HOA3
.
Answers, \FOA
, aka traditional Bformat:
Ambisonic Order  Component Ordering  Component Normalisation 
1st  FurseMalham (FuMa)  Gerzon / FurseMalham (MaxN) 
'decoder'
Answers 'matrix'
, i.e. the type of operation used to compute the resulting signals.
Answers the kind of decoder
Answers the number of decoder dimensions: 2D or 3D.
Answers the number of loudspeaker feeds (output channels).
Answers the direction of loudspeaker feeds, with angles in radians.
A rank 1 array for pantophonic, and rank 2 array for periphonic. E.g.,
Loudspeakers should be place at the angles returned (with equal radii).
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.
[ inf, inf, inf ]
[ inf, inf, inf, inf ]
A synonym for numChannels
A synonym for dirChannels
Returns the raw coefficient Matrix.
Returns the matrix as a new Array of rows.
If the decoder is dualband psychoacoustically optimised, get or set the shelf filter frequency, in Hz.
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 sweetspot, and very focused single user listening.
If the decoder is dualband psychoacoustically optimised, get or set the shelf k.
If set, shelfK is optimised for the chosen decoder, and should be left at the assigned value unless one is an expert user.
Answers the name of the file used to create the instance, or nil
if not created by loading a matrix from a file.
Answers the path of the file used to create the instance, or nil
if not created by loading a matrix from a 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.
Write the matrix to a file
fileNameOrPath 
A String of the file name. The file extension determines the format:
You may provide a full path if you would like to save the file somewhere other than the default location in the Atk 
note 
A String that is a short description or bit of info about the matrix to store for future reference. 
attributeDictionary 
A Dictionary containing any information that's useful to store in key:value pairs. Keys that match getters in the AtkMatrix will take precedence over the defaults. See the Discussion for more details. 
overwrite 
A boolean specifying whether you'd like to force overwriting an existing file of the same name and extension. 
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.