Decoding FOA | SuperCollider 3.13.0 Help

Monitoring

Perhaps one of the most celebrated aspects of the Ambisonic sound technique has been its design as a hierarchal reproduction system, able to target a number of varying loudspeaker arrays. Users may be familiar with SuperCollider's inbuilt regular polygon decoder, DecodeB2.

The ATK provides a much wider palate of optimised monitoring tools via FoaDecode. These include:

stereo UHJ: classic Ambisonic stereo decoding
binaural: measured and synthetic HRTFs
regular 2D & 3D: single and dual polygons
diametric 2D & 3D: flexible semi-regular arrays
5.0: Wiggins optimised decoders

While the regular decoders will be suitable for many users, diametric decoding enables the greatest flexibility, and allows the user to design substantially varying semi-regular arrays suitable for a wide variety of playback situations.

The examples below are intended to briefly illustrate some of the first order decoding options made available in the Ambisonic Toolkit.

NOTE: All decoders presume loudspeakers are placed at equal radii from the origin of the array, and gain is normalised. Loudspeaker arrays with unequal radii may be realised if the resulting wavefront arrival times are compensated through the use of delay lines.

NOTE: See FoaDecode, FoaDecoderMatrix and FoaDecoderKernel for more details about decoding.

Testing notes

Encoded as an omnidirectional soundfield, PinkNoise is used as the example sound source. In a well aligned, dampend studio environment, this usually sounds "in the head". FoaPush is used to "push" the omnidirectional soundfield so that it becomes a planewave (infinite distance, in an anechoic environment) arriving from some direction.

The soundfield is controlled by MouseX and MouseY, where MouseX specifies the incident azimuth angle (pi to -pi; left to right of display) and MouseY the FoaPush angle (0 to pi/2; bottom to top of display). With the mouse at the bottom of the display, the soundfield remains omnidirectional. Placed at the top of the display, the soundfield becomes directional, and varying left/right position will vary the incident azimuth of the resulting planewave.

Before exploring the examples below, it is suggested you confirm your Server has enough output channels to support your chosen decoder. You can query the server:myServer.options.numOutputBusChannels

An example Function, ~checkMyServerOutputs, can be found here. ~checkMyServerOutputs throws a warning if myServer.options.numOutputBusChannels < myDecoder.numOutputs. If you need to update your Server's number of output bus channels, review the example found here.

Stereo

Virtual microphone

The soundfield may be decoded to stereo using a pair of virtual microphones.

NOTE: A matrix type decoder, see FoaDecoderMatrix: *newStereo for further details.

// ------------------------------------------------------------
// virtual microphone stereo decoder
//
// mono pink noise source
// omni encoder

// define encoder / decoder matrices
~encoder = FoaEncoderMatrix.newOmni
~decoder = FoaDecoderMatrix.newStereo

// inspect
~encoder.kind
~encoder.numChannels
~encoder.dirChannels

~decoder.kind
~decoder.numChannels
~decoder.dirChannels.raddeg

(
{
    var sig;// audio signal
    var angle, azim;            // angle and azimuth control

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

// angle ---> top     = push to plane wave
    //            bottom  = omni-directional
    angle = MouseY.kr(pi/2, 0);

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

// ------------------------------------------------------------
    // test sig
    sig = PinkNoise.ar;             // mono pink noise

// ------------------------------------------------------------
    // encode
    sig = FoaEncode.ar(sig, ~encoder);

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, 'push', angle, azim);

// ------------------------------------------------------------
    // decode (to stereo)
    FoaDecode.ar(sig, ~decoder);

}.scope;
)

// ------------------------------------------------------------

Ambisonic UHJ

Ambisonic UHJ stereo¹ is the native stereo format for Ambisonics. A B-format signal (2D, with some losses) can be recovered from a UHJ decoded signal through the use of FoaEncoderKernel: *newUHJ.

NOTE: A kernel type decoder, see FoaDecoderKernel: *newUHJ for further details.

WARNING: Kernel decoders require special care. Allow the kernel time to load before attempting to use. Additionally, the kernel buffer should be freed through the use of FoaDecoderKernel: -free after use.

// ------------------------------------------------------------
// UHJ (stereo) decoder
//
// mono pink noise source
// omni encoder

// define encoder / decoder matrices
~encoder = FoaEncoderMatrix.newOmni
~decoder = FoaDecoderKernel.newUHJ    // kernel decoders should be freed after use!!
                                    // free below...

// inspect
~encoder.kind
~encoder.numChannels
~encoder.dirChannels

~decoder.kind
~decoder.numChannels
~decoder.dirChannels.raddeg

(
{
    var sig;// audio signal
    var angle, azim;            // angle and azimuth control

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

// angle ---> top         = push to plane wave
    //            bottom        = omni-directional
    angle = MouseY.kr(pi/2, 0);

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

// ------------------------------------------------------------
    // test sig
    sig = PinkNoise.ar;             // mono pink noise

// ------------------------------------------------------------
    // encode
    sig = FoaEncode.ar(sig, ~encoder);

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, 'push', angle, azim);

// ------------------------------------------------------------
    // decode (to stereo)
    FoaDecode.ar(sig, ~decoder);

}.scope;
)

// free kernel
~decoder.free

// ------------------------------------------------------------

Binaural

Synthetic

The Ambisonic Tookit provides a synthetic spherical head model HRTF decoder.² Ten subjects with varying head sizes are available. Audition to find one that works best for you.

Additionally, HRTF decoders computed from measured HRIRs are also available: FoaDecoderKernel: *newListen & FoaDecoderKernel: *newCIPIC.

NOTE: A kernel type decoder, see FoaDecoderKernel: *newSpherical for further details.

// ------------------------------------------------------------
// Binaural (synthetic) decoder
//
// mono pink noise source
// omni encoder

// define encoder / decoder matrices
~encoder = FoaEncoderMatrix.newOmni
~decoder = FoaDecoderKernel.newSpherical // kernel decoders should be freed after use!!
                                         // free below...

// inspect
~encoder.kind
~encoder.numChannels
~encoder.dirChannels

~decoder.kind
~decoder.numChannels
~decoder.dirChannels.raddeg

(
{
    var sig;// audio signal
    var angle, azim;            // angle and azimuth control

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

// angle ---> top    = push to plane wave
    //            bottom = omni-directional
    angle = MouseY.kr(pi/2, 0);

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

// ------------------------------------------------------------
    // test sig
    sig = PinkNoise.ar;             // mono pink noise

// ------------------------------------------------------------
    // encode
    sig = FoaEncode.ar(sig, ~encoder);

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, 'push', angle, azim);

// ------------------------------------------------------------
    // decode (to binaural)
    FoaDecode.ar(sig, ~decoder);

}.scope;
)

// free kernel
~decoder.free

// ------------------------------------------------------------

CIPIC

Measured HRTF decoder, with measurements from the University of California Davis' CIPIC HRTF database.³ Forty-five subjects with varying head sizes are available. Audition to find one that works best for you.

NOTE: A kernel type decoder, see FoaDecoderKernel: *newCIPIC for further details.

// ------------------------------------------------------------
// Binaural (CIPIC) decoder
//
// mono pink noise source
// omni encoder

// define encoder / decoder matrices
~encoder = FoaEncoderMatrix.newOmni
~decoder = FoaDecoderKernel.newCIPIC    // kernel decoders should be freed after use!!
                                        // free below...