sfxload.1

.TH sfxload 1 "January 22, 2003"
.LO 1
.SH NAME
sfxload, asfxload \- load a SoundFont file on the Emux WaveTable

.SH SYNOPSIS
.B sfxload
.RI [\| \-options \|] " fontfile"

.B asfxload
.RI [\| \-options \|] " fontfile"

.SH DESCRIPTION
.B sfxload
and
.B 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
\fBsfxload\fP and \fBasfxload\fP except for that \fBasfxload\fP is for
ALSA and \fBsfxload\fP is for OSS, respecitvely. The options to specify
devices are
different between them (see below).

Basically, sfxload behaves as two ways.
.in +1i
% sfxload fontfile
.br
% sfxload \-b1 fontfile
.in -1i

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 \fB\-x\fP option (see below).

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

.SH OPTIONS
.TP
.BI \-F,\ \-\-device= file " \fR(sfxload only)\fP"
Specify the device file to be used.
Default value is
.IR /dev/sequencer .
.TP
.BI \-D,\ \-\-index= number " \fR(sfxload only)\fP"
Specify the device index of AWE driver.
Negative number (e.g. \-1) means to probe the first AWE device automatically.
For selecting the other AWE cards, a positive index number must be given here.
Default value is \fB\-1\fP.
.TP
.BI \-D,\ \-\-hwdep= name " \fR(asfxload only)\fP"
Specify the hwdep name to be used.
As default, asfxload seeks until any Emux compatible hwdep device is found.
.TP
.BI \-i,\ \-\-clear "\fR[=\fPbool\fR]\fP"
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 \fBon\fP, \fBoff\fP, \fByes\fP, \fBno\fP, \fBtrue\fP,
or \fBfalse\fP can be specified as an optional argument.
.TP
.BI \-x,\ \-\-remove "\fR[=\fPbool\fR]\fP"
Remove the optional samples previouly loaded via \fB\-b\fP option.
Otherwise, all new samples are simply appended.
.TP	
.BI \-N,\ \-\-increment "\fR[=\fPbool\fR]\fP"
Do not clear samples even with the absence of \fB\-b\fP option.  However, this option is not exclusive with
.B \-x
option. If both options are specified, and the memory full error is
encountered during loading fonts, \fBsfxload\fP will try to remove
samples and load the fonts again.
.TP
.BI \-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 \fB\-N\fP option is specified. Usually, this option is necessary to load user
bank, typically in bank one.
For example,
.in +1i
% sfxload synthgm.sbk
.br
% sfxload -b1 surprise.sf2
.br
.in -1i
.TP
.BI \-l,\ \-\-lock "\fR[=\fPbool\fR]\fP"
Lock the font.  The locked font is no longer removed via
remove option (\fB\-x\fP) even if it's loaded together with \fB\-b\fP option.
.TP
.BI \-C,\ \-\-compat "\fR[=\fPbool\fR]\fP"
Use the old (v0.4.2) parameter calculations.
.TP
.BI \-A,\ \-\-sense= sensitivity
(Only valid on compatible mode)
.br
Set sample attenuation sensitivity.
This option controls the sensitivity of initial attenuation parameter
of each instrument defined in SoundFont file.
In the program, each parameter is calculated from the value divided
by this number for the original value.
The number \fI1.0\fP means that the original initial attenuation parameters
would be used.
Generally, smaller number makes drum sounds louder.
(I think \fB"-A 2"\fP would be similar to Windows sounds.)
The default value is \fI10\fP.
Note that this option changes also the default attenuation automatically (see below).
.TP
.BI \-a,\ \-\-atten= attenuation
(Only valid on compatible mode)
.br
Set the default attenuation level.
This option controls the minimum attenuation of the sample.
The parameter is given in raw digit number for AWE driver,
that is, in 8/3 dB unit.
Since \fB\-\-sense\fP option changes the default attenuation automatically,
specify this option later from \fB\-\-sense\fP option.
The default value is \fI32\fP.
.TP
.BI \-d,\ \-\-decay= scale
(Only valid on compatible mode)
.br
Set the scale of envelope decay time.  Default value is \fI50.0\fP.
Sounds decay fast when larger number is set.
The ver.0.3 sfxload uses \fI54.8\fP.  If you want to keep the same
sound, use this number instead.
.TP
.BI \-M,\ \-\-memory "\fR[=\fPbool\fR]\fP"
Display the left memory size in DRAM on the AWE32 card.
.TP
.BI \-c,\ \-\-chorus= percent
Specify the effects of chorus.
The value is in percent, from 0 to 100.  The default is unspecified.
This value may be overwritten by MIDI control messages.
.TP
.BI \-r,\ \-\-reverb= percent
Specify the effects of reverb.
The value is in percent, from 0 to 100.  The default is unspecified.
This value may be overwritten by MIDI control messages.
.TP
.BI \-B,\ \-\-addblank "\fR[=\fPbool\fR]\fP"
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.
.TP
.BI \-L,\ \-\-extract= source \fR[:\fP map \fR]\fP
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.
.TP
.BI \-v,\ \-\-verbose "\fR[=\fPlevel\fR]\fP"
Increase or set the verbosity level.
.TP
.BI \-q,\ \-\-quiet
Don't show error messages, equivalen with \-\-verbose=0.
.TP
.BI \-V,\ \-\-volume= percent
Specify the total volume of sounds, provided in percent.
The default volume is \fI70%\fP.
.TP
.BI \-P,\ \-\-path= path1 : path2 : pathN
Specify the search path list.
The sound files are searched from
\fIpath1\fP, \fIpath2\fP, and so on.
This overrides both the system path and environment variable
\fBSFBANKDIR\fP.

.SH "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:
.in +1i
	# comments
.br
	source:map[:soundfont [preset-name]
.br
	source:map[:soundfont [preset-name]
.br
	...
.in -1i

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,
.in +1i
	preset/bank/keynote
.in -1i
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 \fBsfxload\fP.

If the soundfont name is omitted, sfxload loads it 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.
\fBdefault\fP
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, \fI2mbgmgs.sf2\fP is used except
for standard drumsets which employs \fIdrum.sf2\fP:
.in +1i 
	0/128:0/128:drum.sf2
.br
	default 2mbgmgs.sf2
.in -1i

Another special command is
\fBinclude\fP
command.  This simply includes
another virtual bank file under the current position. For example,
.in +1i
	default standard.sf2
.br
	0/128:0/128:drum.sf2
.br
	include xgsfx.bnk
.in -1i

.SH "SYSTEM RESROUCE FILE"

The default option arguments can be stored in the system resource file.
There are two files loaded as default.
.in +1i
.I $HOME/.sfxloadrc
.br
.I /etc/sfxloadrc
.in -1i

The syntax is as follows:
.in +1i
fontname \-options..
.in -1i
The first argument is soundfont file name for each option.
The remaining arguments are identical with command line options.
The font name
\fIdefault\fP
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 \fI~/.sfxloadrc\fP like that:
.in +1i
default	\-\-chorus=20
.br
synthgm \-\-chorus=0
.in -1i


.SH ENVIRONMENT
.TP
.B SFBANKDIR
Search path for sound files.  The current directory is always searched
at first.

.SH "SEE ALSO"
.BR drvmidi (1)

.SH COPYRIGHT
Copyright (C) 1996-2003 Takashi Iwai.
.P
The AWE32 driver and utilties are free software; you can redistribute them
and/or modify them under the terms of the \fIGNU General Public
License\fP as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.