Guides (extension) | Libraries > Ambisonic Toolkit


Ambisonic Toolkit Frequently Asked Questions


General questions about Ambisonics & Theory.

What do all these big Ambisonic words mean?

Try ATK Glossary.

What books on Ambisonics do you suggest?

What HOA research libraries do you suggest?

In addition to the Ambisonic Decoder Toolbox, try:

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.

NOTE: The HOA toolset is intended to provide a broad foundation upon which specific designs may be built. In time, our intention is to illustrate example designs via tutorials.

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.

NOTE: We intend to provide a binaural decoder design example in the near term.

Where are the 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?


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

Can I analyze soundfields with the ATK:


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."1 In response, Kronlachner and Zotter instead propose numeric solutions for HOA.2

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.

NOTE: There are some interesting modal transforms that are kinda like FoaPush. Stay tuned!!

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.

NOTE: We intend to add a more explicit use case example at a later date.

We're also considering adding an IIR option, too.

Does the ATK include near-field focalisation filters?


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.

NOTE: If you're up for designing your own, here are a few papers to review:

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:

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).3 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.4

See Spherical Decomposition.

NOTE: We plan to include a moderately verbose tutorial at some point.

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.

NOTE: We intend to include a short tutorial on the topic.

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
NOTE: We intend to include tutorials on desiging encoding filters for direct ATK encoding at some point.

The SpHEAR Project is an interesting candidate.

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:

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.

NOTE: If we don't upsample the FOA signal to meet the HOA target, we are mixing a spatially truncated signal (lower spatial sampling rate) into a higher rate bus. As a result, transforms won't behave as expected, and significant energy and imaging mismatches may be heard on decoding.

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.

NOTE: In performance practice, we often decode an HOA piece to different layers of highly sampled and lower order arrays.

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:

Conveniently, we can directly ask this question in code:

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. Mosca5
  2. 3Dj6

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

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


See the VSTPlugin project.7 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 SuperCollider8
  2. ATK for Reaper9

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:

Who made the ATK?

And when?

Vague timeline:

Private: Joseph Anderson
Private: Juan Pampin, Anderson
SuperCollider (FOA): Anderson, Pampin, Josh Parmenter.15
JSFX / Reaper: Trond Lossius, Anderson
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?

[1] - Michael Chapman and Philip Cotterell, “Towards a com-prehensive acount of valid Ambisonic Transformations,”in Ambisonics Symposium, Graz, 2009.
[2] - Kronlachner, M., Zotter, F. Spatial transformations for the enhancement of Ambisonic recordings. ( Theile, G. ). Proceedings of the International Conference on Spatial Audio 2014 (International Conference on Spatial Audio 2014) . 2014.
[3] - One exception could be dynamic range compresion. This effect can be managed in the spherical domain, "by degree".
[4] - It won't hurt, but you may end up using just a bit more CPU time than needed.
[7] - The compiled SuperCollider release is found here:
[15] - Aka, "The three Js."