05_ADT and AmbDec

For this part of the guide, I would like to thank Fons Adriaensen and Aaron Heller for developing these tools and for their patience in answering my questions. I would also like to thank Frank Ekeberg for introducing me to them, and Anders Vinjard for creating the sample scripts on which I based my own.

This chapter of our guide will describe the workflow behind the use of AmbDec on Raspberry Pi in conjunction with ADT on GNU Octave. It is not meant to either explain the example patches [those will be covered in the patches themselves] nor the syntax of GNU Octave in depth [1], but will provide insight on the different processes required and all the resources at our disposal.

Downloading and installing GNU Octave:

The process of downloading and installing GNU Octave is slightly different for each operating system, but all the different approaches are described in the GNU Octave wiki on the category:installation page[2]. In my case, the main machine I use is a MacBook running MacOS, and I need to download and install GNU Octave via Homebrew. Homebrew is a package manager that hosts software that is missing from MacOS or Linux, making it available for both operating systems. First, we need to install Homebrew from our terminal by typing the command:

/bin/bash -c "$(curl -fsSLhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

This will also take a few minutes, but by the end of the process we should have a copy of Gnu Octave installed on our machine, ready to run from the terminal.

Generally speaking, the way Octave works, once started, is to read and evaluate functions that are imported and executed from the terminal. But these functions have to be stored somewhere. The default file extension that GNU Octave works with is .m, which is a text file. To work with .m files and to create the decoders we will run in GNU Octave, it is wise to use a text editor. You can use Vim, SublimeText or any other you prefer. For this project I started using Atom and switched to SublimeText when Atom was discontinued.

Working with ADT:

At this point, we need to download the Ambisonics Decoder Toolbox from its bitbucket repository, once we open it we will see a number of different folders - including decoders, examples and matlab - and a .m file called adt_initialize. This is the first function we will need to run every time we launch GNU Octave.

Regarding the folders mentioned above, matlab is the one that contains all the mathematical functions that Octave will call in our scripts, decoders is where Octave will store the files with the decoder matrices that we will create, examples is where we can find a wide range of scripts created by different users that show speaker layouts and decoders. The examples folder is a very good starting point for looking at different coding approaches.

The recommended way to work with the Ambisonics Decoder Toolkit is to create one .m file containing the loudspeaker setup and another .m file containing the decoder. We need to declare the loudspeaker coordinates in the first .m file - we can either do this individually or use a function in the case of a regular loudspeaker setup - then edit the .m file for the decoder to declare the loudspeaker setup file it needs to read from and all the other variables such as order, channel numbering and normalisation. Finally, we can run the function from Terminal.

In the terminal we need to start GNU Octave by typing octave. Then we need to navigate to the folder where the file adt_initialize is located and run it. To open any folder in the terminal we can type cd followed by the directory. In my case this is:

References 

[1] There are plenty of video tutorials dedicated to GNU Octave online and if you want to expand your expertise beyond what is required in this project it is a good idea to take a look at them: https://www.youtube.com/watch?v=TqwSlEsbObg

[2] https://wiki.octave.org/Category:Installation

[3] https://brew.sh/