  Hello folks !


This is libmikmod, version 3.1.7, a portable sound library for Unix.
This version is mainly a bugfixed 3.1.6 version... with some new features,
though.
Check out the file 'NEWS' for more information.


>> BUILDING LIBMIKMOD
---------------------

- If you're building libmikmod under MacOS, please refer to the 'README' file
  located in the 'macintosh' subdirectory.

- If you're building libmikmod under OS/2, please refer to the 'README' file
  located in the 'os2' subdirectory.

- If you're building libmikmod under Windows, please refer to the 'README' file
  located in the 'win32' subdirectory.

- If you're building libmikmod under any other system which is not a Unix
  flavour, then be warned that this your platform is not supported and that
  libmikmod will probably not build out of the box ; don't hesitate to drop me
  a note and I'll see what we can do for this situation.

So you're on a good old Unix workstation, aren't you ?

You'll need an ANSI C compiler to build libmikmod. If you're building on a
32 bit architecture, your compiler must provide a 64 bit integer type
(usually 'long long').

To prevent clobbering the sources, I recommend building libmikmod in an
alternate directory, for example 'build' :

  mkdir build
  cd build

In this directory, run libmikmod's configure script :

  ../configure

The configure script will attempt to guess correct values for various
system-dependent variables used during the build process, and will
create appropriate Makefiles for proper compilation. 

If you're not familiar with configure scripts and their standard
options, you can find more general information about them in the file
INSTALL.

The default behaviour of the configure script is to create both a static and
a shared library, with as many drivers as possible, which are dynamically
loaded whenever possible. However, it can be given several options to tweak
your configuration of libmikmod :

The --enable-af, --enable-alsa, --enable-esd, --enable-oss and --enable-ultra
options will compile respectively the Digital AudioFile, Advanced Linux Sound
Architecture (ALSA), Enlightened Sound Daemon, Open Sound System (OSS) and
Linux Ultrasound drivers.

Since the configure script will search for the appropriate include
files and libraries, to compile as much drivers as possible, these
options are mostly useful in their negative form :
  ../configure --disable-esd
will configure libmikmod without the Enlightened Sound Daemon driver, even
if all the necessary files for compiling are present on the system. 

The --enable-dl option enables the dynamic load of the alsa, esd and ultra
drivers at runtime, if your systems support it. This option is enabled by
default if the build system supports it, so it is more useful in its negative
form :
  ../configure --disable-dl
will configure libmikmod without the dynamic loading facility.

The --enable-threads option enables the creation of a thread-safe libmikmod
library, if your system provides POSIX threads. This option is enabled by
default, so it is more useful in its negative form :
  ../configure --disable-threads
will configure for a non thread-safe version of libmikmod.

The --enable-shared and --enable-static options control whether a static
library, a shared library or both should be built.

The --enable-debug option creates a debug version of libmikmod.

After you've successfully run configure, simply run

  make

to get all things build. Then, run

  make install

to have the library installed. Depending on where you choose to install it
(using the --prefix= option to configure), you may need root privileges for
this operation.


>> STATUS
---------

The following platforms are known to work :

- Linux/i386 :
   o with the built-in OSS driver in kernels 2.0.*, 2.1.* and 2.2.* ; it may
     work with 1.* kernels but has not been tested.
   o with the EsounD driver (on top of OSS and ALSA).
   o with the ALSA driver (including multi sound card configurations).

- Linux/Alpha :
   o with the built-in OSS driver in kernels 2.0.*, 2.1.* and 2.2.*
   o with the EsounD driver.

- FreeBSD 2.2.x and 3.x with the built-in OSS driver.

- NetBSD/i386 1.3.2 and 1.3.3, with the NetBSD audio driver.
  [I've downgraded my NetBSD testbed to 1.3.3 - 1.4 is hardly usable on it]

- OpenBSD/i386 2.2, 2.4 and 2.5, with the OpenBSD audio driver.
  
- HP-UX 10 on HP 9000 hardware, with the HP audio driver.

- IRIX 6 on various SGI hardware (Indy, Octane) :
   o with the SGI Audio library driver.
   o with the EsounD driver.

- Sun IPX, SparcStation (4,5,10,20), UltraSparc (5,30) running Solaris 2.5,
  2.5.1 and 2.6, with the Solaris audio driver.

- Solaris 2.6/i386 :
   o with the Sun audio driver.
   o with the EsounD driver.
  
- OS/2 3.0 and 4.0 :
   o with the MMPM/2 drivers.
   o with the DART driver when supported.
   
The following platforms were supported in the past, but the latest versions
couldn't be tested on such machines :

- DEC Alpha running OSF/1 with the AudioFile driver (not tested since 2.x)
- IBM RS/6000 running AIX 3 (not tested since 3.0.4)

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


>> Y2K COMPLIANCE
-----------------

The libmikmod library does not deal with dates. So, as long as the few libc
functions used by the library are Y2K-compliant, libmikmod is Y2K compliant.


>> DRIVER PARAMETERS
--------------------

Until a good place to put this information is found, here is the list of
parameters recognized by the drivers, as well as the driver alias list.

- AudioFile (alias "audiofile")
  machine=  same syntax as the AUDIOFILE environment variable.
  
- EsounD ("esd")
  machine=  same syntax as the ESPEAKER environment variable.


- AIX ("AIX"), DirectX ("ds"), OS/2 MMPM ("os2")
  buffer=   logarithmic size of the buffer, in the range 12-19. Default is
            15 for AIX, 16 for DirectX and OS/2.
  
- ALSA ("alsa")
  card=     card number. Default is first pcm-capable card. Replaces the
            ALSA_CARD environment variable, which is now deprecated.
  pcm=      pcm interface number. Default is first adequate interface. Replaces
            the ALSA_PCM environment variabl, which is now deprecated.
  buffer=   logarithmic fragment size, in the range 2-16. Default is 4.
            Replaces the MM_NUMFRAGS environment variable, which is now
			deprecated.
			
- HP ("hp")
  buffer=   logarithmic size of the buffer, in the range 12-19. Default is 15.
  headphone redirects the output to the headphone port.
  
- OSS ("oss")
  buffer=   logarithmic fragment size, in the range 7-17. Default is 14.
            Replaces the MM_FRAGSIZE environment variable, which is now
			deprecated.
  count=    fragment count, in the range 2-255. Default is 16.
            Replaces the MM_NUMFRAGS environment variable, which is now
			deprecated.

- SGI audio library ("sgi")
  fragsize= buffer size for libmikmod internal use.
            Replaces the MM_SGI_FRAGSIZE environment variable, which is now
			deprecated.
  bufsize=  buffer size for the audio library.
            Replaces the MM_SGI_BUFSIZE environment variable, which is now
			deprecated.

- Sun/Solaris/NetBSD/OpenBSD audio ("audio")
  buffer=   logarithmic fragment size, in the range 7-17. Default is 12.
            Replaces the MM_FRAGSIZE environment variable, which is now
			deprecated.
  headphone on SunOS/Solaris only, redirects the output to the headphone port.

			
- Piped output ("pipe")
  pipe=     Pipe command (mandatory).
  
- Disk writers in raw and wav formats ("raw" and "wav")
  file=     Output file name. Default is music.raw for the raw driver and
            music.wav for the wav driver.
			

- Dart ("dart"), MacOS ("mac"), NoSound ("nosound"), SGI ("sgi"),
  Standard output ("stdout"), Ultrasound ("ultra"), Windows Multimedia
  ("winmm")
  These driver have no options.


>> ALSA DRIVER SPECIFIC INFORMATION (Linux specific)
-----------------------------------

The Advanced Linux Sound Architecture (ALSA) project aims to provide
better sound facilities than the current OSS drivers. Although it is
still in beta, it appears to be very stable and very easy to program
compared to the OSS.
Besides, it works much better than OSS for Gravis-type soundcards.

You can find more information on ALSA, including an HOWTO, on the web :
  http://alsa-project.org

The Advanced Linux Sound Architecture (ALSA) is still in beta, and may
change slightly until it reaches the 1.0 release. Thus, this libmikmod
version might not work with future versions of ALSA.

The version of the libmikmod ALSA driver coincides with the latest ALSA
release available when this version of libmikmod was released ; for the
3.1.7 release, these are alsa driver v0.3.2 and alsa C library v0.3.2.

If the sound comes out jerky, you can pass the "buffer=xx" option to the
driver, to tweak the ALSA settings. The default value (if this option is not
used) is 4 ; the slower your machine is, the greater this value has to be, but
the allowed range is 2 to 16. However, the ALSA generally finds good settings
for your configuration, so I doubt you'll have to use this option.


>> ENLIGHTENED SOUND DAEMON SPECIFIC INFORMATION
------------------------------------------------

The Enlightened Sound Daemon (EsounD) is still experimental and may
change a lot until it reaches the 1.0 release. Thus, this libmikmod version
might not work with future versions of EsounD.

You can find more information on EsounD on the web :
  http://www.tux.org/~ricdude/EsounD.html

The version of the libmikmod EsounD driver coincides with the latest EsounD
release available when this version of libmikmod was released ; for the
3.1.7 release, this is EsounD v0.2.12, but libmikmod should work with any
0.2.x version, although the latest version is recommended.

Please not that between 0.2.8 and 0.2.12 the server port and the protocol have
changed, thus clients compiled with libesd from 0.2.8 can not communicate with
0.2.12 esd, and vice versa.

If the esd daemon dies, libmikmod will try to reconnect every 5 seconds and
every new module, if a module ends. So, you can safely restart esd and
wait 5 seconds, and voila ! Sound is back...

If you run esd and a libmikmod application on the same machine, everything
should work fine. However, if there is a real network connection,
synchronization problems can occur.

If sound clicks or gets chopped, then you've likely got a synchronization
problem. Pausing the player for a second should cause the problem to
disappear.  If there's still problems, perhaps your network is not fast
enough. Lowering the playback rate will hopefully solve the problem.

Also, the performance of the esd is really abominable if the esd playback
frequency can't be divided by the libmikmod playback rate. For example,
runinng a libmikmod application at 42000 Hz with esd at 44100 Hz will sound
horrible, and take a lot of CPU time due to resampling.


>> SGI DRIVER SPECIFIC INFORMATION (IRIX specific)
----------------------------------

The SGI audio driver was written by Stephan Kanthak in 1996 and its author
grants to distribute it with the libmikmod package under the same restrictions
as the library.

If you encounter any problems concerning crackles or short stops while
playing, feel free to experiment with the values of the fragsize and bufsize
options of the driver. The default values are 20000 for fragsize and 40000 for
bufsize.  Increasing bufsize might result in nonstop sound on slow machines,
but increases latency of interactive applications. The value of fragsize should
be set to about half of bufsize in most cases and needs to be increased only if
you own a very slow SGI.

Common problems

- libmikmod does not compile on my SGI?
  First check out whether you have the SGI audio library (libaudio) or not.
  If the audio library is missing you should upgrade to IRIX 5.3 or newer
  and you will obtain the media development package automatically with it.
  If you have the audio library installed, check out if it is in the linker
  path.

- Sound is _very_ noisy?
  Change sample size to 16 bits.

- Sound crackles or stops temporarily?
  Try to increase the value of the fragsize driver option (default value is
  20000). Switch to mono mode if necessary.

- libmikmod applications only react very slowly?
  This is a typical effect on SGI machines because the audio library sets
  up an internal buffer that seems to be quite large on many installations.
  Try to decrease the bufsize driver option (default value is 40000).

How to contact the driver author

Stephan Kanthak
e-mail: kanthak@i6.informatik.rwth-aachen.de


>> SUNOS, SOLARIS, NETBSD AND OPENBSD DRIVER SPECIFIC INFORMATION
-----------------------------------------------------------------

The above mentioned systems use the same interface to the audio device. The
libmikmod driver for this interface is the Sun driver. It was coded by Valtteri
Vuorikoski <vuori@sci.fi> and updated to libmikmod 3 by Tor Norbye
<tor@cs.stanford.edu>, and has been modified to work under NetBSD and OpenBSD
by the current maintainer.

This driver works with old sound hardware using 8 KHz mono ulaw, and with
modern hardware using pcm mono or stereo at any frequency. If your settings
aren't supported by the audio device, sound initialization will fail. Refer
to the audio(7) man page under SunOS/Solaris and the audio(4) man page under
NetBSD/OpenBSD for more details on your audio hardware and its capabilities.

On Sun workstations, you might be interested in passing the "headphone" option
to the driver to force output on the headphones, since plugging the headphones
is not enough.

If sound is jerky, you can pass the "buffer=xx" option to the driver to
increase its internal buffer size. The default value (when this option is not
used) is 12 ; the slower your machine, the greater this value has to be, in the
range 7-17.

If you can't get libmikmod to work with your hardware, you can use its raw disk
writer driver, in 8 bit mono 8 kHz, and send the music.raw file to /dev/audio
with sox, using the following command line :
    sox -t raw -c 1 -r 8000 -u -b music.raw -t raw -U -r 8000 -c 1 -b /dev/audio
(or use the piped output driver with this command line)

Or if you played in 16 bit stereo, you can convert the file to a .au file :
  audioconvert -o music.au -f sun \
               -i rate=44.1k,channels=stereo,encoding=linear16 music.raw
and play the file :
    audioplay -p headphone -v 10 music.au

Legal notes

  Parts of the Sun driver have their roots in the SOX package by Lance Norskog
  and Jef Poskanzer, which include the following license :

  Sound Tools may be used for any purpose.  Source distributions must include
  the copyright notices.  Binary distributions must include acknowledgements
  to the creators.
  The files I wrote are copyright Lance Norskog.
  The contributed files are copyright by their respective authors.

  ** Copyright (C) 1989 by Jef Poskanzer.
  **
  ** Permission to use, copy, modify, and distribute this software and its
  ** documentation for any purpose and without fee is hereby granted, provided
  ** that the above copyright notice appear in all copies and that both that
  ** copyright notice and this permission notice appear in supporting
  ** documentation.  This software is provided "as is" without express or
  ** implied warranty.

  Fix to load_xm.c to play correctly on big-endian machines by
  Sebastiaan A. Megens <samegens@xs4all.nl>.

  Tighter integration with the rest of the Unix mikmod package by
  Steve McIntyre <stevem@chiark.greenend.org.uk>.


>> THANKS
---------

I would like to thank everyone who contributed to libmikmod. Their names
are in the AUTHORS file for the significative contributions, but some other
names can be found in the NEWS file. Thanks a lot ! Keeping libmikmod alive
wouldn't be much fun without you.


>> LICENSE
----------

The libmikmod sound library is covered by the GNU Library General Public
License as published by the Free Software Fundation (you'll find it in the
file COPYING.LIB) ; either version 2 of the licence, or (at your option)
any later version.

The GNU Lesser General Public License, version 2.1, in file COPYING.LESSER, can
be considered as a later version of the LGPL, and is strongly recommended for
people who will embed libmikmod in their application as a shared library.


>> CONTACT AND DOWNLOAD INFO
----------------------------

* email :
  Please send all your libmikmod related e-mail to me, at :
  miodrag@mikmod.darkorb.net

* chat :
  People wanting to have a ``live talk'' with me can reach me on IRC (IRCnet
  and sometimes Undernet) under the nick 'effetaipa'.

* web :
  libmikmod home page is located at :
    http://mikmod.darkorb.net
  The European mirror is at:
    http://www.multimania.com/miodrag/mikmod

* ftp :
  Latest releases of libmikmod can be found:
  - on the official ftp site
    ftp://mikmod.darkorb.net
  - on metalab (formerly known as sunsite) and its mirrors
    ftp://metalab.unc.edu/pub/Linux/apps/sound/libs
  - on hobbes, in source and OS/2 binary forms
    ftp://hobbes.nmsu.edu/pub/os2/mmedia


>> LAST NOTES
-------------

I hope you'll enjoy using this version of libmikmod as well as I enjoyed
debugging and improving it.

-- Miodrag ("Miod") Vallat, 06/28/1999
   miodrag@mikmod.darkorb.net
