'mod' - plays music modules (MOD/MTM/ULT/S3M) on a GUS under Linux
------------------------------------------------------------------

The goal of this project of mine is to be able to play all the Amiga
ProTracker modules as they sound on a real Amiga (as closely as the
hardware will permit). For fun I added support for a couple of
PC-formats too. There is currently support for MODs (15/31-instrument,
up to 32 voices), MTMs, ULTs and S3Ms.

There are quite a few changes since the previously released version
0.1 (the code about trippled in size :) The major points being an
interactive ncurses-based interface and support for other formats. See
CHANGES for details.

I used ncurses 1.8.5, so I won't guarantee it will work with other
versions (but try it with whatever version you have installed - the
worst thing that can happen is a messed up screen).

This release requires at least version 3.0 of the VoxWare sounddriver
(or if it isn't available yet, ALPHA-version 2.99 from 940911 or later
will do). Note that you need kernel-version 1.1.48 or above for this
version of VoxWare (and the version of VoxWare in 1.1.48 isn't the one
you need). Don't we all hate how this upgrading-spiral seems to go on
for ever and ever :-(

A suitable ALPHA-version is available at:

ftp.funet.fi:/pub/Linux/ALPHA/sound/v3.0-proto-940925.tar.gz

(this directory is hidden, so you won't see it until you 'cd' to it)

Note: This is ALPHA software, so you are on your own (though I should
mention that I've been using the above version for more than a month and
it has caused me no problems whatsoever).

Make sure you include "MIDI interface support" when you configure the
sound-driver.

With the above version there are no problems with soundcard.h (no need
to use a copy from an old version of VoxWare), and you no longer need
to define GUS_USE_CHN_MAIN_VOLUME (not for 'mod' anyways).

If you have an earlier version it WILL NOT work. 'mod' depends on some
important fixes to the sequencer-drivers (specifically the addition of
non-blocking IO and a bugfixed select()).

If you are having trouble with skips in the soundoutput during heavy
disk-activity, you could try to enable interrupt unmasking using the
'hdparm' utility. They supposedly decrease the interrupt-latency and
gives the sounddriver a better chance to get it's interrupts served.

Packed modules are now supported (requires the external programs gzip,
lharc, unzip and unarj). If these programs are not installed 'mod'
will still work, but files packed with the corresponding packers can't
be loaded.
If you are having trouble loading some module packed with anything but
gzip it could be that the text output from your version is different
from mine. If so, please send me the output of the command 'xxx l
modulename.suffix' (or whatever option is used to list the contents of
the archive) and I'll supply a fix. The versions I am using are the
ones that come with stock Slackware 2.0.

Support for all the above packers was added mainly because most
modules on ftp-sites are packed with lha or some other packer. Now you
can just fetch them and play them without (un/re)packing. It doesn't
matter if there are a couple of small text-files in the archive, 'mod'
will play the correct file. Note that most unpackers are slower than
gzip, so you might want to repack them if loading is too slow (for
example, lha is quite a bit slower than gzip).


Installing mod
--------------

1) Upgrade kernel (>= 1.1.48) and/or sounddriver (>=940911). Don't forget
   to copy the kernel-image to the right place and rerun LILO.

   Skip this step if you already are on the bleeding edge (or if you are
   reading this a long time after I am writing it :)

2) Configure 'mod' by editing the makefile (most people won't have to
   change anything, but take a look at it to make sure).
   
3) make all

4) make install

Try it out! (for zsh-users: mod -r /**/*.mod  ;-)

NOTE: Don't make 'mod' suid/sgid as it contains calls to system().
      (There really is no reason to do it)


Invoking mod
------------

Try 'mod', 'mod -h' or 'man mod'.


Credits
-------

Linus Torvalds and all the people that made the Linux OS what it is today.

Hannu Savolainen for his VoxWare sounddriver.

Advanced Gravis for their EXCELLENT soundcard.

Dr.Awesome for his great modules (major reason to why I started this project :)

kurt.kennett@gravis.com for his MODFIL10.TXT that helped me understand the
basics of the module format before digging into the original sources for
the gory details.

And of course Karsten Obarski for creating the MOD-format (as hideous as it
may be :-)

Also thanks to Peter Tufvesson for suggestions and bugreports.

Future version and bugreports
-----------------------------

Feel free to report bugs or send me suggestions for features that you
would like to see implemented. I have put in most of the features I
wanted to see in a player appart from what is in the TODO-list, so if
you have any ideas tell me.

When it comes to bugreports I am especially interested in reports of
modules that play incorrectly, or won't be loaded even though it can
be loaded by the composer it was created with.

/Mikael Nordqvist (mech@df.lth.se or d91mn@efd.lth.se)
