Transforming FOA | SuperCollider 3.13.0 Help

Imaging

For the artist, the real power of the ATK is found in the imaging transforms. These are spatial domain filters which reorient, reshape or otherwise spatially filter an input soundfield. Many users will be familiar with the soundfield rotation transform, as SuperCollider provides the inbuilt Rotate2.

The ATK provides a much wider and comprehensive toolset, including:

rotation: soundfield rotation about an axis
mirror: soundfield reflection across an axis
directivity: soundfield directivity
dominance: adjust directional gain of soundfield
focus: focus on a region of a soundfield
push: push a soundfield in a direction

Imaging tools are provided in two forms: static and dynamic implementations. While most transforms are provided in both categories, a number are found in only one guise.¹

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

NOTE: See FoaTransform, FoaXform and FoaXformerMatrix for more details regarding FOA imaging.

________________

NOTE: The text immediate below follows a workflow in explicit sclang. For a quick review, you may prefer to jump below to try the included transform audition and visualization utilities.

Choose a decoder

With the examples below, we'll start by first choosing a suitable decoder with with to audition.

Choose a decoder suitable for your system, as discussed here. You'll end up definining ~decoder and ~renderDecode .

NOTE: If you choose a kernel decoder, FoaDecoderKernel, be sure to free the kernel after use.

Dynamic examples

Dynamic transforms are rendered via UGens accepting continuously varying arguments. The below examples use the FoaTransform wrapper as a convenience. Users may choose to employ the underlying wrapped UGen, as desired. These are noted for each example below.

Rotate

Rotation is one of the most used soundfield transforms. In this case we'll it to centre the subject of a field recording.

The soundfield is controlled by MouseX, which specifies the rotation angle (pi to -pi; left to right of display).

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: A UGen type transformer, see FoaRotate for further details.

// ------------------------------------------------------------
// rotate transformer
// b-format soundfile read from disk

// choose transformer
~transformer = 'rotate'

// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Courville-Dialogue.wav")
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Hodges-Purcell.wav")
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Orfeo_Trio.wav")

(
{
    var sig;                            // audio signal
    var azim;                           // azimuth control

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

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

// ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, azim);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------

NOTE: Soundfile Credits

D. Courville, "Comparative Surround Recording," Ambisonic Studio | Comparative Surround Recording, 2007. [Online]. Available: http://www.radio.uqam.ca/ambisonic/comparative_recording.html [Accessed: 26-Jul-2011].
P. Hodges, "Purcell - Passacaglia (King Arthur)," Sound of Space: ambisonic surround sound. [Online]. Available: http://soundofspace.com/ambisonic_files/52 [Accessed: 03-Nov-2011].
J. Leonard, "The Orfeo Trio & TetraMic," Sound of Space: ambisonic surround sound. [Online]. Available: http://soundofspace.com/ambisonic_files/41 [Accessed: 03-Nov-2011].

DominateX

Dominance specified in gain is a classic Ambisonic production technique. Here we apply gain across the X axis. With these example recordings, we adjust both the stage width and the subject to reverb balance.

The soundfield is controlled by MouseY, which specifies the dominance gain (4.5 dB to -4.5 dB; top to bottom of display).

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: A UGen type transformer, see FoaDominateX for further details.

// ------------------------------------------------------------
// dominateX transformer
// b-format soundfile read from disk

// choose transformer
~transformer = 'dominateX'

(
{
    var sig;                            // audio signal
    var gain;                           // gain control

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

// gain ---> top            = +4.5db for front
    //            bottom        = -4.5db for front
    gain = MouseY.kr(4.5, 4.5.neg);

// ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, gain);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------

NOTE: Soundfile Credits

D. Courville, "Comparative Surround Recording," Ambisonic Studio | Comparative Surround Recording, 2007. [Online]. Available: http://www.radio.uqam.ca/ambisonic/comparative_recording.html [Accessed: 26-Jul-2011].
P. Hodges, "Purcell - Passacaglia (King Arthur)," Sound of Space: ambisonic surround sound. [Online]. Available: http://soundofspace.com/ambisonic_files/52 [Accessed: 03-Nov-2011].
J. Leonard, "The Orfeo Trio & TetraMic," Sound of Space: ambisonic surround sound. [Online]. Available: http://soundofspace.com/ambisonic_files/41 [Accessed: 03-Nov-2011].

Focus

Here we encode four channels of decorrelated and comb filtered PinkNoise as a decorrelated soundfield, resulting in a maximally diffuse soundfield. FoaFocus is used to "focus" on various parts of the soundfield. At extremes, it becomes a planewave (infinite distance, in an anechoic environment) arriving from some direction. This technique gives the opportunity to continuously modulate between a directional and a diffuse soundfield.

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 FoaFocus angle (0 to pi/2; bottom to top of display). With the mouse at the bottom of the display, the soundfield remains decorrelated. 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.

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: A UGen type transformer, see FoaFocus for further details.

// ------------------------------------------------------------
// focus transformer
// decorrelated, comb filtered pink noise source

// define encoder matrix
~encoder = FoaEncoderMatrix.newAtoB

// choose transformer
~transformer = 'focus'

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

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

// frequencies
    freq = 220;

// 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([1, 1, 1, 1]); // 4 channels decorrelated pink noise

// ------------------------------------------------------------
    // comb filter
    sig = HPF.ar(sig, freq);
    sig = CombL.ar(sig, freq.reciprocal, freq.reciprocal, mul: 9.neg.dbamp);

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

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, angle, azim);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

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

Push and RTT

Here we encode four channels of Klank resonated Dust from A-format. FoaPush is used to "push" the soundfield so that it becomes a planewave (infinite distance, in an anechoic environment) arriving from some direction. This technique gives the opportunity to continuously modulate between a directional and a spatially active soundfield. Additionally, FoaRTT is used to continuously reorient the granular stream so that individual A-format directions don't predominate, and the complete soundfield is filled with activity.

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

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: UGen type transformers, see FoaPush and FoaRTT for further details.

// ------------------------------------------------------------
// push and rtt transformer
// granular klank stream source

// define encoder matrix
~encoder = FoaEncoderMatrix.newAtoB

// choose transformer
~transformer1 = 'rtt'
~transformer2 = 'push'

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

// ir...
    var gain = -18;

var freqs = [50.0, 7000.0], gains = [-24, 0], rtimes = [0.1, 2.0];
    var frequencies, amplitudes, ringTimes;
    var numModes = 20;

var density = 20;                  // grain/klank density

var rttFreq = 10 * density;

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

// calculate klank args
    frequencies = Array.rand(numModes, freqs[0], freqs[1]).sort;
    amplitudes = Array.rand(numModes, gains[0], gains[1]).sort.reverse.dbamp;
    ringTimes = Array.rand(numModes, rtimes[0], rtimes[1]).sort.reverse;

// 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 = Dust.ar(Array.fill(4, density / 4));

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

// ------------------------------------------------------------
    // transform 1 (rtt)
    sig = FoaTransform.ar(
        sig,
        ~transformer1,
        LFSaw.ar(rttFreq, pi, add: pi),
        LFSaw.ar(rttFreq**(1/3), pi, add: pi),
        LFSaw.ar(rttFreq**(2/3), pi, add: pi)
    );

// ------------------------------------------------------------
    // Klank
    sig = gain.dbamp * Klank.ar(
        `[ frequencies, amplitudes, ringTimes ],
        sig
    );

// ------------------------------------------------------------
    // transform 2 (push)
    sig = FoaTransform.ar(sig, ~transformer2, angle, azim);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

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

Push and RTT with newSpread

Here we encode the mono component of a stereo soundfile via the FoaEncoderKernel: *newSpread encoder. FoaPush is used to "push" the soundfield so that it becomes a planewave (infinite distance, in an anechoic environment) arriving from some direction. This technique gives the opportunity to continuously modulate between a directional and a spatially spread soundfield. Additionally, FoaRTT is used to continuously reorient the frequency spread soundfield so that individual frequencies are moved throughout the space, and the complete soundfield is constantly in motion.

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: UGen type transformers, see FoaPush, FoaRTT and FoaEncoderKernel: *newSpread for further details.

// ------------------------------------------------------------
// push and rtt transformer
// spreader encoder
// stereo soundfile read from disk

// define encoder matrix
~encoder = FoaEncoderKernel.newSpread(0000)
~encoder = FoaEncoderKernel.newSpread(0001)
~encoder = FoaEncoderKernel.newSpread(0006)
~encoder = FoaEncoderKernel.newSpread(0008)
~encoder = FoaEncoderKernel.newSpread(0010)
~encoder = FoaEncoderKernel.newSpread(0012)

// free kernel (when you swap encoders!)
~encoder.free

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

// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/stereo/The_City_Waites-The_Downfall.wav")
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/stereo/The_City_Waites-An_Old.wav")
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/stereo/Aurora_Surgit-Lux_Aeterna.wav")
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/stereo/Aurora_Surgit-Dies_Irae.wav")

// free buffer (when you swap buffers!)
~sndbuf.free

(
{
    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 = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile
    sig = 0.5 * sig.sum; // to mono

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

// ------------------------------------------------------------
    // transform
    sig = FoaRTT.ar(sig,
        LFNoise2.kr(1.0/5.0, pi),
        LFNoise2.kr(1.0/5.0, pi),
        LFNoise2.kr(1.0/5.0, pi)
    );
    sig = FoaTransform.ar(sig, 'push', angle, azim);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// free kernel
~encoder.free
// ------------------------------------------------------------

FocusX, ZoomX & PushX

With this example we encode four channels of comb filtered Dust as planewaves arriving from the cardinal directions. FoaFocusX, FoaZoomX and FoaPushX are used to distort the soundfield. At extremes, encoded planewaves are distorted to arrive from the same direction. This example allows one to compare these transforms on the x-axis.

The soundfield is controlled by MouseY, with angle varying between -pi/2 and pi/2. With the mouse in the centre of the display, the soundfield remains unchanged. Placed at the top or bottom of the display, the soundfield is distorted.

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: UGen type transformers, see FoaFocusX, FoaZoomX & FoaPushX for further details.

// ------------------------------------------------------------
// x-axis transformers
// comb filtered dust noise source, at cardinal points

// define encoder matricies, for each cardinal point
(
~encoder = [
    FoaEncoderMatrix.newDirection,
    FoaEncoderMatrix.newDirection(pi/2),
    FoaEncoderMatrix.newDirection(pi),
    FoaEncoderMatrix.newDirection(pi.neg/2)
]
)

// choose transformer
~transformer = 'focusX'
~transformer = 'zoomX'
~transformer = 'pushX'

(
{
    var sig;                            // audio signal
    var angle;                          // angle control
    var freq;
    var density = 10;                   // grain density

// display encoder and decoder
    "Ambisonic encoding via % encoder".format(~encoder[0].kind).postln;
    "Ambisonic transforming via % transformer".format(~transformer).postln;
    "Ambisonic decoding via % decoder".format(~decoder.kind).postln;

// frequencies
    freq = 220 * [ 4, 5, 7, 6 ] / 4;

// angle ---> top           = pi/2
    //            bottom        = -pi/2
    angle = MouseY.kr(pi/2, pi.neg/2);

// ------------------------------------------------------------
    // test sig
    sig = Dust.ar(Array.fill(4, density / 4));

// ------------------------------------------------------------
    // comb filter
    sig = BPF.ar(sig, freq, mul: 18.dbamp);
    sig = CombL.ar(sig, freq.reciprocal, freq.reciprocal, mul: 9.neg.dbamp);

// ------------------------------------------------------------
    // encode
    sig = Mix.fill(sig.numChannels, { arg i;  FoaEncode.ar(sig[i], ~encoder[i]) });

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, angle);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

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

Balance and Asymmetry

With with the above example we encode four channels of comb filtered Dust as planewaves arriving from the cardinal directions. FoaZoomY and FoaAsymmetry are used to distort the soundfield. At extremes, encoded planewaves are distorted to arrive from the same direction. This example allows one to compare these transforms on the y-axis.

The soundfield is controlled by MouseX, with angle varying between -pi/2 and pi/2. With the mouse in the centre of the display, the soundfield remains unchanged. Placed at the left or right of the display, the soundfield is distorted.

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: UGen type transformers, see FoaZoomY and FoaAsymmetry for further details.

// ------------------------------------------------------------
// y-axis transformers
// comb filtered dust noise source, at cardinal points

// choose transformer
~transformer = 'balance'
~transformer = 'asymmetry'

(
{
    var sig;                            // audio signal
    var angle;                          // angle control
    var freq;
    var density = 10;                   // grain density

// frequencies
    freq = 220 * [ 4, 5, 7, 6 ] / 4;

// angle ---> left          = pi/2
    //            right         = -pi/2
    angle = MouseX.kr(pi/2, pi.neg/2);

// ------------------------------------------------------------
    // test sig
    sig = Dust.ar(Array.fill(4, density / 4));

// ------------------------------------------------------------
    // encode
    sig = Mix.fill(sig.numChannels, { arg i;  FoaEncode.ar(sig[i], ~encoder[i]) });

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, angle);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

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

Proximity

FoaProximity facilitates the introduction of the proximity effect to encoded signals. At extremes, the proximity effect introduces a strong bass boost, as well as phase differences. The proximity effect can be an important contributor to perceptions of nearness.

The soundfield is controlled by MouseY, with distance varying between 0.05 and 0.5 meter. With the mouse at the bottom of the display, the soundfield receives the strongest effect, contributing to as sense of nearness.

WARNING: As FoaProximity includes a 1st-order integration, signals must be highpass filtered before application. HPF is usually a suitable choice to control low frequency boost.

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: UGen type transformer, see FoaProximity for further details.

// ------------------------------------------------------------
// proximity transform
// comb filtered dust noise source, panned across the front

// define encoder matricies
(
~encoder = [
    FoaEncoderMatrix.newDirection(pi/6),
    FoaEncoderMatrix.newDirection(pi/12),
    FoaEncoderMatrix.newDirection(pi.neg/12),
    FoaEncoderMatrix.newDirection(pi.neg/6)
]
)

// choose transformer
~transformer = 'proximity'

(
{
    var sig;                            // audio signal
    var dist;                           // distance control
    var freq;
    var density = 10;                   // grain density

// frequencies
    freq = 220 * [ 4, 5, 7, 6 ] / 4;

// dist  ---> top           = 0.5
    //            bottom        = 0.05
    dist = MouseY.kr(0.5, 0.05);

// ------------------------------------------------------------
    // test sig
    sig = Dust.ar(Array.fill(4, density / 4));

// ------------------------------------------------------------
    // encode
    sig = Mix.fill(sig.numChannels, { arg i;  FoaEncode.ar(sig[i], ~encoder[i]) });

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, dist);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

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

NFC

FoaNFC facilitates the reduction or removal of the proximity effect from encoded signals. The proximity effect can be an important contributor to perceptions of nearness.

The soundfield is controlled by MouseY, with distance varying between 0.5 and 0.05 meter. With the mouse at the top of the display, the soundfield receives the strongest effect (removal), contributing to as sense of distance.

If you haven't already choosen a ~decoder and defined ~renderDecode, do so now.

NOTE: UGen type transformer, see FoaNFC for further details.

// ------------------------------------------------------------
// NFC transform
// b-format soundfile read from disk

// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Anderson-Nearfield.wav")

// choose transformer
~transformer = 'nfc'

(
{
    var sig;                            // audio signal
    var dist;                           // distance control

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

// dist  ---> top           = 0.05
    //            bottom        = 1.0
    dist = MouseY.kr(0.05, 1.0);

// ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile

// ------------------------------------------------------------
    // transform
    sig = FoaTransform.ar(sig, ~transformer, dist);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------

NOTE: Soundfile Credits

Joseph Anderson, "Near-field source," [unpublished recording]

Static examples

Rather than using the UGen wrapper FoaTransform to render dynamicly changing spatial filtering, as above, FoaXform is used to render the transform specified by FoaXformerMatrix, which returns a fixed spatial filtering matrix.

This functionality is provided to complete the matrix processing paradim of the ATK.

Rotate

Rotation is one of the most used soundfield transforms. In this case we'll it to centre the subject of a field recording.

If you haven't already choose a ~decoder and defined ~renderDecode, do so now.

NOTE: A matrix type transformer, see FoaXformerMatrix: *newRotate for further details.

// ------------------------------------------------------------
// rotate xformer
// b-format soundfile read from disk

// define xformer matrix
~xformer = FoaXformerMatrix.newRotate           // no rotation --> try this 1st
~xformer = FoaXformerMatrix.newRotate(-110.degrad) // by -110deg   --> try this 2nd

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

// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Chinook.wav")

(
{
    var sig;                            // audio signal

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

// ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile

// ------------------------------------------------------------
    // transform
    sig = FoaXform.ar(sig, ~xformer);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------

NOTE: Soundfile Credits

J. Leonard, "A couple of Chinook helicopters," Sound of Space: ambisonic surround sound, 20-Mar-2008. [Online]. Available: http://soundofspace.com/ambisonic_files/47 [Accessed: 03-Nov-2011].

MirrorO

In mirroring through the origin and delaying the soundfield, we can generate a new set of echos in this fireworks field recording.

If you haven't already choose a ~decoder and defined ~renderDecode, do so now.

NOTE: A matrix type transformer, see FoaXformerMatrix: *newMirrorO for further details.

// ------------------------------------------------------------
// mirrorO xformer
// b-format soundfile read from disk

// define xformer matrix
~xformer = FoaXformerMatrix.newMirrorO

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

// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Fireworks.wav")

(
{
    var sig;                            // audio signal
    var delSig;                         // delayed signal
    var freq;                           // lp frequency
    var delay;                          // delay time
    var scale;                          // delay gain (as scale)

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

// ------------------------------------------------------------
    // parameters
    freq = 1200;                        // in Hz
    delay = 0.5;                        // in seconds
    scale = 9.neg.dbamp;

// ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile

// ------------------------------------------------------------
    // delay, lp and gain
    delSig = LPF.ar(DelayN.ar(sig, delay, delay), freq, scale);

// ------------------------------------------------------------
    // transform
    delSig = FoaXform.ar(delSig, ~xformer);

// ------------------------------------------------------------
    // sum (comment this out to hear original signal)
    sig = sig + delSig;
//    sig = delSig;                    // or listen to the mirrored sig

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------

NOTE: Soundfile Credits

J. Leonard, "Fireworks," Sound of Space: ambisonic surround sound, 25-Aug-2009. [Online]. Available: http://soundofspace.com/ambisonic_files/37 [Accessed: 03-Nov-2011].

DominateX

Dominance adjusts the gain of a soundfield in a particular direction. Here we'll increase the amount of reverberation in this natural soundfield recording. As the image is warped at the same time, we'll also hear the frontal stage widen.

If you haven't already choose a ~decoder and defined ~renderDecode, do so now.

NOTE: A matrix type transformer, see FoaXformerMatrix: *newDominateX for further details.

// ------------------------------------------------------------
// dominateX xformer
// b-format soundfile read from disk

// define xformer matrix
~xformer = FoaXformerMatrix.newDominateX           // no dominance --> try this 1st
~xformer = FoaXformerMatrix.newDominateX(-3.0)    // increase gain at rear

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

// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Orfeo_Trio.wav")

(
{
    var sig;                            // audio signal

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

// ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, BufRateScale.kr(~sndbuf), doneAction:2);   // soundfile

// ------------------------------------------------------------
    // transform
    sig = FoaXform.ar(sig, ~xformer);

// ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------

NOTE: Soundfile Credits

J. Leonard, "The Orfeo Trio & TetraMic," Sound of Space: ambisonic surround sound. [Online]. Available: http://soundofspace.com/ambisonic_files/41 [Accessed: 03-Nov-2011].

Transform utilities

The ATK includes the following useful transform audition and visualization utilities:

FoaAudition: Audition FOA recordings, panning planewaves, diffuse soundfields, and transforms
FoaXformDisplay: Visualize, audition and customize FOA soundfield transforms

These tools offer a very quick and convenient way to become familiar with the ATK's imaging tranforms. You might like to start with the visualizer, FoaXformDisplay, as a quick way to understand transformer parameters change a soundfield.

[1] - It is also useful to note that the dynamic transforms are also available as individual UGens. However, users are advised to use FoaTransform for convenience.

helpfile source: HelpSource/Guides/Transforming-FOA.schelp
link::atk-sc3/Guides/Transforming-FOA::

Transforming FOAExtension

Transforming FOA
Extension