ATK FAQs

Extension

Ambisonics

General questions about Ambisonics & Theory.

What do all these big Ambisonic words mean?

Try ATK Glossary.

What books on Ambisonics do you suggest?

• Zotter, Franz, and Frank, Matthias. Ambisonics. Springer, 2019.
• Ahrens, Jens. Analytic Methods of Sound Field Synthesis. Springer Berlin / Heidelberg, 2012.
• Williams, Earl G. Fourier Acoustics. Elsevier Science & Technology, 1999.

What HOA research libraries do you suggest?

In addition to the Ambisonic Decoder Toolbox, try:

• COMPACT HIGHER-ORDER AMBISONIC LIBRARY
• SPHERICAL HARMONIC TRANSFORM LIBRARY
• SOFiA sound field analysis toolbox
• Sound Field Synthesis Toolbox
• Spatial_Audio_Framework

Ambisonic Toolkit

Specific questions about the ATK.

Where should I start?

Try ABCs of the ATK, followed by Ambisonic Enlightenment.

How is the ATK structured?

Try ABCs of the ATK: Library architecture.

Where are Guides & Tutorials found?

Try ABCs of ATK Guides & Tutorials.

What do you mean by think Ambisonic?

Think of designing the spatial spectrum of the sound (or sound scene).

Though we talk a lot about Ambisonic panning laws, forget about panning sounds. Doing so restricts us to considering a soundworld primarily in terms of travelling waves.

Think instead about shaping the space of sounds. The ATK's tools are spatial domain filters; think in these terms.

What are the differences between the ATK's FOA and HOA toolsets?

Try this first, ABCs of the ATK: Two toolsets in one. We also suggest browsing the ATK's UGens and Matrix & Kernel links.

The two toolsets are intended to be used together. See Ambisonic Format Exchange for examples.

What's with the ATK's kernels and matrices?

Try ABCs of the ATK: Matrix & Kernel operations.

Where are the HOA kernels?

As the HOA toolset includes low level Ambisonic coefficient return, the long term plan is to implement the kernel functionality found on the FOA side with a design on demand pattern.

Where are the ATK's HOA binaural decoders?

For the short term, try the solutions suggested in Binaural Monitoring of HOA.

For the long term, see Where are the HOA kernels?

What decoders are available?

1. For FOA, you'll want to review: FoaDecoderMatrix & FoaDecoderKernel.
2. For HOA, see: HoaMatrixDecoder
3. Example implementations can be found here: ABCs of ATK Guides & Tutorials

Can I analyze decoders with the ATK?

Yes!

Review Pantophonic Monitoring of HOA (2D): Analysis for examples.

Can I analyze soundfields with the ATK:

Yes!

Try FoaAnalyze.

Where is the HOA version of FoaMyFavoriteThing?

Some possible answers:

1. There is not an analytic HOA equivalent.
2. FoaMyFavoriteThing has a slightly different name for HOA.
3. We haven't gotten around to it yet.

1. Chapman an Cotterell note, "a second-order dominance operation corresponding to Gerzon and Barton’s Lorentz transformation is impossible."¹ In response, Kronlachner and Zotter instead propose numeric solutions for HOA.²

The dominance family FOA transforms, like FoaFocus, are based on the Lorentz transformation. At some point we may provide a numerical HOA solution. However, the NFE beamforming solutions available in the HOA toolset can conveniently address many of the dominance operation use cases.

2. Yes, we gave it a different name. Maybe we did so because we think about the problem slightly differently now. Maybe we needed to be very clear given the different context of HOA. Maybe we just found we prefered to change the name to make SC's autocompletion more convenient.

Anyway, the ATK is our thing... so we get to do what we like! ;-)

3. If you haven't noticed, the ATK is a very big project! Our intention is to conveniently provide the tools and platform necessary to solve most imaginable Ambisonic problems. Sometimes these problems require resources that aren't currently available within the SuperCollider ecosystem, e.g. numerical resources found in scientific computing libraries. Sometimes we just haven't gotten around to it, or decided the best way to provide a convenient interface within the ATK.

You might like to jump down to Development & maintenance.

What can I use instead of FoaFocus, &c.?

Try NFE beamforming solutions.

Where is the HOA near-field shelf filter?

I.e., where is FoaPsychoShelf?

As FoaDecode handles its use behind the scenes, most FOA toolset users never notice the use of FoaPsychoShelf.

Our intention with the HOA framework it to be much more open. If you'd like to do multiband decoding (multiple panning laws!), psychoacoustic optimization is explicit. At the moment multi-band beam forming is provided by Signal: *hoaMultiBandFocl.

Does the ATK include near-field focalisation filters?

Yes!

Try Signal: *hoaFocl and Signal: *hoaMultiBandFocl.

How do I do reverb in Ambisonics?

Didn't we suggest trying AmbiVerbSC? BFFreeVerb and BFGVerb are also automagically installed as part of JoshUGens.

But wait, you say! These are FOA reverbs, so I can't do HOA reverb?

Well, these can be adapted for HOA given understanding a few principals. We plan to add a tutorial on HOA reverb at some point.

The short answer is:

Design the reverb in the angular domain.

The slightly longer answer: you'll need to go back and forth between the spherical and angular domains. See Spherical Decomposition.

How do I do DAFX in Ambisonics?

An easy way would be to use a 3rd party plugin that does everything for us. (See Can I use 3rd party Ambisonic VST plugins with the ATK?)

Depending on the effect, we'll either apply it directly in the sphercial domain (B-format), or do so in the angular domain (A-format).

The way we decide:

• B-format: All channels processed the same.
• A-format: Any or all channels processed differently.

With Ambisonic encoding, the space of a sound is encoded as amplitude (angular & radial) and phase (radial) differences between channels. If our effect will change the relationships between channels, process in the angular domain (A-format).³ If the relations will stay the same, it is fine to do the processing in the spherical domain (B-format).

If you have no idea, you can stay safe by processing in A-format.⁴

See Spherical Decomposition.

Does the ATK support mixed order encoding?

Short answer: no.

Longer answer: For an HOA signal of a given order, all components are required. If you have a signal from mixed order microphone, you'll need to supply zeros in place of the missing channel. Silent will do the job.

Even longer answer: We think the best solution is to use an upsampling technique to fill in the missing component. Doing so means the various spatial filters and transforms act as expected.

What HOA microphones does the ATK support?

Given the manufacturer's own HOA encoding software, requirements are:

1. correct Ambisonic Format Exchange
2. complete HOA signal set

Can FOA recordings and HOA soundfields be used together?

This is both a technical and aesthetic question!

Technical answers:

If we wish to use the HOA toolset tools with FOA recordings, the FOA signal should be exchanged to HOA1. Obviously, we can go the other way too. Review this & this.

If we wish to mix FOA recordings into an HOA bus, we need to first match the FOA signal to the target HOA signal set. This means matching:

• Ambisonic order
• Ambisonic component ordering
• Ambisonic component normalisation
• Ambisonic reference radius

Matching the last three is Ambisonic Format Exchange. To match Ambisonic order, we'll need to spatially upsample the FOA signal to meet the HOA target.

Aesthetic answer:

Composers working in the acousmatic tradition have long composed works using mixed spatial stems. That is, one layer of the piece may have been composed in two channel stereo, while another layer is in six or eight channels positioned around an audience.

We can take the exact same approach with Ambisonics. A mix of several layers of different orders can offer a very interesting and convincing result.

What is the highest order supported for spherical decomposition?

At the time of this writing, tenth order is the maximum order supported for inbuilt spherical decomposition using the SphericalDesign class. This is due to the size of the largest included spherical design.

We think tenth order is, well, fairly high. Especially given:"Tenth order Ambisonics requires % channels to encode!".format(HoaOrder.new(10).size).postln;

Conveniently, we can directly ask this question in code:( // set question parameters... ( ~order = 10; ~optimize = \energy; ); // // ... or, try this one // ( // ~order = 11; // ~optimize = \spreadE; // ) // ask the question... ( "Does the ATK support spherical decomposition for: ".postln; " optimize: %".format(~optimize).postln; " order: %".format(~order).postln; ); // ... get your answer! ( TDesignLib.getHoaDesigns(~optimize, ~order).isEmpty.not.if({ "Yes!".postln; }, { "Yes... but... you'll need to import larger designs and/or matrices.".postln; }); ) )

Rendering higher orders is possible via the inclusion of larger designs and/or custom matrices.

If you've installed the ADT quark, larger designs are available in the Ambisonic Decoder Toolbox.

How do I do NRT?

Try SynthDef and NRT examples for ATK.

Any 3rd party spatializers built on the ATK?

We know of:

1. Mosca⁵
2. 3Dj⁶

If you're aware of any others, do let us know.

Can I use 3rd party Ambisonic VST plugins with the ATK?

Yes!

See the VSTPlugin project.⁷ If you've installed VSTPlugin, the documentation can be found here. You'll note there's a discussion on using HOA VST plugins!

As you'd expect, you'll need to correctly Ambisonic Format Exchange.

Development & maintenance

Questions on the ATK as a project.

The ATK is availabe in what distributions?

At this time there are two public distributions of the ATK:

1. ATK for SuperCollider⁸
2. ATK for Reaper⁹

Both may be accessed via the Ambisonic Toolkit web page.

Since 1997, the ATK has existed in various incarnations; first as library of Csound orcs:

• MusicN: Csound¹⁰ , Common Lisp Music¹¹ , SuperCollider¹²
• Numerical: Python / SciPy¹³
• Plugins: VST, JSFX¹⁴

Who made the ATK?

And when?

Vague timeline:

1997

Private: Joseph Anderson

1999

Private: Juan Pampin, Anderson

2011

SuperCollider (FOA): Anderson, Pampin, Josh Parmenter.¹⁵

2013

JSFX / Reaper: Trond Lossius, Anderson

2020

SuperCollider (FOA / NFC-HOA): Anderson & Michael McCrea, w/ Daniel Peterson & Marcin Pączkowski

How do I report a bug?

Hurrah! Thanks for finding a bug!

As you might imagine, with a large, complex, multifacitated codebase, bugs do creep in from time to time. We're happy to report that a fair amount of community contribution to the ATK has come from fixing issues that turn up.

Visit Feedback and Bug Reports as your starting point, and follow additional links to the issue tracker to make a formal report.

SuperCollider offers specific guidance on reporting bugs. Observing this advice will make the issue easier to resolve. In particular, following the steps outlined in Submitting a bug give the dev team the information necessary to begin understanding exactly what the bug is, and open the door to understanding how to go about squashing it.

How do I request a guide or tutorial?

Follow the advice immediately above, and label the issue as documentation.

How do I submit a guide or tutorial?

Great idea! First submit an issue as described above so we know what you're thinking about. It is also possible to begin with an informal conversation with us by contacting us through the channels listed at Feedback and Bug Reports.

How can I support further development of the ATK?

• Use it!
• Have you found a bug? Please report! If you can fix it by submitting a pull request, that would be great!
• The ATK could really use some robust UnitTesting. If you can contribute here, doing so will really help us keep the ATK in shape.
• Are you up for writing a quark able to read SOFA files? Yes? Doing so could help us implement binaural decoder designers sooner rather than later.