
                              //===============\\
                              ||               ||
                              ||  MikMod'Unix  ||
                              ||               ||
                              \\===============//

                                 version 3.0.4 


Hello folks !

You've just got MikMod 3.0.4.
As usual with each new version, there's a lot of bugfixes and improvements.
Check out the ChangeLog for more information.


Building MikMod
---------------

Although there's a configure script, MikMod is not built with Autoconf yet.
Expect this in the next release.

You'll need an ANSI C compiler to build MikMod. If you want to use a specific
compiler rather than the defaut "cc" compiler, set the environment variables CC
and CFLAGS to the correct values before running configure again (and don't
forget to do a make clean)

In this directory, run
  ./configure

Depending on your configuration, you will be asked some questions.

First, if your system is fairly old and doesn't provide some Posix.2 functions,
you will be asked if you want to use the provided replacement functions.
Although you can safely answer "Y", I'd like to know if you encounter these
questions.

Then, you will be asked if you want to build a debug version ; this option is
mainly intended for the MikMod developers, so you should answer "N" here.

The next step is the driver selection. Depending on your system, some drivers
will be automatically built-in, but you'll be asked if you want the AudioFile,
EsounD and OSS drivers. To my knowledge, AudioFile has only been ported to
Digital Unix and IRIX, so don't choose it if your system is different or if
you don't have the Digital AudioFile library installed. Likewise, the EsounD
only works on Linux boxes now. The OSS is a special case, since some systems
come with a built-in OSS driver (FreeBSD and Linux), but you can buy the OSS
driver for many other Unices. And if you're running SunOS or Solaris, you will
be asked if you want the sound to go to the speaker connector or to the
headphone connector.

After that, you will be prompted for various MikMod options. On some operating
system, you'll be able to make MikMod increase its priority if you run it with
root privilege ; this is called tho "CPU time snagger" feature because on slow
machines it can drain a lot of the CPU time. The other option is the
high-quality mixer. The high-quality mixer handles surrond sounds and works hard
to prevent clicks and other spurious noise in output. However, doing this needs
a lot of CPU power. On my main development machine, a PC with a 200 MHz
processor running a slow Unix flavour, the high-quality mixer isn't fast enough
to mix at 44100 Hz, and can't mix more than 16 channels real-time at 22050 Hz.
Your mileage may vary, but if you don't have a very fast machine or are using a
output-to-disk driver, you won't like this option.

After the configuration has finished and the Makefiles are created, just run
  make
and you'll get your customized MikMod binary in the current directory.
If the build fails, I'd like to hear from you to correct the problem.

Note that the remaining binary is not stripped ; if you haven't asked for a
debug version and wish to install it in a common location (such as
/usr/local/bin), don't forget to do "strip mikmod" first.


Using MikMod
------------

The command-line options have changed since previous version, but with a bit of
getopt() magic the old syntax is still supported.
Run MikMod without parameters to get the available options.
Once you're in the player, if you haven't choosed terse mode (a la MikMod 2),
pressing the H key will give you an help screen with the list of the keys you
can use. I hope it's understandable.

If you're playing MikMod in quiet mode (with the -q/-quiet 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 -playlist myalltimefavmods -kqtra &
[1] 7531
You've told MikMod to read the songs out of the playlist myalltimefavmods
(-playlist), to play them in random order (-ra) , to delete each module from the
playlist after playing (so none get played twice) --k), to skip over any file
access errors (-t), to not spit out any output (-q), and to run in the
background.
Your shell will give you the process ID, in this case it's 7531.  You can also
find this out from "ps", "top", or a number of process management 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
or
$ kill -USR1 %1
(if your shell supports the %n process notation)
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 if you've used the "play once" option (-k/-once), asking for the
previous song will in fact restart the current song.
This feature also works when MikMod is in interactive mode (with the curses
interface), but is less useful then, since you have full player control...


Known problems
______________

Alas, no software is perfect, and MikMod still has a few bugs... However, we're
working on them and you can bet they'll disappear in a future release.

- The loader for some rare formats (DSM and MED) have not been extensively
  tested and may be broken. I would like to hear about them, success as well
  as failures... And if you have such modules, I'd like to get them for
  testing...
- Modules with 16 bit samples sometimes don't play well (there's extra noise in
  the background)
- The EsounD driver has some issues. Please read README.EsounD if you want to
  use this driver.


Future
______

Here's what's on my todolist :

- Fix all remaining bugs. Yes, really.
- Use autoconf for building
- Implement all IT effects
- Port to more hardware and more Unices
- Add support for DMP .AMF modules (partially done in my CVS tree)
- Document the player engine, and make it a shared library
- Write a nice X11 interface...
- Write a file selector and playlist manager for the curses player
- Anything else which will be requested...


Status
------

The following platforms are known to work :

- Linux i386, with the built-in OSS driver in kernels 2.* ; it may work with 1.*
  kernels but has not been tested
- Linux i386, with the EsounD driver.

- FreeBSD with the built-in OSS driver.

- OpenBSD 2.2 i386, with the OpenBSD driver. This driver only works correctly in
  8 bit mono at 8000 Hz. NetBSD should work as well.
  
- HP-UX 10 on HP 9000 hardware, with the HP audio driver.
  (I had to use gcc instead of the default HP compiler)

- IRIX 6 on various SGI hardware.
  Please read README.SGI as well.

- Various Sun Sparc/UltraSparc running Solaris 2.5, 2.5.1 and 2.6
  Please read README.SUN as well.

MikMod compiles but has not been tested since ages on :

- IBM RS/6000 running AIX 3

MikMod used to work on :

- DEC Alpha running OSF/1 with the AudioFile driver

If you want to use the EsounD driver, please read the file README.EsounD as
well.

If your favorite system is not supported, please drop me a note and I'll see
what I can do for you.

Thanks
------

I would like to thank everyone who contributed to MikMod. Their names are in
the AUTHORS file. Thanks a lot !

License
-------

The MikMod engine (aka MikMod sound library), contained in the include/, mmio/
and playercode/ directories, is covered by the GNU Library General Public
License, which you can find in COPYING.LIB.

The non-standardized or extended Posix functions sources which reside in extra/
are also covered by the GNU Library General Public License.
 
The sound player example, contained in the usercode/ directory, is covered by
the GNU General Public License, which you can find in usercode/COPYING.

Contact info
------------

Since MikMod for DOS has been officially withdrawn, there's no need to bother
MikMak or Air Richter (the two main MikMod authors) with email regarding this
version of MikMod.
Please send all your MikMod related e-mail to me, at :
  miodrag@mygale.org

MikMod's official home page has moved with each new maintener, so the latest
official MikMod'Unix homepage is located at :
  http://www.mygale.org/~miodrag/mikmod

Latest releases of MikMod'Unix can be found on the official homepage, as well
as on 
  ftp://sunsite.unc.edu/pub/Linux/apps/sound/players
and all sunsite mirrors. However, due to the huge traffic at sunsite, it may
still be in /pub/Linux/incoming ...

I hope you'll enjoy using this version of MikMod as well as I enjoyed debugging
and improving it. Yes, really, I enjoy debugging coredumps... (-: .  

-- Miodrag ("Miod") Vallat (miodrag@mygale.org)
