Libmikmod

Hello folks!

This is libmikmod, version 3.2.0-beta1, a portable sound library for Unix and other systems. Check out the file 'NEWS' for more history information.

BETA WARNING

---

This is a beta version of libmikmod. Although it should work fine on almost all systems, there are likely a few last-minute errors or typos in the source, and some parts have not received enough hours of testing yet.

Also, please note that all features planned for the final 3.2.0 release are not available yet. Some structures or functions may change. This release is mainly intended to the libmikmod developers to share a common base for adding new features...

The library programming documentation (in docs/) is mostly up-to-date... It lacks the Player_QueryVoices documentation, though.

If you're not scared, then you can proceed and enjoy fewer bugs than in the previous version (-;

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 I 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 your system does not come with an ANSI C compiler, you might want to try the GUN C compiler, gcc. 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, --enable-sam9407 and --enable-ultra options will compile respectively the Digital AudioFile, Advanced Linux Sound Architecture (ALSA), Enlightened Sound Daemon, Open Sound System (OSS), sam9407 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.

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. When specifying multiple parameters, use a comma (,) to separate the different parameters, for example: somevalue=1,someothervalue=2

• AudioFile (alias "audiofile") machine= same syntax as the AUDIOFILE environment variable.

• AIX ("AIX") [AIX only] buffer= logarithmic size of the buffer, in the range 12-19. Default is 15.

• ALSA ("alsa") [Linux only] 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 variable, 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.

• DART ("dart") [OS/2 only] buffer= logarithmic fragment size, in the range 12-16. Default is computed to a bit more than 1/4" of playback. count= fragment count, in the range 2-8. Default is 2. device= waveaudio device number, in the range 0-8. Default is 0 (use default waveaudio device).

• DirectX ("ds") [Win32 only] buffer= logarithmic size of the buffer, in the range 12-19. Default is 16. globalfocus always play music, even if the application has not the focus. Required for full-screen applications.

• EsounD ("esd") [Unix only] machine= same syntax as the ESPEAKER environment variable.

• HP ("hp") [HP-UX only] buffer= logarithmic size of the buffer, in the range 12-19. Default is 15. headphone redirects the output to the headphone port.

• MacOS ("mac") [MacOS only] buffer= logarithmic size of the buffer, in the range 10-16. Default is 12.

• OS/2 MMPM ("os2") [OS/2 only] buffer= logarithmic size of the buffer, in the range 12-16. Default is computed to a bit more than 1/4" of playback. device= waveaudio device number, in the range 0-8. Default is 0 (use default waveaudio device).

• OSS ("oss") [Unix only] card= card number. Default is the card whose driver was loaded first. 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.

• Piped output ("pipe") [Unix only] pipe= Pipe command (mandatory).

• SGI audio library ("sgi") [IRIX only] 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.

• 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.

• Sun/Solaris/NetBSD/OpenBSD audio ("audio") [SunOS, Solaris, NetBSD, OpenBSD only] 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. speaker on SunOS/Solaris only, redirects the output to the speaker.

• Linux sam9407-based soundcards ("sam9407") [Linux only] card= card number. Default is first card.

• NoSound ("nosound"), 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://www.alsa-project.org

The Advanced Linux Sound Architecture (ALSA) is still in beta, but its API is stable, so this libmikmod version should work with future versions of ALSA.

This version of the libmikmod ALSA driver works with either ALSA versions 0.3.x (for Linux kernels 2.0.x) and 0.4.x (for Linux kernels 2.2.x and later). The latest versions, 0.5.x and 0.9.x, are currently not supported natively, although you can use the OSS emulation without problems.

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 (Unix specific)

---

The Enlightened Sound Daemon (EsounD) is still experimental and may change a lot until it reaches the 1.0 release. Thus, this libmikmod ve