================================================================
	AWE32 MIDI Player for Linux / FreeBSD
		version 0.4.3c; Jan. 16, 2000

	Takashi Iwai	<iwai@ww.uni-erlangen.de>
================================================================

* GENERAL NOTES

This is a midi player program which supports AWE32 sound driver v0.4.3
by Takashi Iwai.  Before using this program, you have to load sound
samples onto the driver.  Please read the document in utility package
awesfx-0.4.3b.tar.gz.  All AWE32 driver and utilities can be downloaded
from:
	http://members.tripod.de/iwai/awedrv.html


* USAGE

	drvmidi [options] midifile[.gz] ...

You can give the compressed or gzipped files on command line.
These files are expanded automatically inside the program.
The drvmidi accepts not only normal MIDI files, but also RIFF combined
MIDI files and CMF files.

If drvmidi finds a file which has the same file name with the
extension ".id", drvmidi reads this file as an option file.  You can
specify its own settings without the command line options.  See
"option file format" section for the syntax of the option file.  The 
option file is editable via File/Edit Options menu in tkmidi.

The drvmidi can emulate XG MIDI with GS soundfont samples.  You need
to load XG SFX and drum maps for this emulation together with --xgmap
option to play properly XG sounds.


* CONTROL PROGRAMS

- Tkmidi

Tkmidi provides an external control to drvmidi in Tcl/Tk window.
This works just as Tcl/Tk interface of drvmidi except tkmidi uses
the general pipe interface to communicate with drvmidi.
All the long command line options starting double minus (--) are
passed to drvmidi, but short options are unavailable.

Tkmidi accepts the directory as command line arguments.  It search the
files with .mid extension under the directory, and add them to the
file list.  For example, to play all midi files under the current
directory, you can start tkmidi as follows:

	% tkmidi .


- Atmidi

Atmidi is another external control program which employs Athena Widget 
sets.  This is an example program, and supports only limited
functions.


* TKMIDI AND TCL/TK INTERFACE MENUES

    - File Menu
	Open File: open a MIDI file from the file selection window.
	    Not available during play midi files.
    	Clear List: clear all MIDI songs selected in the list.
	    Not available during play midi files.
	Save Config: save the current configuration in user config
	    file ~/.tkawe.  The play style, display style, volume
	    parameters, chorus/reverb modes are saved.  This file is
	    read when starting drvmidi.
	Edit Options: edit option files in the selection list, or the
	    system default options.  A file selection dialog appear
	    when this menu is selected, then choose a midi file from
	    the file list.  Most of playing options can be set via
	    option editor window.  If the corresponding midi option
	    file doesn't exist, a new option file is created, which
	    name starts from period and has ".id" extension.  For
	    example, when "foo.mid" is edited, an option file
	    ".foo.id" will be created on the current directory.  The
	    system default option can be editted by selecting "Edit
	    Default" in file selection dialog.  The options are saved
	    on the system resource file, ~/.drvmidirc.

    - Mode Menu
	Repeat: play the first file again repeatedly after all files
	    are played. 
	Shuffle: shuffle play mode.  The order of the playing files is
	    shuffled and selected randomly.
	Auto Start: start playing midi files automatically when the
	    program runs. 
	Auto Exit: exit the program automatically when finishing all
	    the files. 
	Confirm Quit: pop up a dialog to confirm when the program is
	    going to quit. 

    - Display Menu
	This menu contains six toggle button items, File List, Time,
	Messages, Volume, Buttons, and Trace.  Each item selects to
	display or remove the corresponding window.  The current
	display style can be saved by "Save Config".

	File List: File list window displays all the MIDI files.
	    You can start or change the file currently playing by
	    clicking the file name in it.
	Time: Time window displays the current time and total time,
	    and a scale bar.  You can control the current time
	    directly by dragging the thumb in the scale bar. 
	Messages: Message window displays messages in the MIDI file.
	    To clear the window, push "clear" button under the message
	    window. 
	Volume: Volume window controls total and equalizer volumes.
	    The total volume can be changed by dragging the upper
	    scale bar from 0 to 200%.  Other two lower scale bars
	    control bass and treble volumes.  The volume status will
	    be saved by "Save Config" in File menu. 
	Buttons: Button window displays operational buttons to play,
	    stop, previous, backward, pause, forward, next, and quit.
	    Each button will be activated or disabled according the
	    playing status.
	Trace: Trace window dnisplay volume bars of each MIDI
	    channel.  The red bar means the drum channel, and green
	    bar means the normal one.  The yellow arrows under volume
	    bars indicate the panning positions, and the lower numbers
	    indicate the preset number in hex. 

    - Chorus & Reverb Menues:
	Change the current chorus and reverb modes immediately.
	These modes may be changed according to MIDI sysex messages.
	
    - Key Bindings
	[Return]	play
	[c]		stop
	[Space] [s]	pause / continue
	[q]		quit
	[n]		next song
	[p]		restart or previous song
	[r]		restart
	[Right] 	forward two seconds
	[Left]		backward two seconds
	[Up] [v]	volume up 5%
	[Down] [V]	volume down 5%
	[u]		increase the base key
	[d]		decrease the base key


* NCURSES INTERFACE

     - Key bindings
	[h] [?]	[F1]	display help window
	[Space]		pause / continue
	[q]		quit
	[Up] [V]	volume up 10 %
	[Down] [v]	volume down 10 %
	[n]		next song
	[p]		previous song
	[r]		restart
	[Right] [f]	forward two seconds
	[Left] [b]	backward two seconds
	[c] [C]		change chorus mode
	[e] [E]		change reverb mode
	[u]		increase the base key
	[d]		decrease the base key


* DYNAMIC SOUNDFONT LOADING

The dynamic soundfont loading is helpful for users who have only
limited DRAM on the soundcard.  If the dynamic loading is enabled,
drvmidi loads the specified soundfont or virtual bank file
automatically when it receives each MIDI file.
Since only necessary samples are loaded, the required memory size of
soundcard is reduced.  For example, 2MB GS font can be used on 512KB
RAM in most of MIDI files.

In the case of XG midi file, specify the font file via --xgload
option.  The specified file should contain proper XG mappings, and
GS font file as default font.  Usually, this option should be used
together with --xgmap option.
In other cases, the font file specified in --dynamic option is used as
the dynamic font file.  In both cases, the specified file can be a
soundfont file or a virtual bank file.  The virtual bank file can
define each preset from various soundfont files, and preset mappings.
See the description in awesfx utility for more details.


* OPTIONS

    -i, --interface=type
	Specifies the interface mode. "k" for Tcl/Tk interface, and 
	"d" for dumb interface.  "n" means ncurses interface.
	The default is Tcl/Tk interface.

    -D, --drum=channel
	Used to change drum channels.  If the argument is larger
	than zero, this channel is treated as a drum channel.
	If less than zero, minus of this value is treated as a normal
	channel.
	ex)
		% drvmidi --drum=-10 --drum=16 foo.mid

	    will set channel 10 as a normal channel, and channel 16 as
	    a drum one.
	As default, drvmidi uses only channel 10 (and 26) as drum
	channels.

    --drumflag=val
	Set all drum channels as 32bit flags.  For example, the argument
	0x02008200 will set channel 10, 16, and 26 as drum channels. 

    -c, --chorus=mode
    -r, --reverb=mode
	They supply the chorus and reverb modes.  The AWE32 card
	has eight chorus modes and eight reverb modes as default.
	The chorus/reverb mode specified in this option may be changed
	by sysex control in MIDI file.
	The system default modes are:

	chorus mode
		0: chorus 1
		1: chorus 2
		2: chorus 3
		3: chorus 4
		4: feedback
		5: flanger
		6: short delay
		7: short delay 2
	reverb mode
		0: room 1
		1: room 2
		2: room 3
		3: hall 1
		4: hall 2
		5: plate
		6: delay
		7: panning delay

	The other modes can be defined via setfx utility program.

    --chorusdepth=val
    --reverbdepth=val
	Define the default chorus/reverb depth, respectively.
	The arguments are MIDI control values from 0 to 127.
	These values are not used when chorus and reverb values (CC
	#93 and #91) are defined in each MIDI file.

    -V, --volume=percent
	Set the master volume in percent unit.  Default is 100.

    -S, --volscale=percent
	Set volume scaling factor.  The argument is in percent.
	It still accepts a float number from 0 to 5.0 for
	compatibility with older version.  For example, if a number
	0.8 is given, the MIDI volume will be output in 80% of the
	normal scale.   
	Default factor is 100.

    --bass=val
    --treble=val
	Define the equalizer bass and treble levels of AWE driver,
	respectively.  The value is from 0 (-12 dB) to 11 (+12 dB).

    -O, --acceptall[=bool]
	Toggle to accept or ignore "all notes off" and "all sounds off"
	events.  Some MIDI file contains these events.  Either of
	"on", "off", "yes", "no", "true", or "false" can be specified
	as an optional boolean argument.
	Default is ON.

    -P, --realpan[=bool]
	Toggle to enable or disable realtime panning change.
	Emu8000 chip often causes a click noise when changing the panning
	position in real time during playing a voice.
	Default is ON.

    --multipart[=bool]
	Toggle to enable or disable multi MIDI parts.
	If this option is enabled, the the tracks later than the given
	track number are treates as MIDI part B.
	Note that even if this option is disabled, multi mode is
	activated when GS multi mode sysex is received (see SYSEX
	MACROS section).
	Default is OFF.

    -T, --tracks=num
	Specify the track number of multi part.  For example, to deal
	with tracks from 0 to 16 as part A, and from 17 to 32 as part
	B, specify '--tracks=16'.  The value -1 means to disable multi
	MIDI parts (equivalent with --multipart=off).
	The default value is 16.

    -M, --mt32=mode
	Set MT32 program mode.  The argument must be from 0 to 2.
	When mode is 0, no conversion is done (GM/GS mode).  When 1 is 
	given, bank number 127 is automatically set.  If you have a
	proper MT-32 set, you should specify 1.  Otherwise, when the
	argument is 2, each preset number is converted internally to
	the corresponding GM preset number.
	Default is 0.

    -C, ---samecsec[=bool]
	Toggle to enable or disable the note-off event check.
	The sequencer device can handle events only in 1/100 sec unit,
	so often both the note on and off events occur at the same time.
	To prevent this problem, drvmidi checks the time of each note
	off event, and send it after 1/100 sec later if necessary.
	Default is ON.

    -G, --gsmacro[=bool]
	Toggle to enable or disable GS sysex controls.
	When GS part check is on, drvmidi accepts chorus mode, reverb
	mode, and GS part change messages.
	Default is ON.

    -X, --xgmacro[=bool]
	Toggle to enable or disable XG bank controls.
	Default is ON.

    --xgmap=bool
	Control XG SFX and drum mapping.  If this option is enabled,
	bank #64 and #126 are used for XG SFX sounds.  XG drumsets are
	shifted from #64 to #126 to avoid conflicts with GS sounds.
	To support this mapping, you need to load XG map file on AWE
	drvier.  The --xgload option below is helpful for dynamic
	loading of this map file.

    --xgload=file
	Set the font file to load automatically when drvmidi receives
	a XG midi file.  This just behaves as --dynamic option, but
	invoked only when the MIDI file is XG.
	If "none" is specified as the argument, this function is
	suppressed. 

    -N, --increment[=bool]
	Load the fonts incrementally.  This option enables the sample
	sharing on awedrv-0.4.3, and reduces the loading time.  If
	you're using 12MB fonts on 8MB DRAM, it's better to set this
	option.  If you have 512k DRAM, better to disable this option.
	Default is ON.

    -s, --autoskip[=bool]
	Toggle auto skip mode.  If this option is enabled, drvmidi skips
	to the first note on event immediately after starting.
	Default is OFF.

    --chnprior[=bool]
	Enable or disable MIDI channel proprity mode.
	If this is enabled, the drum channels have the highest priority,
	and the lower channels have higher priority.  A new voice is
	allocated from the channel with lower priority.  This
	mechanism is available only on GS or XG mode.
	Default is OFF.

    -L, --dynamic=fontfile
	Load the specified soundfont file automatically.
	If this option is enabled, drvmidi invokes sfxload program to
	load soundfont (or virtual bank) file on the driver.
	If "none" is specified as the argument, this function is
	suppressed. 

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

    --parsetitle[=bool]
	Enable or disable to display the first text event as a title.
	Default is ON.

    -m, --mode=modifiers
	Set playing mode.  Some modes are valid only on Tcl/Tk
	interface.  The following mode identifiers may be available:

	t	Turn tracing mode on.  It shows realtime bar graph and 
		program number of each channel in the trace window.
	s	Shuffle play mode.  The order of the playing files is
		shuffled and selected randomly.
	n	Normal play mode.  The songs are played in the order
		of specified command line arguments.
	p	Start play automatically.
	q	Exit drvmidi automatically after finishing all songs.
	r	Loop the playing songs.

    -t, --trace
	Turns tracing mode on.  Equivalent with -mt.

    -d, --display=xdisp
	Set window display.  Valid only on Tcl/Tk interface.

    -g, --geometry=xgeom
	Set window geometry.  Valid only on Tcl/Tk interface.

    --newvolume[=bool]
	Use the new volume calculation which is compatible with Win/DOS
	drivers.  Default is ON.

    --effect=file
	Set user defined chorus/reverb configurations.  Valid only on
	Tcl/Tk interface.

    --convert=ext/converter
	Define new file conversion rule for the specified file
	extension.  The argument gives both file extension and the
	converter program separated by slash letter.  The converter
	program must read the source file from stdin and output a MIDI
	format to stdout.  For example, to convert .rcp file to midi
	format via rcptomid program automatically, set the option as
	follows:

		--convert=rcp/rcptomid

	Also, to accept the gzipped file, too, define the following
	with addition to the above one:

		--convert="rcp.gz/zcat %s | rcptomid"

	The %s is replaced with the corresponding source file name.

    --usefx=bool
	Enable or disable effect controls.  This feature is still
	experimental.  When this option is enabled, drvmidi emulates
	SC88 NRPN (TVF/EG parameters) and AWE32 NRPN controls in GM/GS 
	mode, and accepts hermonic (cc#71), brightness (cc#74), attack 
	and release time (cc#72 and #73) in XG mode.

    --fx_cutoff=int
	Change TVF cut-off parameter sensitivity.  Valid only when
	usefx option is set.  Default value is 170.
    --fx_resonance=int
	Change TVF resonance parameter sensitivity.  Valid only when
	usefx option is set.  Default value is 6.
    --fx_attack=int
	Change EG attack time sensitivity.  Valid only when usefx
	option is set.  Default value is 50.
    --fx_release=int
	Change EG release time sensitivity.  Valid only when usefx
	option is set.  Default value is 50.
    --fx_vibrate=int
	Change vibrato rate sensitivity.  Valid only when usefx
	option is set.  Default value is 30.
    --fx_vibdeepth=int
	Change vibrato depth sensitivity.  Valid only when usefx
	options is set.  Default value is 4.
    --fx_vibdelay=int
	Change vibrato delay sensitivity.  Valid only when usefx
	options is set.  Default value is 1500.

    --seqdev=file
	Specify the OSS sequencer device file to be used.
	The default value is /dev/sequencer.

    --seqidx=val
	Specify the device number index of AWE driver.  If a negative
	value is given, the device is probed and the first matching
	device will be selected.  If multiple AWE driver is installed,
	you'll need to specify the appropriate one.
	Default value is -1.

    --seqbuf=bool
	Enable or disable the buffered output to sequencer device.
	See event handling section for more details.
	Default is ON.

    --seqecho=bool
	Enable or disable the timer synchronization via echo back from 
	sequencer device.  See event handling section for more details.
	Default is ON.


* OPTION FILE FORMAT

    title string
	Set title of this midi file.  Displayed on behalf of the file
	name.

    parsetitle bool
	Enable or suppress to parse the title string from MIDI file
	automatically.

    chorus mode
    reverb mode
	Set chorus and reverb modes, respectively.  The arguments are
	identical with the command line options.  See --chorus and
	--reverb options, respectively.

    chorusdepth value
    reverbdepth value
	Set default chorus and reverb depth, respectively.  The
	arguments are identical with the command line options.

    volume percent
	Total volume in percent unit (see --volume option).

    drum channel
	Set drum a channel status.  Equivalent with --drum option.

    drumflag bits
	Set drum channels.  The argument is a digit number indicating
	drum channels (See --drumflag option).

    acceptall bool
	Accpet or disable all notes/sounds off events (see
	--acceptall option).

    multipart bool
	Enable or disable the multi MIDI part (see --multipart option).

    tracks num
	Set track number of multi part (see --tracks option).

    samecsec bool
	Enable or suppress the note off event check (see --samecsec
	option).
	
    gsmacro bool
	Enable or suppress the GS sysex messages (see --gsmacro
	option). 

    xgmacro bool
	Enable or suppress the XG bank controls (see --xgmacro option)

    xgmap bool
	Enable or suppress the XG SFX & drum mapping (see --xgmap
	option).

    xgload fontfile
	Use the specified file for XG dynamic loading (see --xgload
	option).

    subsf arguments..
	Load optional SoundFont file automatically.
	The arguments are passed to sfxload internally together with
	"-x -b1" options.  For example, to load sfx.sf2 for sample.mid,
	set "subsf sfx.sf2" in sample.id file.
	Note that this commmand will not work together with dynamic
	loading.

    volscale scale
	Set volume scaling parameter (see --volscale option).

    mt32 mode
	Set MT32 program mode.  The argument is from 0 to 2.
	See --mt32 option for each meaning.

    dynamic fontfile
	Use the specified font file for dynamic loading (see --dynamic
	option).

    chnprior bool
	Enable or disable MIDI channel proprity mode (see --chnprior
	option).
    
    chnvolume channel scale
	Set volume scale for each specified channel.  The scale factor
	is given as same way as in volscale command.

    offset value
	Change the base key.  The argument is an integer number.
	If the number -1 is given, all notes (except drums) will be
	played in one semitone lower, and if 12 is given, the sounds
	become one octave higher than normal output.

    newvolume bool
	Equivalent with --newvolume option.

    usefx bool
	Enable or disable effect change controls.  Equivalent with
	--usefx option.
	Note that this feature is still experimental.  

    fx_* value
	Set effect change parameters.  See the corresponding command
	line option.  Valid only when usefx option is enabled.


* SYSTEM RESOURCE FILE:

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

	$HOME/.drvmidirc
	/etc/drvmidirc

The syntax is as follows:

	default options..

The first argument is arbitrary so far, but should be "default" for
future extensions.  The remaining arguments are identical with command
line options described above.

The resource file can be changed via File/Edit Options menu in tkmidi.
Althogh drvmidi accepts both short and long options in the resource
file, tkmidi can edit only long options.


* EVENT HANDLING

As default, drvmidi once writes music events on a buffer for up to two
seconds forward, then sends them to the sequencer device.  This
prevents a pausing even when some heavy process (like garbage
collection in emacs) is working unlike the previous version (ver.0.4.0
or older).

Since the events are sent to the device asynchronously, the program
need to know the playing actual time by the other means. Then, drvmidi
checks the system timer to know the current time and update the status
like volume bars.  Also, sends an echo back event once per second to
the sequencer, and synchronize the internal timer when receiving the
signal from sequencer device.

It is known that on some FreeBSD systems this function doesn't work
correctly.  In such a case, try the option --autoskip (I have no idea
why this solves the bug).  Also, you should try to disable --seqecho
or --seqbuf option.


* SUPPORTED MIDI CONTROLS

    #0		bank select (MSB)
    #1		modulation wheel
    #6		data entry (MSB)
    #7		main volume
    #10		panning position
    #11		expression volume
    #32		bank select (LSB)
    #38		data entry (LSB)
    #64		sustain
    #66		sostenuto
    #67		soft pedal (experimental)
    #71		hermonic content (XG only)
    #72		attack time (XG only)
    #73		release time (XG only)
    #74		brightness (XG only)
    #91		reverb effects send
    #93		chorus effects send
    #98		NRPN LSB
    #99		NRPN MSB
    #100	RPN LSB
    #101	RPN MSB
    #120	all sounds off
    #121	reset controllers
    #123	all notes off


* SYSEX MACROS

    GM on
	F0 7E 7F 09 01 F7

    GS reset
	F0 41 10 42 12 40 00 00 00 cs F7

    GS reverb mode
	F0 41 10 42 12 40 01 30 XX cs F7
      where XX denotes the reverb mode above (from 0 to 7).
       
    GS chorus mode
	F0 41 10 42 12 40 01 38 XX cs F7
      where XX denotes the chorus mode above (from 0 to 7).

    GS drum part change
	F0 41 10 42 12 40 1X 15 YY cs F7
      where X denotes the channel and YY denotes a drum flag.

    GS master volume
	F0 41 10 42 12 40 00 04 XX cs F7
      where XX denotes the volume (from 0 to 7).

    GS multi mode
	F0 41 10 42 12 00 00 7F XX cs F7
      where XX=0: double module mode, XX=1: single module mode.

    XG on
	F0 43 10 4C 00 00 7E 00 F7


* RPN CONTROLS

    - 0000 : pitch bend sensitivity (MSB/LSB).  1 semitone per 128.
    - 0001 : fine tuning (MSB/LSB). in 100/8192 cent unit, and
	 no tuning when MSB/LSB=8192.
    - 0002 : coarse tuning (MSB/LSB). 1 semitone per 128, and no
	 tuning when MSB/LSB=8192.
    - 7F7F : lock-in.  values are ignored.


* NRPN CONTROLS

  GS (SC88) NRPN Controls
	NRPN MSB/LSB, Data Entry (MSB only, center=64)

    - NRPN 1/8:		Vibrato rate
    - NRPN 1/9:		Vibrato depth
    - NRPN 1/10:	Vibrato delay
    - NRPN 1/32:	TVF cutoff
    - NRPN 1/33:	TVF resonance
    - NRPN 1/99:	EG attak time
    - NRPN 1/100:	EG decay time
    - NRPN 1/102:	EG release time

  AWE32 NRPN Controls
	NRPN MSB/LSB, Data Entry MSB/LSB (center=8192)

    - NRPN 127/0:	LFO1 delay
    - NRPN 127/1:	LFO1 freq
    - NRPN 127/2:	LFO2 delay
    - NRPN 127/3:	LFO2 freq
    - NRPN 127/4:	EG1 delay
    - NRPN 127/5:	EG1 attack
    - NRPN 127/6:	EG1 hold
    - NRPN 127/7:	EG1 decay
    - NRPN 127/8:	EG1 sustain
    - NRPN 127/9:	EG1 release
    - NRPN 127/10:	EG2 delay
    - NRPN 127/11:	EG2 attack
    - NRPN 127/12:	EG2 hold
    - NRPN 127/13:	EG2 decay
    - NRPN 127/14:	EG2 sustain
    - NRPN 127/15:	EG2 release
    - NRPN 127/16:	initial pitch
    - NRPN 127/17:	LFO1 pitch
    - NRPN 127/18:	LFO2 pitch
    - NRPN 127/19:	EG1 pitch
    - NRPN 127/20:	LFO1 volume
    - NRPN 127/21:	Cutoff
    - NRPN 127/22:	Resonance
    - NRPN 127/23:	LFO1 cutoff
    - NRPN 127/24:	EG1 cutoff
    - NRPN 127/25:	chorus
    - NRPN 127/26:	reverb


* COPYRIGHT

Copyright (C) 1996-2000 Takashi Iwai

This program is free software; you can redistribute it and/or modify
it 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.

This program is distributed in the hope that it 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.

