Debian Codegraph @

README

raw
1 ================================================================
2 AWE32 Sound Driver Utility Programs for Linux / FreeBSD
3 version 0.5.1
4
5 Takashi Iwai <[email protected]>
6 ================================================================
7
8 ----------------------------------------------------------------
9 * GENERAL NOTES
10
11 Thie package includes several utilities for AWE32 sound driver on
12 Linux and FreeBSD systems and for Emux WaveTable of ALSA sbawe and
13 emu10k1 drivers. You need to use these utilities to enable sounds on
14 these drivers properly.
15
16 The package is managed with GNU auto-tools since version 0.5.0.
17 The ALSA support (asfxload) is added also in this version.
18
19 Ver.0.4.3 improves the parameter calculation as almost compatible with
20 the DOS/Win drivers. This is more effective in the case of ROM sounds.
21 If you prefer the old type sounds, use --compatible option.
22
23 This packaing contains the following programs:
24
25 for ALSA
26 - asfxload SoundFont file loader
27
28 for OSS
29 - sfxload SoundFont file loader
30 - setfx Chorus/reverb effect loader
31 - aweset Change the running mode of AWE driver
32 - sf2text Convert SoundFont to readable text
33 - text2sf Revert from text to SoundFont file
34 - gusload GUS PAT file loader
35 - sfxtest Example program to control AWE driver
36
37 The package includes the correction of SoundFont managing routines,
38 called AWElib. As default, the AWElib is *NOT* installed.
39 For installing it, modify awelib/Makefile.am.
40
41 ----------------------------------------------------------------
42 * SFXLOAD and ASFXLOAD
43
44 SFXLOAD and ASFXLOAD are utility program sto transfer the sound wave
45 and instruments data in a SoundFont file to the AWE32 sound driver,
46 or to the Emux WaveTable of ALSA sbawe and emu10k1 drivers.
47 This program is necessary for playing MIDI samples via sequencer
48 programs supporting AWE driver. There is no big difference between
49 sfxload and asfxload except for that asfxload is for ALSA and sfxload
50 is for OSS, respecitvely. The options to specify devices are
51 different between them.
52
53 Basically, sfxload behaves as two ways.
54
55 % sfxload fontfile
56 % sfxload -b1 fontfile
57
58 The first usage is to read SF2 (or SBK) file and transfer to the awe
59 driver. In this case, the samples which were loaded on the driver are
60 replaced with the new one.
61 In the second case, sfxload reads the file and appends it to the
62 pre-loaded samples on the driver with specified bank number. The old
63 samples remain in the driver. The additional samples can be cleared
64 via -x option (see below).
65
66 The sound files are searched through the path list. The path list is
67 defined as built-in. If the environment variable SFBANKDIR or the
68 command line option -P is given, it replaces the default search list.
69 The file extension .sf2, and .sbk can be abbreviated.
70
71 The new sfxload can deal with a virtual bank file. It contains
72 a list of presets from various soundfonts. See the virtual bank file
73 section for more details.
74
75
76 OPTIONS:
77
78 -i, --clear[=bool]
79 Remove all samples before loading the fonts.
80 This is an explicit directive (see -b option).
81 If this option is specified alone without soundfont file
82 arguments, sfxload does onlay remove samples.
83 Either of "on", "off", "yes", "no", "true", or "false" can be
84 specified as an optional argument.
85
86 -x, --remove[=bool]
87 Remove the optional samples previouly loaded via -b option.
88 Otherwise, all new samples are simply appended.
89
90 -N, --increment[=bool]
91 Do not clear samples even with the absence of -b option.
92 However, this option is not exclusive with -x option. If both
93 options are specified, and the memory full error is
94 encountered during loading fonts, sfxload will try to remove
95 samples and load the fonts again.
96
97 -b, --bank=number
98 Append the sound samples on the specified bank.
99 Without this option, all present samples in the driver are
100 removed before loading the new fonts unless -N option is
101 specified. Usually, this option is necessary to load user
102 bank, typically in bank one.
103
104 eg)
105 % sfxload synthgm.sbk
106 % sfxload -b1 surprise.sf2
107
108 -l, --lock[=bool]
109 Lock the font. The locked font is no longer removed via
110 remove option (-x) even if it's loaded together with -b
111 option.
112
113 -C, --compat[=bool]
114 Use the old (v0.4.2) parameter calculations.
115
116 -A, --sense=sensitivity
117 -a, --atten=attenuation
118 (Only valid on compatible mode)
119
120 These options are used to control the attenuation of samples.
121 The former defines the sensitivity of initial attenuation
122 parameter of each instrument in SoundFont file. In the
123 program, the actual attenuaton is calculated from the divided
124 value by this sensitivity from the original parameter. Then,
125 1.0 means to use the original parameter without modification.
126 Generally, smaller number makes drum sounds louder. The
127 default value is 10. (I think -A 2 would be similar to
128 Windows sounds.)
129
130 The latter option defines the minimum attenuation. The value
131 is given in the raw parameter for AWE driver, that is, in 8/3
132 dB unit. The default value is 32. Note that since -A option
133 will change the minimum attenuation automatically, the option
134 -a must be speicifed later from -A option.
135
136 -d, --decay=scale
137 (Only valid on compatible mode)
138
139 Set the scale of envelope decay time. Default value is 50.0.
140 Sounds decay fast when larger number is set.
141
142 The ver.0.3 sfxload uses 54.8. If you want to keep the same
143 sound, use this number instead.
144
145 -B, --addblank[=bool]
146 Add 48 size of blank loop on each sample data. Usually, this
147 option is not necessary. Most of soundfont files are designed
148 well for enough blank loops for each sample.
149
150 -M, --memory[=0|1]
151 Display the left memory size of DRAM on the AWE32 card.
152
153 -c, --chorus=percent
154 -r, --reverb=percent
155 Specify the effects of chorus and reverb, respectively. The
156 value is in percent, from 0 to 100. The default is
157 unspecified.
158 Note: these values may be overwritten by MIDI control
159 messages.
160
161 -L, --extract=source[:map]
162 Extract and load only the specified preset(s).
163 This option is usually employed by drvmidi.
164 The preset is given as same as in virtual bank file.
165
166 -v, --verbose[=level]
167 Increase or set the verbosity level.
168
169 -q, --quiet
170 Don't print error messages, equivalent with --verbose=0.
171
172 -V, --volume=percent
173 Set the total volume of sounds, provided in percent.
174 Default volume is 70%.
175
176 -P, --path=path1:path2:...
177 Specify the search path for sound files. It overrides both
178 the system path and environment variable SFBANKDIR.
179
180 -d, --device=file
181 Specify the device file name. As default, /dev/sequencer
182 is used.
183
184 VIRTUAL BANK FILE:
185
186 The virtual bank file is a list of presets treated as one soundfont
187 file. The syntax of virtual bank is as follows:
188
189 # comments
190 source:map[:soundfont [preset-name]
191 source:map[:soundfont [preset-name]
192 ...
193
194 The first and second items are the source and mapped presets,
195 respectively. The former is the existing preset in the soundfont,
196 and the latter is the actual preset loaded on the sound driver.
197 The preset is described by the following three values,
198
199 preset/bank/keynote
200
201 If bank and keynote are omitted, bank 0 and keynote -1 (meaning to
202 search all keys) are applied.
203
204 The third item is the name of soundfont file. The file is searched
205 from the prescribed search-path. The remaining arguments are
206 ignored in sfxload.
207
208 If the soundfont name is omitted, sfxload loads them as preset
209 mapping. It just behaves like a symbolic link of file opposing to
210 copying of the file. Any sample data is not referred at this time,
211 but searched first when the note is played.
212
213 A couple of special commands can be used together with the virtual
214 presets above. "default" command is used to specify the default
215 soundfont file. Any other presets which are not defined in the
216 virtual preset lists are loaded from this default font. For
217 example, in the following virtual bank, 2mbgmgs.sf2 is used except
218 for standard drumsets which employs drum.sf2:
219
220 0/128:0/128:drum.sf2
221 default 2mbgmgs.sf2
222
223 Another special command is "include" command. This simply includes
224 another virtual bank file under the current position.
225 For example,
226
227 default standard.sf2
228 0/128:0/128:drum.sf2
229 include xgsfx.bnk
230
231
232 SYSTEM RESOURCE FILE:
233
234 You can set default option arguments in the system resource file.
235 There're two files loaded as default.
236
237 $HOME/.sfxloadrc
238 /etc/sfxloadrc
239
240 The syntax is as follows:
241
242 fontname options..
243
244 The first argument is soundfont file name for each option. The
245 remaining arguments are identical with command line options.
246 The font name "default" is used for default options for all sound
247 fonts. The default options are overridden by specific options or
248 command line options.
249
250 For example, to set default chorus level 20 except for synthgm font,
251 you can write a resource file ~/.sfxloadrc like that:
252
253 default --chorus=20
254 synthgm --chorus=0
255
256
257 ENVIRONMENT:
258
259 SFBANKDIR
260 Search path for sound files. The current directory is always
261 searched at first.
262
263
264 ----------------------------------------------------------------
265 * AWESET
266
267 AWESET sets many controll parameters on AWE driver.
268 Most of the parameters can be controlled directly from drvmidi
269 MIDI sequencer. This program is useful to control the parameters
270 for other non-AWE-specific programs.
271
272 The control parameters are given either by command line or a file.
273
274 % aweset newvolume on
275 % aweset n 1
276 % aweset -f new-config
277
278 In the first case, aweset enables a boolean parameter "newvolume".
279 The second case is identical with the first case, but using an
280 abbreviated command.
281 In the last case, aweset reads a file "new-config" and parses the
282 contents. The file must contain the commands like command line
283 arguments as former cases.
284
285 The available commands are as follows:
286
287 command(abbrev) data type description
288
289 - exclusive(e) bool exclusive note mode (default: on)
290 - realpan(p) bool real-time panning change (default: on)
291 - gusbank(g) int GUS-instrument bank number (default: 0)
292 - keepeffect(k) bool keep effect controls after clearing voices (def:off)
293 - zeroatten(z) int zero attenuation level (default: 32 - depends on sfxload)
294 - chnprior(C) bool channel priority mode (default: off)
295 - modsense(m) int modulation wheel sensitivity (default: 18)
296 - defpreset(P) int default search preset number (default: 0)
297 - defbank(B) int default search bank number (default: 0)
298 - defdrum(D) int default search drumset number (default: 0)
299 - toggledrum(a) bool accept to change bank of drum channels (def: off)
300 - newvolume(n) bool Windows/DOS-like volume calculation mode (def: on)
301 - chorus(c) [0-7] chorus mode (default: 2)
302 - reverb(r) [0-7] reverb mode (default: 4)
303 - bass(b) [0-11] equalizer bass level (default: 5)
304 - treble(t) [0-11] equalizer treble level (default: 9)
305 - debug(d) int debug mode (default: 0)
306 - panexchange(x) bool exchange panning direction (left<->right) (def:off)
307
308
309 ----------------------------------------------------------------
310 * SETFX
311
312 SETFX reads a configuration file and downloads the user defined
313 chorus/reverb effect parameters on the sound driver.
314
315 % setfx test.cfg
316
317 The format of configuration file is as follows:
318
319 type:mode:name:include:parameters..
320
321 type
322 this specifies either "chorus" or "reverb".
323 mode
324 the mode index in integer value from 8 to 31.
325 name
326 the name of this effect in any string (except colon)
327 include
328 include from the pre-defined mode. This is valid only on
329 reverb definition. If this index is specified, the
330 parameter lists become "pos=value pos=value.." where 'pos'
331 is a position of the parameter (from 0 to 27) and 'value'
332 is the new replaced value.
333 parameters
334 effect parameters. All values are written in hex code.
335 In chorus mode, this contains five values, while in reverb
336 mode, 28 values must be listed.
337
338 The configuratoin file is searched according to the pre-defined
339 soundfont path search list.
340
341
342 ----------------------------------------------------------------
343 * SF2TEXT
344
345 Sf2text converts the specified SoundFont file to the text file which
346 is editable easily. Both SBK and SF2 formats can be converted.
347
348 % sf2text sample.sf2 sample.txt
349
350 The converted text file contains five categories.
351
352 1. major and minor versions
353 2. sample data position and size
354 3. preset information
355 4. instrument information
356 5. sample data information
357
358 The present sf2text program employes an S-expression list.
359 This text file can be converted to SoundFont format again via
360 text2sf utility program below.
361
362
363 ----------------------------------------------------------------
364 * TEXT2SF
365
366 Text2sf works as an opposite convertor from text file to SoundFont
367 format file. It reads an S-expression list and write it on the new
368 SoundFont file.
369
370 % text2sf sample.txt sample.sf2 new.sf2
371
372 The second argument is the original SoundFont file, and the last
373 is the new SoundFont file. The original file is necessary to
374 duplicate INFO list and wave samples to the new file.
375
376
377 ----------------------------------------------------------------
378 * GUSLOAD
379
380 Gusload is a tool to load a GUS compatible patch file to AWE32 driver.
381
382 % gusload [-i] [-v] [-b bank] [-p preset] [-k keynote] GUSfile
383
384 The voices are loaded as a preset with the prescribed instrument
385 number in each patch unless -p option is specified.
386 The bank number is also changed by -b option.
387 The option -k is used to specify the fixed key note for the patch.
388
389 eg)
390 % gusload -b 0 -p 53 doo.pat
391
392 The option -i is identical with sfxload. All the samples will be
393 cleared before loading.
394
395
396 ----------------------------------------------------------------
397 * SFXTEST
398
399 Sfxtest is a sample program to control awe sound driver.
400
401 % sfxtest commands ...
402
403 For example, to play a trumpet voice (preset 56) on key middle C (60)
404 for two seconds in channel access mode, execute as follows:
405
406 % sfxtest X p 56 n 60 127 t 200 K 60
407
408 You can see the debug message of the awe driver by setting debug
409 mode.
410
411 % sfxtest X D 9 p 47 n 62 100 t 150 K 47 D 0
412
413 Multiple channels can be used at the same time.
414
415 % sfxtest X x 0 p 0 n 60 127 x 1 p 5 n 72 110 t 150 x 0 K 60 x 1 K 72
416
417
418 ----------------------------------------------------------------
419 * ACKNOWLEDGMENTS
420
421 Thanks to Mark Weaver who revealed and offered ADIP compatible
422 parameter calculations.
423
424
425 ----------------------------------------------------------------
426 * COPYRIGHT
427
428 Copyright (C) 1996-2003 by Takashi Iwai
429
430 These programs are free software; you can redistribute them and/or
431 modify them under the terms of the GNU General Public License as
432 published by the Free Software Foundation; either version 2 of the
433 License, or (at your option) any later version.
434
435 These programs are distributed in the hope that they will be useful,
436 but WITHOUT ANY WARRANTY; without even the implied warranty of
437 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
438 GNU General Public License for more details.
439
440 You should have received a copy of the GNU General Public License
441 along with this program; if not, write to the Free Software
442 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.