-----------------------------------------------------------------------------------

    Copyright (C) 2005 Fons Adriaensen
    
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

-----------------------------------------------------------------------------------


I'm using these mostly with Ardour. See below for some hints.


--------------------------------------------
AMB-plugins-0.0.1   First release 2005.06.11
--------------------------------------------

All the plugins in this release use first order B-format.
B-format signals have four channels named W, X, Y, Z and
always in that order. 



Mono to B format panner
-----------------------

Pan a mono source to a first order B-format. Controls are:

  Elevation: Vertical component of the direction [-90 .. +90]. 
  Azimuth:   Horizontal direction, [-180 .. +180].
             Positive values are to the right. Back is +/-180.
             
  Changes to the control ports are 'smoothed' over one period.
  The interpolation is done not on the input values but on the
  direction vectors computed from them. This means for example
  that if consecutive azimuth inputs are -170, +170, the result
  will be a smooth transition through the back direction, just
  as -10, +10 would interpolate via the front direction. 


Stereo to B format panner
-------------------------

Pan a stereo source to a first order B-format. Controls are:

  Elevation: Vertical component of the direction [-90 .. +90]. 
  Azimuth:   Horizontal direction of the center of the stereo
             image, [-180 .. +180]. Positive values are to the
             right. Back is +/-180.
  Width:     Horizontal width of the stereo image [-90 .. +90].
             Negative values give a mirror image.             

  As for the mono panner, the control port values are inter-
  polated over one period, and there is no discontinuity at
  +/- 180 azimuth, provided you give the right inputs.


Horizontal rotator
------------------

Rotate a first order B-format signal around the Z axis. there 
is just one control:
  
  Angle:     Rotation angle [-180 .. +180], positive is to the
             right.

  The rotation is smoothed in the same way as the for the two
  panners.


B-format to square decoder
--------------------------

Decode a first order B-format to signals for a square speaker
layout. Controls are:
 
  Front:     This switch selects one of two possible layouts.
             When 'off' the decoder assumes the usual setup
             with two front and two back speakers. The first
             output is for the left front speaker, and then
             clockwise around the circle.
             When on, the decder is for a 'diamond' layout, and
             the first output is for the central front speaker.
             
  Distance:  This should be used to compensate for the proximity
             effect of the speakers in a small (e.g. control
             room) layout. The parameter is the distance of the
             listener (center of the square) to the speakers
             [1 .. 30m]. It controls a first order highpass
             filter on the velocity components X and Y (the Z
             input is not used).
              
  LF ratio:  This control modifies the decoding matrix at low
             frequencies (up to about 700 Hz). It controls a
             'shelf' type filter on the velocity signals.
             At the mininum setting, a single source will never
             produce any antiphase signals. This is recommended
             for a large (auditorium) setup as it increases the
             size of the 'sweet spot'.
             At the maximum setting, the speaker(s) opposite to
             the source direction will produce antiphase signals
             in order to create a velocity component that
             corresponds exactly to the pressure. This is the
             optimum decoding in a psychoacoustic sense, and
             is recommended for studio use.


B-format to hexagon decoder
---------------------------

Decode a first order B-format to signals for a regular hexagon
speaker setup. The controls are the same as for the square
decoder above.



-----------------------------
Using AMB plugins with Ardour
-----------------------------

Ardour is not aware of encoded formats such as B-format, and this
requires some attention. Some hints:

* Switch ON the option 'Use plugins while recording', and switch OFF
the option 'Auto connect new tracks'. The latter is not saved in the
session file, so watch out when reloading a session. The effects of
the automatic connections can sometimes be quite confusing when using
a mix of mono, stereo and B-format tracks and strips.

* All the plugins should normally be used post-fader. First create
the strip's outputs (4, or 6 for the hexagon decoder), and connect
them. Then disable Ardour's multichannel panner. and only then
insert and activate the plugin.

* Apart from the 'auditioner', Ardour's mixer has no dedicated 
modules for monitoring, and hence no place to 'insert' a decoder.
A practical solution is to create a 'monitoring' strip (not a 
'track' but a 'bus'). Insert the required decoder post-fader,
connect the inputs to your B-format 'master' strip, and the outputs
to the inputs of your monitoring system. Also connect the 'auditioner'
outputs to the same destination as the first two decoder outputs.
Apart from these, there should normally not be any other signals
going directly to the speakers.


