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

This is version 3.0.3 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)
^L (control-L) redraws the screen if it becomes corrupted

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", or 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.  (view .IT messages works perfectly)
- 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...  This has been bugging (no pun intended) me for a while but
	it's very elusive...  This has been kludged around for now.  If a song
	goes past position 256, it'll break.  A few wierd formats like .it 
	allow 64+ positions per pattern, don't they?  Hope this doesn't
	break anything...
- 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...
- _Very Occasionally_ I've gotten "Cannot allocate DMA buffer" error.  
	I don't know where this is comming from, and it can be annoying.
	Usually running it a few times will see it work eventually.
- Some .ITs will give you nothing but static, and lots of it.  Ick...

TODO [yea, I still haven't done most of this stuff...]

* 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
* Write a spiffy-ass GGI-based interface
* Contact other MikMod developers and get 'em to do this stuff 'cause I'm
too lazy to :)


MIKMOD ON NON-LINUX PLATFORMS

- The author of the SGI driver contacted me, and he has verified
	that the SGI driver works with MikMod 3.0!  He also cleaned up
	the code some to fix some gcc-isms that could have hurt 
	portability.  Thanks Stephan!
- Torbjorn Norbye contacted me about the Sun driver, and verifies that works
	on SunOS/Solaris!  Thanks Tor! 
- Douglas Carmichael has made the needed modifications to compile
	cleanly under FreeBSD.  Excellent!
Otherwise,
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: AFIK FreeBSD uses the same sound driver interface 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 Unix 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
(although knowing how fast sunsite moves uploaded apps to their
appropriate directories, it's probably still in /pub/Linux/Incoming)

The offical offical MikMod homepage is Jake Stine's
(this is for the DOS version that MikMod for Unix is based upon)
http://divent.simplenet.com

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
8:40pm 11 Febuary 1998
