/----------------------------------------------\
+--------------- MIKMOD FOR UNIX --------------+
\----------------------------------------------/

This is version 3.0.1 of MikMod of Unix - it is a fairly big leap
from the MikMod 2.14 that everyone's been using for the past year or
so - sorry it's so late coming.  However, I think you'll be pleased
with it...  The console player is better - you can see
& scroll through the instrument list and see the sample messages now,
and the archive support is much improved, and the playlist support is
pretty sweet as well.  The big thing really is... 

WE HAVE IMPULSE TRACKER SUPPORT!!!!!!!!!!!!!!!!!!!!!!!!

This now puts MikMod 3.0 in direct competition with MikIT :)


COMPILING

I.   Type "build-mikmod.sh"
II.  It builds
III. The excutable binary 'mikmod' is spit into your directory
IV.  Install mikmod somewhere in your $PATH
V.   Enjoy kick-ass mod music :)


USING MIKMOD

To get the command line options, type "mikmod -h"
That should tell you most of what you want to know, basically you just
type "mikmod <filename-1> <filename-2> ... <filename-n>"
Once you're in the player, a few keys you can press...
(keys don't have to be capitalized, BTW)

UP/DOWN scrolls the sample list
LEFT/RIGHT or -/+ moves the song backwards/forwards 1 pattern
SPACE pauses
N loads the next song
P loads the previous song
Q quits
W writes writes the current playlist to "$HOME/mikmodplaylist"
I toggles between sample/instrument names/messages 
	(this is only for .XMs and .ITs)
M gives you the song message/comment (.ITs ONLY)

If you're playing MikMod in quiet mode (with the -q switch), you
can tell MikMod to jump to the next/previous song by sending
the MikMod process SIGUSR1 or SIGUSR2 respectivly.
In other words, let's say you're doing something like this:

$ mikmod -pl myalltimefavmods -rp -k -t -q &
[1] 7531

You've told MikMod to read the songs out of the playlist 
myalltimefavmods, to play them in random order, to delete each
module from the playlist after playing (so none get played twice)
to skip over any file access errors, to not spit out any output, and
to run in the background.
bash gives us the process ID, in this case it's 7531.  You can also
find this out from "ps", "top", on any of a number of other utilities.
Now, let's say a song you don't like as much comes on, or for some
reason one seems to be looping forever, you can do this...

$ kill -s SIGUSR1 7531

and MikMod will start playing the next file in the list.
If you want the previous file, just use SIGUSR2 in place of
SIGUSR1.  Note that when you're playing randomly, it doesn't actually
make any different if you select next or previous, because the next song
is selected randomly every time, and the previous one not saved.  As
well, if you're not playing randomly but have an ordered list you are
deleting after each plays, you won't be able to get the previous song
played either...  Hrm, maybe I should make SIGUSR2 toggle pause 
instead...  What do you think?  E-mail me!


BUGS

What?  Bugs?  Where???
Yes, there are a few bugs and/or misfeatures and/or things that should
be implemented that haven't yet been.

- sample messages are sometimes a bit screwed up for some .MTMs
- You can't view the song messages of .MTMs, except possibly for
	the very first line.  This is because the way the song comment
	is stored is really wierd for .MTMs and totally different from
	the way .ITs store it.
- When you pause, any looped notes will keep on playing.  This is
	actually a bug ("feature") of MikMod_TogglePause() which
	I will probably have to do in and patch...
- At the end of a few songs you'll "go over the edge" and it will
	try to play past the end of the second to last patten.  In 
	other words, if "pos:" of the ncurses display starts showing 
	400+ and the sound is wrong (or not there) it's time to hit
	NEXT...
- The ULT loader is broken.  Segfaults every time... Solution:
	AVOID PLAYING ULTRATRACKER MODS FOR THE TIME BEING
	(it's not so common a format, so that shouldn't be too too 
		inconvinient)
- In addition to .ULT, the .FAR, .MED, and .669 loaders are of
	questionable status.  I haven't been able to throw any files
	of such formats at 'em to test.  Tell me about your 
	successes/failures at playing any of those...
- Hmm, the status display should probably display the BPM along
	with the protracker speed...
- Sometimes I've gotten "Cannot allocate DMA buffer" error.  
	I don't know where this is comming from, and it can be annoying.
	Try running it a few times and it will work eventually.
- Prolly some other problems that escape me at the moment...


TODO

* X Interface (there already are several based on older versions of
MikMod, however none of them reached a very sophisticated level)
* File selector under ncurses
* View messages in .MTMs
* Write a /dev/sequencer driver so people with GUSes and AWE32s can
use hardware mixing


MIKMOD ON NON-LINUX PLATFORMS

First, check playercode/unix_drv/ to see if a driver has been written
for your platform.  If so, you're in some luck.  Theoretically you
then can simply edit the makefile to compile in your driver.  It's
probably not that simple, however, as these drivers haven't been tested
with MikMod 3.0 and are carryovers from 2.15...  I don't have access
to Suns, SGIs, etc with which to test.  If you DO get MikMod working
with this distribution on another unix than Linux, or need some help
in doing so, E-Mail me!  I want to support as many unices as possible
in the MikMod for Unix distribution.
BTW: FreeBSD uses the same sound driver as Linux, so the oss driver
should probably work fine.  Werd to the FreeBSDers!
Also...  This code was originally for DOS.  DOSisms like the DOS 
drivers and makefiles for Watcom C have been mostly deleted to save 
space.  Go to Jake Stine's web site for the DOS version.


CONTACT

You probably want to e-mail me at amstpi@freenet.tlh.fl.us as
this is an unsupported release of MikMod (that is, not supported by the 
guy who officially owns MikMod now, Jake Stine)

offical Mikmod for Linux homepage is at
http://www.freenet.tlh.fl.us/~amstpi/mikmod.html

latest releases of Linux mikmod can also be found at
ftp://sunsite.unc.edu/pub/Linux/apps/sound/players

The offical offical MikMod homepage is Jake Stine's
(this is for the DOS version that MikMod for Unix is based upon)
http://www.epix.net/~dracoirs/mikmod

Other relevant web pages/email addresses can be found in various
parts of the source tree and documentation...

Hope this brings you hours of mod-listening pleasure!

- Peter Amstutz
11:30pm 16 October 1997