.TH XGMOD 1 "1996 Mar 03" "Version 2.3" "USER APPLICATIONS"
.SH NAME
xgmod \- play music modules
.SH SYNOPSIS
.B xgmod
[\-chrR] [\-P pan-factor] [\-v volume] [module...]
.SH DESCRIPTION
This manual page documents
.BR xgmod ,
a music module file player for Linux and X, with support for the
Gravis Ultrasound card and AWE cards.
.B Xgmod
is capable of playing 669, MOD, Multitracker (MTM), Scream Tracker III (S3M),
Ultratracker (ULT), and FastTracker (XM) files.
.PP
If modules are listed on the command line, those modules will be added to the
file queue.
Modules compressed with \fBcompress\fP, \fBgzip\fP, \fBlharc\fP, or
\fBzip\fP can be played by
.BR gmod ,
if gunzip, lharc, and/or zip are installed.
.SH OPTIONS
.TP
.B "\-c"
Disable compression of modules in memory.  Normally, modules are compressed
in memory in order to use less space.  Specifying this option will save some
CPU time.
.TP
.B "\-h"
Display help.
.TP
.B "\-P \fIpan-factor\fP"
Set the panning factor.  Valid values are -100 to 100.  Higher absolute values
produce more panning.  Negative values cause the left/right channels to be
swapped. The default value is 100.
.TP
.B "-r"
Infinitely repeat the current module.
.TP
.B "-R"
Randomize the play order of the modules.
.TP
.B "-v \fIvolume\fP"
Set the volume to
.I volume.
Valid values are 0 to 255.  The default value is 255.
.SH THE XGMOD WINDOW
The Xgmod main window contains a number of buttons.
.TP
.B "Double Left Arrow"
Move to the previous song position (rewind)
.TP
.B "Double Right Arrow"
Move to the next song position (forward)
.TP
.B "Double Left Arrow with bar"
Play previous module in queue.  If there is no previous module (the module 
currently playing is the first module in the queue), playback will stop.
.TP
.B "Double Right Arrow with bar"
Play next module in queue.  If there is no next module (the module currently
playing is the last module in the queue), playback will stop.
.TP
.B "Single Right Arrow"
Begin playback of the current module.
.TP
.B "Square"
Stop playback
.TP
.B "Queue"
Pop up the queue window
.TP
.B "Options"
Pop up to options window
.TP
.B "Track"
Pop up the tracking window
.TP 
.B "Samples"
Pop up the sample information window
.TP
.B "Comment"
Pop up the module comment window
.TP
.B "Exit"
Exit Xgmod
.SH THE QUEUE WINDOW
The queue window displays all files currently in the play queue.  Double
clicking on a file will start playback of that module.  A number of buttons
are provided for manipulating the queue.
.TP
.B "Add"
Pop up the file selector to add files to the queue
.TP
.B "Save"
Save the current file queue
.TP
.B "Current"
Highlight the module currently playing in the file queue list
.TP
.B "Play"
Start playback with the module currently highlighted in the file queue list
.TP
.B "Remove"
Remove the highlighted file from the file queue
.TP
.B "Clear"
Remove all files from the file queue
.TP
.B "Shuffle"
Randomize the order of the files in the file queue.
.TP
.B "Close"
Close the queue window
.SH THE OPTIONS WINDOW
The options window contains four groups of options.  The first group, play
options, are effective immediately after they are pressed.  The second group,
load options, are checked only when a module is loaded.  The third group
contains toggles to control the file queue.  The fourth group controls the
selection of octaves when loading a module.  By default, all the options are
off.
.TP
.B "Break Infinite Loops [play]"
If this toggle is enabled, infinite loops in modules will be broken.  
.TP
.B "Ignore Speed0 Commands [play]"
Speed 0 commands normally cause a module to stop playing.  Enabling this toggle
will cause all speed 0 commands to be ignored.
.TP
.B "50 Hz Clock Freq [load]"
Enabling this toggle will cause modules to be played using a 50 Hz base clock
frequency.  This option is effective for MOD files only.
.TP
.B "NTSC Sample Timing [load]"
If this toggle is enabled, samples will be playing using NTSC (as opposed to
PAL) sample timing.  This option is effective for MOD files only.
.TP
.B "Disable BPM Tempos [load]"
Enabling this toggle will cause all speed changes to be considered "ticks
per division" changes.  This option is effective for MOD files only.
.TP
.B "Check magic number [load]"
Check the magic number in MOD files.  If the MOD file does not have a
magic number, then it will not be loaded.  Old 15 channel MODs do not
have magic numbers.
.TP
.B "Unqueue After Play [queue]"
If this toggle is enabled, the module will be removed from the file queue after
it has been played.
.TP
.B "Random Order [queue]"
Play the modules in the file queue in a random order.  Clicking "previous
module" or "next module" in the main window will select another module
randomly.
.TP
.B "Highlight Current [queue]"
Highlight the current module in the file queue whenever a new module is loaded.
.TP
.B "Limited [octave selection]"
Use the standard octave range for MOD files.
.TP
.B "Extended [octave selection]"
Use an extended octave range for MOD files.
.TP
.B "Automatic [octave selection]"
Use the standard octave range if all notes in the MOD file fall within the
standard range; otherwise, the extended octave range will be used.
.TP
.B "Save"
Save the options into the .xgmodrc file.
.TP
.B "Close"
Close the options window.
.SH THE GMODRC FILE
The gmodrc file is used to determine settings to be used for particular
modules.  The gmodrc settings will always override the settings in the options
window.  GMOD will first look for a file named .gmodrc in the user's home
directory, and if it is not found, it will look for /usr/etc/gmodrc.  The gmodrc
settings are combined with the options given on the command line.  The format of
the file is:
.PP
filename(without path) option ...
.PP
For example, if mymodule.mod uses NTSC sample timing and speed 0 commands
should be ignored, the following line could be entered in the gmodrc file:
.PP
mymodule.mod ntsc nospeed0
.PP
Spacing is not important, but case is significant.  The module name must start
at the leftmost position of the line.  The length of the line is limited to
160 characters.
.PP
Valid options are:
nobpm (ignore BPM tempos), ntsc (use NTSC sample timing), nospeed0 (ignore
speed 0 commands), extend (extended octaves), and 50hz (use 50 Hz clock
frequency)
.SH NOTES
This applies only if gmod is compiled without linear volume support:
Setting the sequencer volume to anything greater than approximately 60 when
gmod's volume
.I "(\-v)"
is set to 255 will cause volume clipping.  Lower gmod volumes will allow higher
sequencer volumes before clipping occurs.
.PP
MOD files use various timing methods.  Different methods and the corresponding
options are listed below:
.PP
NTSC (60 Hz) CIA:  NTSC sample timing
.PP
PAL (50 Hz) CIA:  no options (default)
.PP
NTSC (60 Hz) Vblank:  NTSC sample timing, Ignore BPM tempos
.PP
PAL (50 Hz) Vblank:  Ignore BPM tempos, 50 Hz clock frequency
.SH DIAGNOSTICS
The exit codes are:
.TP
0
Normal termination.
.TP
50
Bad arguments.
.TP
51
An error occurred while attempting to access the sequencer.
.TP
52
An error occurred while attempting to load a module
.TP
53
No GUS card was found.
.SH AUTHORS
Original source by Hannu Savolainen.
.PP
MultiTracker/Ultratracker loading by Robert Sanders.
.PP
Many other modifications have been performed by Andrew J. Robinson
<arobinso@nyx.net>.
Andrew is currently the maintainer of gmod.  Please direct any comments,
questions, bug reports, etc. to him.  There is currently a Xgmod WWW page
available through http://www.nyx.net/~arobinso
.PP
Xgmod is Copyright (C) 1996 by Andrew J. Robinson.