Gt plays midi files in surround sound using patches you provide.  It
is a "soft synth" sampler derived from Tuukka Toivonen's classic program
TiMidity.  To get surround sound, you need a suitable sound card with
four or six analog connections to an external amplifier or powered
speakers and a fairly recent version of the Alsa drivers and library.


Compiling:

There are some configuration options (look at "./configure --help"), but
probably nothing you need to be concerned with.  The standard
	./configure
	make
	su
	make install
should work.


Running:

Assuming your sound system is set up ok and you have patches (see below),
cd to some directory where you have some midi files and type "gt" in an
X window or Linux console.  Then gt will play them and display the notes
and midi controls using curses.  The display is much nicer if you use
a window that can display at least 16 colors, e.g., an xterm window.
You can also give on the command line a directory containing midi
files or paths to individual midi files.

For a one page summary of command line options, type "gt -h", and for
more info, "man gt".


Patches:

Many distributions come with either GUS patches or a Soundfont set up
to work for Timidity++.  Gt knows about some other kinds of patches,
but patches set up for Timidity++ should work.  If you used configure
without options, as suggested just above, gt will expect to find
the config file "timidity.cfg" in the directory /usr/local/share/timidity/.
If it's present, but in some different location, you'll need to do
something about that.  Perhaps go back and run configure again using
the "--prefix=..." or "--datadir=..." option, or make a soft link
to your "timidity/" directory in /usr/local/share, or something along
these lines.  There's also a command line option for telling gt where
to look.

But if you don't have patches at all, you'll just have to get some for
gt to work at all.  There is a very small starter set of patches in
the examples/ directory of this distribution.  It has just a piano,
quitar, and a couple of drums, and it doesn't sound very good.  See
the README file in the examples/ directory for how to set it up.  For
a nicer set of patches, try Eric Welsh's "eawpats" GUS patches, or the
version of these at http://www.freepats.org, or else use a general
purpose GM (General Midi) Soundfont.  There are many thousands of
free Soundfonts on the web.  A nice one is Frank Wen's FluidR3,
available at http://www.ibiblio.org/thammer/HammerSound/, and there
are config files for it in the examples/ directory.

Gt can handle very large patch sets, and you could probably spend
years elaborating your patch setup, if you want to get into it.

---------------------------------------

The above might well get gt up and running.  What follows are notes
on details for special situations or making advanced use of gt.

On surround sound.

Gt produces an interleaved stream of samples with 1, 2, 4, or 6
sound channels.  Ordinarily this is sent to the Alsa sound driver
in the Linux kernel, but it can also be saved to a wave file or
an ac3 file.  There are command line options to choose the
number of channels and the destination.  The default number of
channels is the highest number possible -- for sound output, gt
tries to open the kernel driver for 6 channels, and if that fails,
it drops back to 4, quadriphonic, or 2 channels, ordinary stereo.
I haven't tried 1 channel, monophonic output for a long time, and
I don't know whether it still works.  Six channels is 5.1 sound,
and the channels, in the order in which they are produced, are
for the left, right, left rear, right rear, center, and lfe
speakers.  Four channels is 4.0 sound, and the channels are for
the left, right, left rear, and right rear speakers.  For direct
sound output, gt does not filter the lfe subwoofer channel, but
it does use a 100Hz low pass filter for output to wave or ac3
files.

Only Alsa will do.  Gt does not use the OSS, Open Sound System.
I don't have OSS on my system, and, anyhow, I don't know how to
do surround sound on OSS.  Also, to get surround sound, you need
to have 4 or 6 analog connections between your sound card and
external amplifier or powered speakers.  The digital SP/DIF
connector won't work, because the current generation of Alsa
drivers can't translate from multichannel analog to a digital
signal.  It might be possible to use digital sound with a
sound chip that has an onboard Dolby encoder, but I haven't
heard of anyone who has gotten that to work.

However, if you have a surround sound system that uses the
SP/DIF digital connector, it may be possible to get some
surround sound from gt by outputting to an ac3 file, then
using the ac3dec program from the Alsa tools to play it.
Ac3 files are Dolby Digital compatible encoded files.  The ones
produced by gt sound a little cheesy, I'm sorry to say.

If there is a problem getting surround sound to work on your
system, or some doubt about whether it is actually working, I
suggest using the speaker-test program from the Alsa utilities.
If that works to give you sound from all your speakers, then
gt should work.  Gt does not presuppose any special setup
of Alsa -- it should work with the defaults, provided of
course you have the right Alsa modules installed for your
soundcard.

My sound system uses 16 bit samples, not 24 bit samples.  But
gt can probably handle 24 bit output, though I cannot test
this directly.  Actually, my own soundcard, an Audigy2 zs,
supposedly will do 24 bit sound, but the Alsa driver for this
card does not yet know how to send 24 bit sound to the card.
Gt first tries to open the Alsa driver for 6 channel 24 bit sound,
and falls back to 6 channel 16 bit sound if this fails, so if
your card and Alsa driver are capable of it, you might get 24 bit
surround.  I don't know.  You can ask gt for 24 bit sound with
the "-Oa3" command line option, and you'll get it, but what
happens in this case on my system is that the Alsa driver refuses
to give 6 channels, gt falls back to 2 channels, then sends the
24 bit 2 channel signal to the Alsa driver, which down converts
the 24 bit sound to 16 bit sound before sending it to the card.
So it's pointless to ask for 24 bit sound for direct sound output
on a system like mine, though it may be useful for making wave
files using the command line option "-0w3".

For making ac3 files, the number of bits per sample is not
relevant.  32 bit samples are always used as a basis for the ac3
encoding.


On configuring and compiling.

If you need to edit the configure.ac file or the Makefile.am files,
you can use autogen.sh afterward to redo the configure and make
files.

During configuration, the ncurses and vorbisfile libraries are
looked for.  If ncurses is not found, the ncurses user interface
for gt cannot be compiled, leaving you with the "dumb" command
line interface only.  Gt will still work.  If the vorbisfile
library is not found, gt will not be able to use compressed
ogg file samples with sfz patches.  Since you will probably
not be using sfz patches, and if you do you will probably use
wave or aiff sample files with them, this will not make any
difference.  Gt will still work.  But if it's important to
you and the problem is merely that ncurses or vorbisfile are
in an unusual place on your system, the configure program has
options for telling it whare to look for these libraries.
Use "./configure --help" for information about these options.



Features:

(1) Reads extended GUS patches which contain about as
    much information about instruments as Soundfonts
    contain.  The utils directory has some documentation
    on extended GUS patches, a program "unsf" to extract them
    from Soundfonts, and a program "patinfo" to display
    their contents.

(2) Does 4 or 6 channel surround sound output.  You can
    also make 4 or 6 channel wave or ac3 files using Gt's
    wave and ac3 output drivers (use "-Ow" or "-Od").

(3) Has configuration file facilities for (a) referencing
    soundfile banks and instruments as GUS banks and
    instruments are referenced, (b) setting up alternate
    bank-instrument configurations and switching among
    them from the timidity command line, and (c)
    designating banks as various sorts of XG banks.

See the file FEATURES for a more complete list.

The utils/ directory has:

(A) unsf, for breaking up soundfonts into extended GUS
    patches.

(B) patinfo, for displaying information about an extended
    GUS patchfile.

(C) patcat, for combining two GUS patches into one extended
    stereo GUS patch.

(D) dim, a midi file disassembler.

Additional utility programs are in the src/ directory:

(E) sf2cfg, for constructing a config file for a Soundfont.

(F) sfz2pat, for deriving extended GUS patches from SFZ
    patches.


Greg Lee <greg@ling.lll.hawaii.edu>