HOA Tutorial Exercise 15

Extension

Previous: Exercise_14_HOA_NRT_decoding_script

Next: HOA_Tutorial_Overview

The general workflow (more details below) is as follows.

• - Write the speaker positions into an array in SC.
• - The helper class generates the ADT specific speaker position file (Matlab/Octave script).
• - The helper class generates the ADT run file for the specified parameters (Matlab/Octave script).
• - Open and execute the runfile in Matlab/Octave, this generates a Faust file which is automatically compiled as SC Ugen.
• - Use the helper class to generate a SC wrapper class which has the same argument list to interface with SC-HOA.
• - Move all the generated SC code to the Extension folder.
• - Recompile sclang, reboot the server, have fun!.

Things to do before you start:

• - Install a recent version of

  Faust: https://github.com/grame-cncm/faust/tree/master

• - Install

  either Octave: https://www.gnu.org/software/octave/

  or Matlab: https://www.mathworks.com/products/matlab.html

• Download the Ambisonics Decoder Toolkit

  ATD: https://bitbucket.org/ambidecodertoolbox/adt.git

To make this class work, we need to test Faust, Matlab/Octave, and the ADT first.

Testing Faust:

This Quark contains an ADT generated Faust script of a simple 5.0 decoder for testing purposes. Locate the itu5.dsp and move it to a location without a space in the path (on OSX the folder "Application Support" will create problems). Open a command line window, cd to where you have put itu5.dsp and execute:faust2supercollider -sn -ks -noprefix itu5.dsp

The compilation flags: -sn (supernova), -ks (keep source), -noprefix (no default Faust prefix for the generated Ugen Classes).

If all goes well you will get 4 files:

• the SuperCollider class file: itu5.sc
• the scsynth Ugen: itu5.scx
• the supernova Ugen: itu5_supernova.scx
• the supernova Ugen: itu5.cpp

Hint: With the .sc the .ccp and the wrapper Class from below you can package the decopder for your speaker array as SC3plugins so that the decoders can be compiled cross-platform.

Testing ADT in Matlab/Octave:

Make sure the ADT that you downloaded is in a folder under a path without spaces (we will excute the faust2supercollider command from above from Matlab/Octave). Go the the examples folder in the ADT and open the file run_dec_itu.m in Matlab or Octave. This is the file that generated the itu5.dsp from above. Execute the run_dec_itu.m script. If you get a path error you will need to include the paths to the examples and matlab folder in the script, which is just for testing purposes, the helper class will do that for you later.function [ output_args ] = run_dec_itu( n_spkrs, radius) addpath('/...MY/PATH/TO.../adt/examples/'); addpath('/...MY/PATH/TO.../adt/matlab/');

If all goes well, various plots about the decoder performance will pop up which you will find in the decoders folder together with the the Faust.dsp file. Faust files generated with the ADT have very long names, which inlude the info about decoder parameters. The file name equals the string after the "declare name" stament in the faust script and translates into the UGen name. The helperclass will allow you to set these names. The last output in the Matlab/Octave window must be the Ugen related files .scx _supernova.scx and .sc.

If your Faust, Matlab/Octave, and ADT installations work. You can start using the helper class:

First enter the speaker positions into an array in Cartesian coordinates, you can add after that a speaker label if you wish.// This is the speaker configuration of the Satosphere at the Societé des Arts Technologiques in Montreal ~spkrPos = [ [0.00, 0.00, 8.94, "top"], [1.47, 5.48, 6.91, "high"], [-4.01, 4.01, 6.91, "high"], [-5.48, -1.47, 6.91, "high"], [-1.47, -5.48, 6.91, "high"], [ 4.01, -4.01, 6.91, "high"], [ 5.48, 1.47, 6.91, "high"], [ 0.00, 7.88, 4.21, "middle"], [-3.94, 6.83, 4.21, "middle"], [-6.83, 3.94, 4.21, "middle"], [-7.88, 0.00, 4.21, "middle"], [-6.83, -3.94, 4.21, "middle"], [-3.94, -6.83, 4.21, "middle"], [ 0.00, -7.88, 4.21, "middle"], [ 3.94, -6.83, 4.21, "middle"], [ 6.83, -3.94, 4.21, "middle"], [ 7.88, 0.00, 4.21, "middle"], [ 6.83, 3.94, 4.21, "middle"], [ 3.94, 6.83, 4.21, "middle"], [ 0.00, 8.90, -0.88, "bottom"], [-4.45, 7.71, -0.88, "bottom"], [-7.71, 4.45, -0.88, "bottom"], [-8.90, 0.00, -0.88, "bottom"], [-7.71, -4.45, -0.88, "bottom"], [-4.45, -7.71, -0.88, "bottom"], [ 0.00, -8.90, -0.88, "bottom"], [ 4.45, -7.71, -0.88, "bottom"], [ 7.71, -4.45, -0.88, "bottom"], [ 8.90, 0.00, -0.88, "bottom"], [ 7.71, 4.45, -0.88, "bottom"], [ 4.45, 7.71, -0.88, "bottom"] ];

Then you need to define the path to where you have put the ATD, make an instance of the HOAAmbiDecoderHelper, set the setAmbiToolboxPath, and give your speaker array a name which becomes part of the name of the decoders you'll make.~path = "/...MY/PATH/TO.../adt/"; ~hoaAmbiHelper = HOAAmbiDecoderHelper(); ~hoaAmbiHelper.setAmbiToolboxPath(~path); ~hoaAmbiHelper.setSpeakerArrayName("SATO");

Then you can set the speaker position array. There is also a method to use spherical coordinates as input "specifySpeakersAsRadAzEl", see implementation for details. The class stores internally the speaker positions in Cartesian coordinates.~hoaAmbiHelper.specifySpeakersAsXYZ(~spkrPos);

If you want to change the sweetspot in your array you can do it for instance relative to the center of gravity of the speaker array.~hoaAmbiHelper.setSweetSpot(~hoaAmbiHelper.centerOfGravity + [0.0,0.0,-3.0]);

Next, make the speaker position file. This method generates a Matlab/Octave script which holds the speaker positions in an ADT compatible format. This file has the speaker array name you have set above and will be written to the ADT examples folder.~hoaAmbiHelper.makeAmbiDecoderSpeakerPositionFile();

Next, we make the run file. This Matlab/Octave script contains all the code to generate the decoders based on the speaker position written above. In this runfile you can specify the max order for which decoders will be made, the channel order as well as the channel normalization. For all these parameters you need to know what you do otherwise the decoder will not work together with your b-format the way as it should. The run file will be written to the ADT examples folder. The decoder that will be generated is at the moment the ADT implementation of the Allrad decoder, also compare the ADT website for references:

https://bitbucket.org/ambidecodertoolbox/adt.git

[1] F. Zotter, M. Frank, and A. Sontacchi, "The Virtual T-Design Ambisonics-Rig Using VBAP," presented at the 1st EAA-EuoRegio 2010 Congress on Sound and Vibration, Ljubljana, Slovenia, 2010, pp. 1-4.

[2] F. Kaiser, "A Hybrid Approach for Three-Dimensional Sound Spatialization," Algorithmen in Akustik und Computermusik 2, SE, May 2011.

[3] F. Zotter and M. Frank, "All-Round Ambisonic Panning and Decoding," J. Audio Eng Soc, vol. 60, no. 10, pp. 807–820, Nov. 2012.

Then check the run file that got created in the ADT examples folder and execute it in Matlab/Octave. If all goes well and you also have Faust installed the compiled Ugens should just come out like that.

After sucessfully generating the decoders as individual Ugens for each order, you can make the wrapper class, which will wrap the individual orders consistent with the rest of the HOA library. the path argument is the ADT path from above, followed by the order which should correspond to the order for which you made the Ugens.~hoaAmbiHelper.makeWrapperClass(~path, 5);

Because we have named the speaker array SATO the decoder wrapper class has the name HOADecSATO.HOADecSATO.ar(order, in, gain, lf_hf, mute, xover)

The arguments are:

• order: the decoder order.
• in: the b-format channel array.
• gain: in dB defaults t0 -10 dB.
• lf_hf: high freq/low freq balance in dB, default is 0.
• mute: default is on.
• xover: the hf_lf crossover frequency, default is 400 Hz.

The HOADecSATO class additionall has the following class variables:

• speakerPositions: an array of Cartesian points of the speaker positions in meters as provided in ~spkrPos above.
• sweeterPositions: an array of Cartesian points of the speaker positions in meters relative to the sweetspot.
• speakerLabels: speaker lables as provided above.

Previous: Exercise_14_HOA_NRT_decoding_script

Next: HOA_Tutorial_Overview