================================================================
    AWE32 Sound Driver Utility Programs for Linux / FreeBSD
		version 0.5.1

		Takashi Iwai <[email protected]>
================================================================

----------------------------------------------------------------
* GENERAL NOTES

Thie package includes several utilities for AWE32 sound driver on
Linux and FreeBSD systems and for Emux WaveTable of ALSA sbawe and
emu10k1 drivers.  You need to use these utilities to enable sounds on
these drivers properly.

The package is managed with GNU auto-tools since version 0.5.0.
The ALSA support (asfxload) is added also in this version.

Ver.0.4.3 improves the parameter calculation as almost compatible with
the DOS/Win drivers.  This is more effective in the case of ROM sounds.
If you prefer the old type sounds, use --compatible option.

This packaing contains the following programs:

for ALSA
 - asfxload	SoundFont file loader

for OSS
 - sfxload	SoundFont file loader
 - setfx	Chorus/reverb effect loader
 - aweset	Change the running mode of AWE driver
 - sf2text	Convert SoundFont to readable text
 - text2sf	Revert from text to SoundFont file
 - gusload	GUS PAT file loader
 - sfxtest	Example program to control AWE driver

The package includes the correction of SoundFont managing routines,
called AWElib.  As default, the AWElib is *NOT* installed.
For installing it, modify awelib/Makefile.am.

----------------------------------------------------------------
* SFXLOAD and ASFXLOAD

SFXLOAD and ASFXLOAD are utility program sto transfer the sound wave
and instruments data in a SoundFont file to the AWE32 sound driver,
or to the Emux WaveTable of ALSA sbawe and emu10k1 drivers.
This program is necessary for playing MIDI samples via sequencer
programs supporting AWE driver.  There is no big difference between
sfxload and asfxload except for that asfxload is for ALSA and sfxload
is for OSS, respecitvely.  The options to specify devices are
different between them.

Basically, sfxload behaves as two ways.

	% sfxload fontfile
	% sfxload -b1 fontfile

The first usage is to read SF2 (or SBK) file and transfer to the awe
driver.  In this case, the samples which were loaded on the driver are
replaced with the new one.
In the second case, sfxload reads the file and appends it to the
pre-loaded samples on the driver with specified bank number.  The old
samples remain in the driver.  The additional samples can be cleared
via -x option (see below).

The sound files are searched through the path list.  The path list is
defined as built-in.  If the environment variable SFBANKDIR or the
command line option -P is given, it replaces the default search list.
The file extension .sf2, and .sbk can be abbreviated.

The new sfxload can deal with a virtual bank file.  It contains
a list of presets from various soundfonts.  See the virtual bank file
section for more details.


OPTIONS:

  -i, --clear[=bool]
	Remove all samples before loading the fonts.
	This is an explicit directive (see -b option).
	If this option is specified alone without soundfont file
	arguments, sfxload does onlay remove samples.
	Either of "on", "off", "yes", "no", "true", or "false" can be
	specified as an optional argument.
	
  -x, --remove[=bool]
  	Remove the optional samples previouly loaded via -b option.
	Otherwise, all new samples are simply appended.

  -N, --increment[=bool]
	Do not clear samples even with the absence of -b option.
	However, this option is not exclusive with -x option.  If both 
	options are specified, and the memory full error is
	encountered during loading fonts, sfxload will try to remove
	samples and load the fonts again.

  -b, --bank=number
	Append the sound samples on the specified bank.
	Without this option, all present samples in the driver are
	removed before loading the new fonts unless -N option is
	specified.  Usually, this option is necessary to load user
	bank, typically in bank one.

	eg)
		% sfxload synthgm.sbk
		% sfxload -b1 surprise.sf2

  -l, --lock[=bool]
	Lock the font.  The locked font is no longer removed via
	remove option (-x) even if it's loaded together with -b
	option.

  -C, --compat[=bool]
	Use the old (v0.4.2) parameter calculations.
	
  -A, --sense=sensitivity
  -a, --atten=attenuation
	(Only valid on compatible mode)

	These options are used to control the attenuation of samples.
	The former defines the sensitivity of initial attenuation 
	parameter of each instrument in SoundFont file.  In the
	program, the actual attenuaton is calculated from the divided
	value by this sensitivity from the original parameter.  Then,
	1.0 means to use the original parameter without modification.
	Generally, smaller number makes drum sounds louder.  The
	default value is 10.  (I think -A 2 would be similar to
	Windows sounds.)

	The latter option defines the minimum attenuation.  The value
	is given in the raw parameter for AWE driver, that is, in 8/3
	dB unit.  The default value is 32.  Note that since -A option
	will change the minimum attenuation automatically, the option
	-a must be speicifed later from -A option.

  -d, --decay=scale
	(Only valid on compatible mode)

	Set the scale of envelope decay time.  Default value is 50.0.
	Sounds decay fast when larger number is set.

	The ver.0.3 sfxload uses 54.8.  If you want to keep the same
	sound, use this number instead.

  -B, --addblank[=bool]
	Add 48 size of blank loop on each sample data.  Usually, this
	option is not necessary.  Most of soundfont files are designed 
	well for enough blank loops for each sample.

  -M, --memory[=0|1]
	Display the left memory size of DRAM on the AWE32 card.

  -c, --chorus=percent
  -r, --reverb=percent
	Specify the effects of chorus and reverb, respectively.  The
	value is in percent, from 0 to 100.  The default is
	unspecified.
	Note: these values may be overwritten by MIDI control
	messages. 

  -L, --extract=source[:map]
	Extract and load only the specified preset(s).
	This option is usually employed by drvmidi.
	The preset is given as same as in virtual bank file.

  -v, --verbose[=level]
	Increase or set the verbosity level.

  -q, --quiet
	Don't print error messages, equivalent with --verbose=0.

  -V, --volume=percent
	Set the total volume of sounds, provided in percent.
	Default volume is 70%.

  -P, --path=path1:path2:...
	Specify the search path for sound files.  It overrides both
	the system path and environment variable SFBANKDIR.

  -d, --device=file
	Specify the device file name.  As default, /dev/sequencer
	is used.

VIRTUAL BANK FILE:

  The virtual bank file is a list of presets treated as one soundfont
  file.  The syntax of virtual bank is as follows:

	# comments
	source:map[:soundfont [preset-name]
	source:map[:soundfont [preset-name]
	...

  The first and second items are the source and mapped presets,
  respectively.  The former is the existing preset in the soundfont,
  and the latter is the actual preset loaded on the sound driver.
  The preset is described by the following three values,

	preset/bank/keynote

  If bank and keynote are omitted, bank 0 and keynote -1 (meaning to
  search all keys) are applied.

  The third item is the name of soundfont file.  The file is searched
  from the prescribed search-path.  The remaining arguments are
  ignored in sfxload.

  If the soundfont name is omitted, sfxload loads them as preset
  mapping.  It just behaves like a symbolic link of file opposing to
  copying of the file.  Any sample data is not referred at this time,
  but searched first when the note is played.

  A couple of special commands can be used together with the virtual
  presets above.  "default" command is used to specify the default
  soundfont file.  Any other presets which are not defined in the
  virtual preset lists are loaded from this default font.  For
  example, in the following virtual bank, 2mbgmgs.sf2 is used except
  for standard drumsets which employs drum.sf2:
 
	0/128:0/128:drum.sf2
	default 2mbgmgs.sf2

  Another special command is "include" command.  This simply includes
  another virtual bank file under the current position.
  For example,

	default standard.sf2
	0/128:0/128:drum.sf2
	include xgsfx.bnk


SYSTEM RESOURCE FILE:

  You can set default option arguments in the system resource file.
  There're two files loaded as default.

	$HOME/.sfxloadrc
	/etc/sfxloadrc

  The syntax is as follows:

	fontname options..

  The first argument is soundfont file name for each option.  The
  remaining arguments are identical with command line options.
  The font name "default" is used for default options for all sound
  fonts.  The default options are overridden by specific options or
  command line options.

  For example, to set default chorus level 20 except for synthgm font,
  you can write a resource file ~/.sfxloadrc like that:

	default	--chorus=20
	synthgm --chorus=0


ENVIRONMENT:

  SFBANKDIR
	Search path for sound files.  The current directory is always
	searched at first.
	

----------------------------------------------------------------
* AWESET

AWESET sets many controll parameters on AWE driver.
Most of the parameters can be controlled directly from drvmidi
MIDI sequencer.  This program is useful to control the parameters
for other non-AWE-specific programs.

The control parameters are given either by command line or a file.

	% aweset newvolume on
	% aweset n 1
	% aweset -f new-config

In the first case, aweset enables a boolean parameter "newvolume".
The second case is identical with the first case, but using an
abbreviated command.
In the last case, aweset reads a file "new-config" and parses the
contents.  The file must contain the commands like command line
arguments as former cases.

The available commands are as follows:

command(abbrev)	data type	description

- exclusive(e)	bool	exclusive note mode (default: on)
- realpan(p)	bool	real-time panning change (default: on)
- gusbank(g)	int	GUS-instrument bank number (default: 0)
- keepeffect(k)	bool	keep effect controls after clearing voices (def:off)
- zeroatten(z)	int	zero attenuation level (default: 32 - depends on sfxload)
- chnprior(C)	bool	channel priority mode (default: off)
- modsense(m)	int	modulation wheel sensitivity (default: 18)
- defpreset(P)	int	default search preset number (default: 0)
- defbank(B)	int	default search bank number (default: 0)
- defdrum(D)	int	default search drumset number (default: 0)
- toggledrum(a)	bool	accept to change bank of drum channels (def: off)
- newvolume(n)	bool	Windows/DOS-like volume calculation mode (def: on)
- chorus(c)	[0-7]	chorus mode (default: 2)
- reverb(r)	[0-7]	reverb mode (default: 4)
- bass(b)	[0-11]	equalizer bass level (default: 5)
- treble(t)	[0-11]	equalizer treble level (default: 9)
- debug(d)	int	debug mode (default: 0)
- panexchange(x) bool	exchange panning direction (left<->right) (def:off)


----------------------------------------------------------------
* SETFX

SETFX reads a configuration file and downloads the user defined
chorus/reverb effect parameters on the sound driver.

	% setfx test.cfg

The format of configuration file is as follows:

	type:mode:name:include:parameters..

	type
	    this specifies either "chorus" or "reverb".
	mode
	    the mode index in integer value from 8 to 31.
	name
	    the name of this effect in any string (except colon)
	include
	    include from the pre-defined mode.  This is valid only on
	    reverb definition.  If this index is specified, the
	    parameter lists become "pos=value pos=value.." where 'pos'
	    is a position of the parameter (from 0 to 27) and 'value'
	    is the new replaced value.
	parameters
	    effect parameters.  All values are written in hex code.  
	    In chorus mode, this contains five values, while in reverb
	    mode, 28 values must be listed.

The configuratoin file is searched according to the pre-defined
soundfont path search list.


----------------------------------------------------------------
* SF2TEXT

Sf2text converts the specified SoundFont file to the text file which
is editable easily.  Both SBK and SF2 formats can be converted. 

	% sf2text sample.sf2 sample.txt

The converted text file contains five categories.

1. major and minor versions
2. sample data position and size
3. preset information
4. instrument information
5. sample data information

The present sf2text program employes an S-expression list.
This text file can be converted to SoundFont format again via
text2sf utility program below.


----------------------------------------------------------------
* TEXT2SF

Text2sf works as an opposite convertor from text file to SoundFont
format file.  It reads an S-expression list and write it on the new
SoundFont file.

	% text2sf sample.txt sample.sf2 new.sf2

The second argument is the original SoundFont file, and the last
is the new SoundFont file.  The original file is necessary to
duplicate INFO list and wave samples to the new file.


----------------------------------------------------------------
* GUSLOAD

Gusload is a tool to load a GUS compatible patch file to AWE32 driver.

	% gusload [-i] [-v] [-b bank] [-p preset] [-k keynote] GUSfile

The voices are loaded as a preset with the prescribed instrument
number in each patch unless -p option is specified.
The bank number is also changed by -b option.
The option -k is used to specify the fixed key note for the patch.

eg)
	% gusload -b 0 -p 53 doo.pat

The option -i is identical with sfxload.  All the samples will be
cleared before loading.


----------------------------------------------------------------
* SFXTEST

Sfxtest is a sample program to control awe sound driver.

	% sfxtest commands ...

For example, to play a trumpet voice (preset 56) on key middle C (60)
for two seconds in channel access mode, execute as follows:

	% sfxtest X p 56 n 60 127 t 200 K 60

You can see the debug message of the awe driver by setting debug
mode.

	% sfxtest X D 9 p 47 n 62 100 t 150 K 47 D 0

Multiple channels can be used at the same time.

	% 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


----------------------------------------------------------------
* ACKNOWLEDGMENTS

Thanks to Mark Weaver who revealed and offered ADIP compatible
parameter calculations.


----------------------------------------------------------------
* COPYRIGHT

Copyright (C) 1996-2003 by Takashi Iwai

These programs are free software; you can redistribute them and/or
modify them 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.

These programs are distributed in the hope that they 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.