Debian Codegraph @

debian/doc/README

raw
1 AEOLUS
2 ============================
3
4
5 1. The stops directory
6 ----------------------
7
8 The aeolus binary itself is a generic organ synth and
9 does not define any instrument. In order to use Aeolus
10 you need a directory containing definitions of stops
11 and of an instrument. The one supplied with the current
12 release has this structure:
13
14
15 stops-0.3.0
16 |
17 |___ Aeolus
18 | |
19 | |____ definition
20 | |____ presets
21 |
22 |___ Aeolus1
23 | |
24 | |____ definition
25 | |____ presets
26 |
27 |___ Aeolus2
28 | |
29 | |____ definition
30 | |____ presets
31 |
32 |___ ***.ae0
33 |___ ***.ae0
34 |___ ***.ae0
35 |___ ...
36 |
37 |___ waves
38 |
39 |___ ***.ae1
40 |___ ***.ae1
41 |___ ***.ae1
42 |___ ...
43
44
45 The 'Aeolus' directory is the default instrument
46 directory. It contains two files: a 'definition'
47 file that specifies the layout of the organ, and
48 'presets' that contains registration and midi presets.
49
50 There can be more than one instrument definition
51 directory (in fact there are two more examples
52 in the supplied stops-0.3.0). These can be selected
53 with a command line option (see below).
54
55 The data in 'presets' only makes sense for one
56 particular instrument, and that's why these files
57 are kept together with the corresponding instrument
58 definition. For binary distributions, there is a
59 configuration option that will make Aeolus save the
60 presets in the users's home (see below). This will
61 allow the user to save presets for one instrument.
62
63 The *.ae0 files contain parameters for the additive
64 synthesis. There is one such file for each rank of
65 pipes in the organ. These are binary files and they
66 should not be edited. 'Power users' can use the built-in
67 synthesis editor to modify them (see section 5).
68
69 The waves directory will be empty initially. When
70 Aeolus starts up, it will compute wavetables, one for
71 each pipe. This is indicated by the flashing stop buttons.
72 The same will happen whenever the tuning or temperament is
73 changed. These wavetables can be saved (so Aeolus will be
74 ready for use much faster next time), but only if the stops
75 directory is writeable for the user. This will not be the
76 case for a binary installation as the stops dir will be
77 system-wide (e.g. /usr/share/Aeolus/stops-0.3.0).
78
79 In order to be able to save wavetables or edited stops
80 the stops directory must be copied to a location where
81 it can be modified by the user, (e.g. ~/stops-0.3.0).
82
83
84 2. Run-time configuration
85 -------------------------
86
87 Aeolus takes run-time options from three sources:
88
89 * the file /etc/aeolus.conf
90 * the file ~/.aeolusrc
91 * command line options
92
93 Apart from empty lines and comments (lines starting with '#')
94 either of the files should just contain the command line options
95 you want to use, on a single line (examples given below).
96
97 If the file in the home directory exists (even empty) then the
98 one in /etc is not used. Options given on the command line override
99 those given in either file.
100
101 Command line options are:
102
103 (audio interface)
104
105 -J Use JACK. This is also the default. The option
106 can be used to override a -A in the files.
107
108 -A Use ALSA. Aeolus should work with the "default"
109 device, but in recent ALSA releases this has a
110 very large buffer size, and this may result in
111 excessive latency. Use of a hardware device and
112 the options below is recommended.
113
114 Sub-options for ALSA and their defaults are:
115
116 -d <device> (default)
117 -r <sample rate> (48000)
118 -p <period size> (1024)
119 -n <number of periods> (2)
120
121 (output channels)
122
123 -C <number of channels>
124
125 The default is 2 (stereo). Other legal values
126 are 4 for four speakers in a square and 8 for
127 eight speaker in cube setup. The built-in
128 Ambisonics decoder used for the latter two
129 formats is quite primitive and will be removed
130 in future versions, to be replaced with a much
131 better external application.
132
133 Speaker order for -C 4 is clockwise starting at
134 front-left. For -C 8 the first four outputs are
135 the 'bottom' speakers, and the next four the
136 'top' ones, each of them in the same order as
137 for -C 4.
138
139 -B This options selects direct Ambisionics first order
140 B-format output, to be used for recording or with
141 an external decoder.
142
143 (resources)
144
145 -S <stops directory>
146
147 The default is ./stops.
148
149 -I <instrument directory>
150
151 This is relative to the stops directory.
152 The default is 'Aeolus'.
153
154 -W <waves directory>
155
156 This is relative to the stops directory.
157 The default is 'waves'. This options mainly exists
158 for use during development and should not be used.
159
160 -u This option is for use with binary distributions
161 only. When used, the presets file will be stored
162 into the user's home directory instead of within
163 the system wide instrument directory.
164
165 (general)
166
167 -t Selects the text mode user interface. With this
168 option Aeolus does not in any way depend on X11.
169 In the current version the text mode UI is just
170 an empty stub and should not be used.
171
172 -h Prints version information and a summary of all
173 command line options.
174
175
176 For example if you always use Aeolus with ALSA device hw:0,
177 using 3 periods of 512 frames and a sample rate of 44.1 kHz,
178 and you have copied the stops directory to your home, then
179 your ~/.aeolusrc could look like this:
180
181 # Aeolus default options
182 -A -d hw:0 -n 2 -p 512 -r 44100 -S /home/login/stops-0.3.0
183
184 where 'login' is your login name.
185
186
187 3. Binary packages
188 ------------------
189
190 This release permits packagers to install a working Aeolus
191 without touching a users's home directory, as follows.
192
193 * Install the aeolus binary in /usr/bin and the two
194 plugins in /usr/lib.
195 * Install the stops directory in /usr/share/Aeolus.
196 * Install this README into /usr/share/doc/packages/Aeolus.
197 * Create the file /etc/aeolus.conf containing:
198
199 # Aeolus default options
200 -u -A -S /usr/share/Aeolus/stops-0.3.0
201
202 This will use the default instrument 'Aeolus', and save the
203 presets in .aeolus-presets in the users's home directory.
204
205
206 4. A quick tour of the GUI
207 --------------------------
208
209 4.1 The main window
210
211 TBC
212
213 4.2 The instrument window
214
215 TBC
216
217 4.3 The audio window
218
219 TBC
220
221 4.4 The midi window
222
223 TBC
224
225
226 5. Editing the synthesis parameters
227 -----------------------------------
228
229 TBC
230
231
232 6. Midi control of stop buttons
233 -------------------------------
234
235 The protocol uses one controller number. The default is #98, but you
236 can change this in global.h. The message is accepted only on channels
237 enabled for control in the midi matrix.
238
239 The value is interpreted as follows:
240
241 v = 01mm0ggg
242
243 This type of messages (bit 6 set) selects a group, and either
244 resets all stops in that group or sets the mode for the second
245 form below.
246
247 mm = mode. This can be:
248
249 00 disabled, also resets all elements in the group.
250 01 set off
251 10 set on
252 11 toggle
253
254 ggg = group, one of the button groups as defined in the instrument
255 definition. In the GUI groups start at the top, the first one (for
256 division III) being group #0.
257
258 The values of mm and ggg are stored and need not be repeated unless
259 they change.
260
261 v = 000bbbbb
262
263 According to the current state of mode, this command switches a
264 stop on or off, or toggles its state, or does nothing at all.
265
266 bbbbb = button index within the group.
267
268 Buttons are numbered left to right, top to bottom within each
269 group. The first one is #0.
270
271
272 EOF
273