1 Hello folks! 2 3 4This is libmikmod, version 3.3.11, a portable sound library for Unix 5and other systems. Check out the file 'NEWS' for more history information. 6 7 8>> BUILDING LIBMIKMOD 9--------------------- 10 11- If you're building libmikmod for Windows, refer to the 'README' file 12 located in the 'win32' subdirectory. 13 14- If you're building libmikmod for Mac OS X, refer to the 'README' file 15 located in the 'macosx' subdirectory. 16 17- If you're building libmikmod for Android, refer to the 'README' file 18 located in the 'android' subdirectory. 19 20- If you're building libmikmod for DOS, refer to the 'README' file 21 located in the 'dos' subdirectory. 22 23- If you're building libmikmod for OS/2, refer to the 'README' file 24 located in the 'os2' subdirectory. 25 26- If you're building libmikmod for AmigaOS, or its variants like MorphOS 27 or AROS, refer to the 'README' located in the 'amiga' subdirectory. 28 29- If you're building libmikmod for MacOS, refer to the 'README' file 30 located in the 'macintosh' subdirectory. 31 32- If you're building libmikmod for dreamcast, gp32 or psp platforms, 33 refer to the corresponding 'README' files located under the 'dc', 34 'gp32' or 'psp' subdirectory. 35 36- If you're building libmikmod under any other system which is not a 37 Unix flavour, then be warned that your platform is probably not 38 supported and that libmikmod will probably not build out of the box. 39 Drop us a note and we'll see what we can do for this situation. 40 41So you're on a good old Unix workstation, aren't you ? 42 43You'll need an ANSI C compiler to build libmikmod. If your system does 44not come with an ANSI C compiler, you might try the GNU C compiler, gcc. 45If you're building on a 32 bit architecture, your compiler must provide 46a 64 bit integer type (usually 'long long'). 47 48To prevent clobbering the sources, I recommend building libmikmod in an 49alternate directory, for example 'build': 50 51 mkdir build 52 cd build 53 54In this directory, run libmikmod's configure script: 55 56 ../configure 57 58The configure script will attempt to guess correct values for various 59system-dependent variables used during the build process, and will 60create appropriate Makefiles for proper compilation. 61 62If you're not familiar with configure scripts and their standard 63options, you can find more general information about them in the file 64INSTALL. 65 66The default behaviour of the configure script is to create both a static 67and a shared library, with as many drivers as possible, which are 68dynamically loaded whenever possible. However, it can be given several 69options to tweak your configuration of libmikmod: 70 71The --enable-af, --enable-alsa, --enable-esd, --enable-oss, 72--enable-sam9407 and --enable-ultra options will compile respectively 73the Digital AudioFile, Advanced Linux Sound Architecture (ALSA), 74Enlightened Sound Daemon, Open Sound System (OSS), sam9407 and Linux 75Ultrasound drivers. 76 77Since the configure script will search for the appropriate include files 78and libraries, to compile as much drivers as possible, these options are 79mostly useful in their negative form: 80 ../configure --disable-esd 81will configure libmikmod without the Enlightened Sound Daemon driver, 82even if all the necessary files for compiling are present on the 83system. 84 85The --enable-dl option enables the dynamic load of the alsa, esd and 86ultra drivers at runtime, if your systems support it. This option is 87enabled by default if the build system supports it, so it is more useful 88in its negative form: 89 ../configure --disable-dl 90will configure libmikmod without the dynamic loading facility. 91 92The --enable-threads option enables the creation of a thread-safe 93libmikmod library, if your system provides POSIX threads. This option is 94enabled by default, so it is more useful in its negative form: 95 ../configure --disable-threads 96will configure for a non thread-safe version of libmikmod. 97 98The --enable-shared and --enable-static options control whether a static 99library, a shared library or both should be built. 100 101The --enable-debug option creates a debug version of libmikmod. 102 103After you've successfully run configure, simply run 104 105 make 106 107to get all things build. Then, run 108 109 make install 110 111to have the library installed. Depending on where you choose to install 112it (using the --prefix= option to configure), you may need root 113privileges for this operation. 114 115 116>> DRIVER PARAMETERS 117-------------------- 118 119Until a good place to put this information is found, here is the list of 120parameters recognized by the drivers, as well as the driver alias list. 121When specifying multiple parameters, use a comma (,) to separate the 122different parameters, for example: somevalue=1,someothervalue=2 123 124- AudioFile (alias "audiofile") 125 machine= same syntax as the AUDIOFILE environment variable. 126 127- AIX ("AIX") [AIX only] 128 buffer= logarithmic size of the buffer, in the range 12-19. Default 129 is 15. 130 131- DART ("dart") [OS/2 only] 132 buffer= logarithmic fragment size, in the range 12-16. Default is 133 computed to a bit more than 1/4" of playback. 134 count= fragment count, in the range 2-8. Default is 2. 135 device= waveaudio device number, in the range 0-8. Default is 0 (use 136 default waveaudio device). 137 138- DirectX ("ds") [Win32 only] 139 buffer= logarithmic size of the buffer, in the range 12-19. Default 140 is 16. 141 globalfocus 142 always play music, even if the application has not the 143 focus. Required for full-screen applications. 144 145- EsounD ("esd") [Unix only] 146 machine= same syntax as the ESPEAKER environment variable. 147 148- HP ("hp") [HP-UX only] 149 buffer= logarithmic size of the buffer, in the range 12-19. Default 150 is 15. 151 headphone redirects the output to the headphone port. 152 153- MacOS ("mac") [MacOS only] 154 buffer= logarithmic size of the buffer, in the range 10-16. Default 155 is 12. 156 157- OS/2 MMPM ("os2") [OS/2 only] 158 buffer= logarithmic size of the buffer, in the range 12-16. Default 159 is computed to a bit more than 1/4" of playback. 160 device= waveaudio device number, in the range 0-8. Default is 0 (use 161 default waveaudio device). 162 163- OSS ("oss") [Unix only] 164 card= card number. Default is the card whose driver was loaded 165 first. 166 buffer= logarithmic fragment size, in the range 7-17. Default is 14. 167 Replaces the MM_FRAGSIZE environment variable, which is now 168 deprecated. 169 count= fragment count, in the range 2-255. Default is 16. 170 Replaces the MM_NUMFRAGS environment variable, which is now 171 deprecated. 172 173- Piped output ("pipe") [Unix only] 174 pipe= Pipe command (mandatory). 175 176- SGI audio library ("sgi") [IRIX only] 177 fragsize= buffer size for libmikmod internal use. 178 Replaces the MM_SGI_FRAGSIZE environment variable, which is 179 now deprecated. 180 bufsize= buffer size for the audio library. 181 Replaces the MM_SGI_BUFSIZE environment variable, which is 182 now deprecated. 183 184- Disk writers in raw and wav formats ("raw", "wav" and "aiff") 185 file= Output file name. Default is music.raw for the raw driver 186 and music.wav for the wav driver. 187 188- OpenBSD sndio ("sndio") [OpenBSD only] 189 buffer= logarithmic fragment size, in the range 7-17. Default is 12. 190 191- Sun/Solaris/NetBSD/OpenBSD audio ("audio") 192 [SunOS, Solaris, NetBSD, OpenBSD only] 193 buffer= logarithmic fragment size, in the range 7-17. Default is 12. 194 headphone on SunOS/Solaris only, redirects the output to the headphone 195 port. 196 speaker on SunOS/Solaris only, redirects the output to the speaker. 197 198- Linux sam9407-based soundcards ("sam9407") [Linux only] 199 card= card number. Default is first card. 200 201- NoSound ("nosound"), Standard output ("stdout"), Ultrasound ("ultra"), 202 Windows Multimedia ("winmm"), Windows XAudio2 ("xaudio2"), 203 Amiga AHI ("ahi"), Linux ALSA ("alsa") 204 These drivers have no options. 205 206 207>> ALSA DRIVER SPECIFIC INFORMATION (Linux specific) 208----------------------------------- 209 210The Advanced Linux Sound Architecture (ALSA) project aims to provide 211better sound facilities than the current OSS drivers. You can find 212more information on ALSA, including a HOWTO, on the web: 213 http://www.alsa-project.org 214 215This version of libmikmod ALSA driver works with ALSA versions 1.0.x. 216ALSA versions 0.9.x and earlier are not supported any more. 217 218 219>> ENLIGHTENED SOUND DAEMON SPECIFIC INFORMATION (Unix specific) 220------------------------------------------------ 221 222The Enlightened Sound Daemon (EsounD) development has long been stopped, 223but libmikmod still supports it. libmikmod should work with any esound 224version starting from 0.2.18, although the latest 0.2.41 is recommended: 225 http://ftp.gnome.org/pub/gnome/sources/esound/0.2/ 226 227You can find more information on EsounD on the web: 228 http://www.tux.org/~ricdude/EsounD.html 229 230If the esd daemon dies, libmikmod will try to reconnect every 5 seconds 231and every new module, if a module ends. So, you can safely restart esd 232and wait 5 seconds, and voila! Sound is back... 233 234If you run esd and a libmikmod application on the same machine, 235everything should work fine. However, if there is a real network 236connection, synchronization problems can occur. 237 238If sound clicks or gets chopped, then you've likely got a 239synchronization problem. Pausing the player for a second should cause 240the problem to disappear. If there's still problems, perhaps your 241network is not fast enough. Lowering the playback rate will hopefully 242solve the problem. 243 244Also, the performance of the esd is really abominable if the esd 245playback frequency can't be divided by the libmikmod playback rate. For 246example, runinng a libmikmod application at 42000 Hz with esd at 44100 247Hz will sound horrible, and take a lot of CPU time due to resampling. 248 249 250>> SGI DRIVER SPECIFIC INFORMATION (IRIX specific) 251---------------------------------- 252 253The SGI audio driver was written by Stephan Kanthak in 1996 and its 254author grants to distribute it with the libmikmod package under the same 255restrictions as the library. 256 257If you encounter any problems concerning crackles or short stops while 258playing, feel free to experiment with the values of the fragsize and 259bufsize options of the driver. The default values are 20000 for fragsize 260and 40000 for bufsize. Increasing bufsize might result in nonstop sound 261on slow machines, but increases latency of interactive applications. The 262value of fragsize should be set to about half of bufsize in most cases 263and needs to be increased only if you own a very slow SGI. 264 265Common problems 266 267- libmikmod does not compile on my SGI? 268 First check out whether you have the SGI audio library (libaudio) or 269 not. If the audio library is missing you should upgrade to IRIX 5.3 or 270 newer and you will obtain the media development package automatically 271 with it. If you have the audio library installed, check out if it is 272 in the linker path. 273 274 Also, the audio API has been extended in recent IRIX releases (6.4 and 275 later). The older API used by libmikmod is supposed to be still supported, 276 please drop me a note if it is not on your IRIX release. 277 278- Sound is _very_ noisy? 279 Change sample size to 16 bits. 280 281- Sound crackles or stops temporarily? 282 Try to increase the value of the fragsize driver option (default value 283 is 20000). Switch to mono mode if necessary. 284 285- libmikmod applications only react very slowly? 286 This is a typical effect on SGI machines because the audio library 287 sets up an internal buffer that seems to be quite large on many 288 installations. Try to decrease the bufsize driver option (default 289 value is 40000). 290 291How to contact the driver author: 292Stephan Kanthak <kanthak@i6.informatik.rwth-aachen.de> 293Please cc: me (miod), just in case. 294 295 296>> SUNOS, SOLARIS, NETBSD AND OPENBSD DRIVER SPECIFIC INFORMATION 297----------------------------------------------------------------- 298 299The above mentioned systems use the same interface to the audio device. 300The libmikmod driver for this interface is the Sun driver. It was coded 301by Valtteri Vuorikoski <vuori@sci.fi> and updated to libmikmod 3 by Tor 302Norbye <tor@cs.stanford.edu>, and has been modified to work under NetBSD 303and OpenBSD by Miodrag Vallat. 304 305This driver works with old sound hardware using 8 KHz mono ulaw, and 306with modern hardware using pcm mono or stereo at any frequency. If your 307settings aren't supported by the audio device, sound initialization will 308fail. Refer to the audio(7) man page under SunOS/Solaris and the 309audio(4) man page under NetBSD/OpenBSD for more details on your audio 310hardware and its capabilities. 311 312On Sun workstations, you might be interested in passing the "headphone" 313option to the driver to force output on the headphones, since plugging 314the headphones is not enough. 315 316If you run NetBSD or OpenBSD, the driver does not support the headphone 317and speaker parameters, but you can achieve the same effect with 318audioctl(1), for example: 319 audioctl -w play.port=1 320will select the speaker, while a value of 2 would have selected the 321headphone. 322 323If sound is jerky, you can pass the "buffer=xx" option to the driver to 324increase its internal buffer size. The default value (when this option 325is not used) is 12; the slower your machine, the greater this value has 326to be, in the range 7-17. 327 328If you can't get libmikmod to work with your hardware, you can use its 329raw disk writer driver, in 8 bit mono 8 kHz, and send the music.raw file 330to /dev/audio with sox, using the following command line: 331 sox -t raw -c 1 -r 8000 -u -b music.raw -t raw -U -r 8000 \ 332 -c 1 -b /dev/audio 333(or use the piped output driver with this command line) 334 335Or if you played in 16 bit stereo, you can convert the file to a .au 336file: 337 audioconvert -o music.au -f sun \ 338 -i rate=44.1k,channels=stereo,encoding=linear16 music.raw 339and play the file: 340 audioplay -p headphone -v 10 music.au 341 342 343>> SAM9407 DRIVER SPECIFIC INFORMATION (Linux specific) 344-------------------------------------- 345 346The SAM9407 driver provides an OSS-compatible driver for the soundcards 347based on the sam9407 audio chip (MaxiSound 64 and Terratec EWS, among 348others), and provides advanced features such as hardware module 349playback. 350 351You can find more information on this driver on the web: 352 http://www.anime.net/~sam9407 353 354The version of the libmikmod sam9407 driver coincides with the latest sam9407 355driver release available when this version of libmikmod was released; for the 3563.1.10 release, this is sam9407 driver v1.0.0. 357 358 359>> THANKS 360--------- 361 362I would like to thank everyone who contributed to libmikmod. Their names 363are in the AUTHORS file for the significative contributions, but some 364other names can be found in the NEWS file. Thanks a lot! Keeping 365libmikmod alive wouldn't be much fun without you. 366 367 368>> LICENSE 369---------- 370 371The libmikmod sound library is covered by the GNU Library General Public 372License as published by the Free Software Fundation (you'll find it in 373the file COPYING.LIB); either version 2 of the licence, or (at your 374option) any later version. 375 376The GNU Lesser General Public License, version 2.1, in file 377COPYING.LESSER, can be considered as a later version of the LGPL, and is 378strongly recommended for people who will embed libmikmod in their 379application as a shared library. 380 381Parts of the library (in playercode/mdulaw.c) are derived from the files 382libst.h and raw.c from an old version of the sox (SOund eXchange) 383package written by Lance Norskog and Jef Poskanzer. The following 384copyright notice applies to these parts: 385 386 Copyright (C) 1989 by Jef Poskanzer. 387 388 Permission to use, copy, modify, and distribute this software and its 389 documentation for any purpose and without fee is hereby granted, provided 390 that the above copyright notice appear in all copies and that both that 391 copyright notice and this permission notice appear in supporting 392 documentation. This software is provided "as is" without express or 393 implied warranty. 394 395 396>> CONTACT AND DOWNLOAD INFO 397---------------------------- 398 399libmikmod home page is located at SourceForge: 400 401 http://mikmod.sourceforge.net/ 402 http://sourceforge.net/projects/mikmod/ 403 404There's a mailing list (mikmod-public) for discussing the development 405of MikMod (new features, bugs, ideas...) Look for more information on 406the web site. 407 408