1----------------------------------------------------------------------------------- 2 3 Copyright (C) 2004-2010 Fons Adriaensen 4 5 This program is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation; either version 2 of the License, or 8 (at your option) any later version. 9 10 This program is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with this program; if not, write to the Free Software 17 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. 18 19----------------------------------------------------------------------------------- 20 21 22I'm using these mostly with Ardour (see below for some hints), 23but you could use any of these plugins as well in a softsynth 24such as AMS. 25 26-------------------------------------------- 27AMB-plugins-0.8.1 Released 2010.11.14 28-------------------------------------------- 29 30* Added UHJ encoder and decoder. 31 32-------------------------------------------- 33AMB-plugins-0.6.1 Released 2009.11.01 34-------------------------------------------- 35 36* Four new third order plugins added, created by 37 Joern Nettingsmeier. 38 39 1963 order 3,1 Mono panner 40 1964 order 3,1 Z-axis rotator 41 1965 full periphonic order 3 Mono panner 42 1965 full periphonic order 3 Z-axis rotator 43 44 See below for channel orders. 45 46* Added a first order 'virtual stereo mic' (same 47 as used in TetraProc). 48 49* Added a plugin converting the output of three 50 coincident cardiods (azimuths 60, -60, 180) to 51 first order B-format. 52 53-------------------------------------------- 54A note on channel order 55-------------------------------------------- 56 57All plugins operate to the Furse-Malham 58standard. This means that for the panners 59the W output is the input attenuated by 3dB, 60and all others have a maximum gain of 0dB. 61The decoders expect Furse-Malham signals. 62The rotators could be used with any type 63of normalisation. 64 65When using the plugins in e.g. Ardour you 66don't see the audio port names. The channel 67orders are: 68 691,1 plugins: W XYZ 702,2 plugins: W XYZ RSTUV 713,3 plugins: W XYZ RSTUV KLMNOPQ 72 732,1 plugins: W XY UV Z <-- note Z is last. 743,1 plugins: W XY UV PQ Z <-- note Z is last. 75 76Or in plain words, the full periphonic plugins 77use the Furse-Malham order, the mixed order N,1 78ones use the horizontal components in standard 79order and followed by Z. 80 81 82-------------------------------------------- 83AMB-plugins-0.4.0 Released 2009.02.02 84-------------------------------------------- 85 86* Two new plugins added, both second order 87 periphonic (i.e. nine channels). 88 89 1967 2nd order Mono panner 90 1968 2nd order Rotator 91 92-------------------------------------------- 93AMB-plugins-0.3.0 Released 2007.08.27 94-------------------------------------------- 95 96* Two new plugins added, both second order horizontal 97 and first order vertical (i.e. six channels). 98 99 1979 2nd order Mono panner 100 1980 2nd order Rotator 101 102* New name scheme introduced, using two numbers: 103 a,b means horizontal order 'a', vertical order 'b'. 104 105* Plugins are now organised in two files: 106 107 ambisonic1.so : first order (6 plugins) 108 ambisonic2.so : second order (2 plugins) 109 110The install target in the Makefile will remove any 111older versions. If you have saved host configurations 112(e.g. Ardour sessions) using any of these plugins you 113may have to remove and re-insert them. 114 115 116-------------------------------------------- 117AMB-plugins-0.1.0 Released 2006.07.16 118-------------------------------------------- 119 120Main feature of this release are the improved decoders. 121These now have optional phase-aligned shelf filters that 122enable to have a different decoding matrix for low and 123high frequencies. This is explained in more detail below. 124(A similar feature was present in older releases, but the 125implementation was not entirely correct and the filters 126used were not phase aligned). 127 128NOTE: if you are using the decoders in existing patches 129or sessions you may have to remove and re-insert them 130as the number and type of control ports has changed. 131 132The panner and rotation plugins are the same as in the 133previous release (0.0.2). 134 135 136B-format to square decoder 137-------------------------- 138 139B-format to hexagon decoder 140--------------------------- 141 142B-format to cube decoder 143------------------------ 144 145Decode a first order B-format to signals for a square, regular 146hexagon or cube speaker layout. All plugins have W,X,Y,Z inputs 147but Z is not used for the sqaure and hexagon versions. All three 148decoders share the same controls: 149 150 Front: This switch selects one of two possible layouts. 151 When 'off' the decoder assumes the usual setup 152 with left and right front speakers. The first 153 output is the left front speaker, then going 154 clockwise around the circle. 155 When 'on', the decoder assumes a rotated layout 156 with a single centre front and back speaker. 157 The first output is centre front in this case. 158 159 Distance: This should be used to compensate for the proximity 160 effect of the speakers in a small (e.g. control 161 room) layout. The parameter is the distance of the 162 listener to the speakers [1 .. 30m]. It controls a 163 1st order highpass filter on the velocity components. 164 165 Shelf, HF XYZ gain, LF XYZ gain, Shelf frequency: 166 167 These control the relative gain of the first (XYZ) 168 relative to the zero order (W) components. With the 169 Shelf switch 'off', the same value is used for all 170 frequencies and controlled by the HF XYZ gain value. 171 LF XYZ gain and Shelf frequency are not used in that 172 case. With Shelf switched 'on', separate control for 173 low and high frequencies is enabled. The Shelf frequency 174 parameter controls the transition frequency between the 175 two regions. 176 177 The two gain controls work as follows: 178 179 At the minimum setting (1), the decoding is such that 180 there will never be any antiphase signals for a single 181 source. This "in-phase" setting is usually recommended 182 for large (auditorium) setups where a larger "sweet 183 spot" is desired. 184 185 At the centre value of the gain controls (sqrt(2) for 186 horizontal and sqrt(3) for the cube decoder), the 187 result wil be the "max rE" decoding which is optimal 188 at high frequencies for small and medium size setups. 189 190 For the maximum value of the gain controls (2 for 2D 191 and 3 for 3D), the resulting decoding is the "max rV" 192 one which is optimal for low frequencies but will give 193 a smaller "sweet spot". 194 195 For a small (control room) setup for a single listener 196 the normal settings would be max rE for HF and max rV 197 for LF, together with the correct distance compensation. 198 199 200 201Mono to B format panner 202----------------------- 203 204Pan a mono source to a first order B-format. Controls are: 205 206 Elevation: Vertical component of the direction [-90 .. +90]. 207 Azimuth: Horizontal direction, [-180 .. +180]. 208 Positive values are to the right. Back is +/-180. 209 210 Changes to the control ports are 'smoothed' over one period. 211 The interpolation is done not on the input values but on the 212 direction vectors computed from them. This means for example 213 that if consecutive azimuth inputs are -170, +170, the result 214 will be a smooth transition through the back direction, just 215 as -10, +10 would interpolate via the front direction. 216 217 218Stereo to B format panner 219------------------------- 220 221Pan a stereo source to a first order B-format. Controls are: 222 223 Elevation: Vertical component of the direction [-90 .. +90]. 224 Azimuth: Horizontal direction of the center of the stereo 225 image, [-180 .. +180]. Positive values are to the 226 right. Back is +/-180. 227 Width: Horizontal width of the stereo image [-90 .. +90]. 228 Negative values give a mirror image. 229 230 As for the mono panner, the control port values are inter- 231 polated over one period, and there is no discontinuity at 232 +/- 180 azimuth, provided you give the right inputs. 233 234 235Horizontal rotator 236------------------ 237 238Rotate a first order B-format signal around the Z axis. there 239is just one control: 240 241 Angle: Rotation angle [-180 .. +180], positive is to the 242 right. 243 244 The rotation is smoothed in the same way as the for the two 245 panners. 246 247 248 249----------------------------- 250Using AMB plugins with Ardour 251----------------------------- 252 253Ardour is not aware of encoded formats such as B-format, and therefore 254using them requires some attention. Some hints: 255 256* Switch ON the option 'Use plugins while recording', and switch OFF 257the option 'Auto connect new tracks'. The latter is not saved in the 258session file, so watch out when reloading a session. The effects of 259the automatic connections can sometimes be quite confusing when using 260a mix of mono, stereo and B-format tracks and strips. 261 262* Panner plugins should normally be used post-fader. First create 263the strip's inputs (1 or 2) and outputs (4, 6, 8, 9, 16). Disable 264Ardour's multichannel panner, and insert and activate the plugin. 265 266* Apart from the 'auditioner', Ardour's mixer has no dedicated 267modules for monitoring, and hence no place to 'insert' a decoder. 268A practical solution is to create a 'monitoring' strip (not a 269'track' but a 'bus'). Insert the required decoder post-fader, 270connect the inputs to your B-format 'master' strip, and the outputs 271to the inputs of your monitoring system. Also connect the 'auditioner' 272outputs to the same destination as the first two decoder outputs. 273Apart from these, there should normally not be any other signals 274going directly to the speakers. 275 276 277