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