forgot to undef the debugging NOKEYB macro
[dosdemo] / libs / mikmod / README
1   Hello folks!
2
3
4 This is libmikmod, version 3.3.10, a portable sound library for Unix
5 and 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
41 So you're on a good old Unix workstation, aren't you ?
42
43 You'll need an ANSI C compiler to build libmikmod.  If your system does
44 not come with an ANSI C compiler, you might try the GNU C compiler, gcc.
45 If you're building on a 32 bit architecture, your compiler must provide
46 a 64 bit integer type (usually 'long long').
47
48 To prevent clobbering the sources, I recommend building libmikmod in an
49 alternate directory, for example 'build':
50
51   mkdir build
52   cd build
53
54 In this directory, run libmikmod's configure script:
55
56   ../configure
57
58 The configure script will attempt to guess correct values for various
59 system-dependent variables used during the build process, and will
60 create appropriate Makefiles for proper compilation.
61
62 If you're not familiar with configure scripts and their standard
63 options, you can find more general information about them in the file
64 INSTALL.
65
66 The default behaviour of the configure script is to create both a static
67 and a shared library, with as many drivers as possible, which are
68 dynamically loaded whenever possible. However, it can be given several
69 options to tweak your configuration of libmikmod:
70
71 The --enable-af, --enable-alsa, --enable-esd, --enable-oss,
72 --enable-sam9407 and --enable-ultra options will compile respectively
73 the Digital AudioFile, Advanced Linux Sound Architecture (ALSA),
74 Enlightened Sound Daemon, Open Sound System (OSS), sam9407 and Linux
75 Ultrasound drivers.
76
77 Since the configure script will search for the appropriate include files
78 and libraries, to compile as much drivers as possible, these options are
79 mostly useful in their negative form:
80   ../configure --disable-esd
81 will configure libmikmod without the Enlightened Sound Daemon driver,
82 even if all the necessary files for compiling are present on the
83 system.
84
85 The --enable-dl option enables the dynamic load of the alsa, esd and
86 ultra drivers at runtime, if your systems support it. This option is
87 enabled by default if the build system supports it, so it is more useful
88 in its negative form:
89   ../configure --disable-dl
90 will configure libmikmod without the dynamic loading facility.
91
92 The --enable-threads option enables the creation of a thread-safe
93 libmikmod library, if your system provides POSIX threads. This option is
94 enabled by default, so it is more useful in its negative form:
95   ../configure --disable-threads
96 will configure for a non thread-safe version of libmikmod.
97
98 The --enable-shared and --enable-static options control whether a static
99 library, a shared library or both should be built.
100
101 The --enable-debug option creates a debug version of libmikmod.
102
103 After you've successfully run configure, simply run
104
105   make
106
107 to get all things build. Then, run
108
109   make install
110
111 to have the library installed. Depending on where you choose to install
112 it (using the --prefix= option to configure), you may need root
113 privileges for this operation.
114
115
116 >> DRIVER PARAMETERS
117 --------------------
118
119 Until a good place to put this information is found, here is the list of
120 parameters recognized by the drivers, as well as the driver alias list.
121 When specifying multiple parameters, use a comma (,) to separate the
122 different 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
210 The Advanced Linux Sound Architecture (ALSA) project aims to provide
211 better sound facilities than the current OSS drivers. You can find
212 more information on ALSA, including a HOWTO, on the web:
213   http://www.alsa-project.org
214
215 This version of libmikmod ALSA driver works with ALSA versions 1.0.x.
216 ALSA versions 0.9.x and earlier are not supported any more.
217
218
219 >> ENLIGHTENED SOUND DAEMON SPECIFIC INFORMATION (Unix specific)
220 ------------------------------------------------
221
222 The Enlightened Sound Daemon (EsounD) development has long been stopped,
223 but libmikmod still supports it.  libmikmod should work with any esound
224 version 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
227 You can find more information on EsounD on the web:
228   http://www.tux.org/~ricdude/EsounD.html
229
230 If the esd daemon dies, libmikmod will try to reconnect every 5 seconds
231 and every new module, if a module ends. So, you can safely restart esd
232 and wait 5 seconds, and voila! Sound is back...
233
234 If you run esd and a libmikmod application on the same machine,
235 everything should work fine. However, if there is a real network
236 connection, synchronization problems can occur.
237
238 If sound clicks or gets chopped, then you've likely got a
239 synchronization problem. Pausing the player for a second should cause
240 the problem to disappear.  If there's still problems, perhaps your
241 network is not fast enough. Lowering the playback rate will hopefully
242 solve the problem.
243
244 Also, the performance of the esd is really abominable if the esd
245 playback frequency can't be divided by the libmikmod playback rate. For
246 example, runinng a libmikmod application at 42000 Hz with esd at 44100
247 Hz will sound horrible, and take a lot of CPU time due to resampling.
248
249
250 >> SGI DRIVER SPECIFIC INFORMATION (IRIX specific)
251 ----------------------------------
252
253 The SGI audio driver was written by Stephan Kanthak in 1996 and its
254 author grants to distribute it with the libmikmod package under the same
255 restrictions as the library.
256
257 If you encounter any problems concerning crackles or short stops while
258 playing, feel free to experiment with the values of the fragsize and
259 bufsize options of the driver. The default values are 20000 for fragsize
260 and 40000 for bufsize. Increasing bufsize might result in nonstop sound
261 on slow machines, but increases latency of interactive applications. The
262 value of fragsize should be set to about half of bufsize in most cases
263 and needs to be increased only if you own a very slow SGI.
264
265 Common 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
291 How to contact the driver author:
292 Stephan Kanthak <kanthak@i6.informatik.rwth-aachen.de>
293 Please cc: me (miod), just in case.
294
295
296 >> SUNOS, SOLARIS, NETBSD AND OPENBSD DRIVER SPECIFIC INFORMATION
297 -----------------------------------------------------------------
298
299 The above mentioned systems use the same interface to the audio device.
300 The libmikmod driver for this interface is the Sun driver. It was coded
301 by Valtteri Vuorikoski <vuori@sci.fi> and updated to libmikmod 3 by Tor
302 Norbye <tor@cs.stanford.edu>, and has been modified to work under NetBSD
303 and OpenBSD by Miodrag Vallat.
304
305 This driver works with old sound hardware using 8 KHz mono ulaw, and
306 with modern hardware using pcm mono or stereo at any frequency. If your
307 settings aren't supported by the audio device, sound initialization will
308 fail. Refer to the audio(7) man page under SunOS/Solaris and the
309 audio(4) man page under NetBSD/OpenBSD for more details on your audio
310 hardware and its capabilities.
311
312 On Sun workstations, you might be interested in passing the "headphone"
313 option to the driver to force output on the headphones, since plugging
314 the headphones is not enough.
315
316 If you run NetBSD or OpenBSD, the driver does not support the headphone
317 and speaker parameters, but you can achieve the same effect with
318 audioctl(1), for example:
319   audioctl -w play.port=1
320 will select the speaker, while a value of 2 would have selected the
321 headphone.
322
323 If sound is jerky, you can pass the "buffer=xx" option to the driver to
324 increase its internal buffer size. The default value (when this option
325 is not used) is 12; the slower your machine, the greater this value has
326 to be, in the range 7-17.
327
328 If you can't get libmikmod to work with your hardware, you can use its
329 raw disk writer driver, in 8 bit mono 8 kHz, and send the music.raw file
330 to /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
335 Or if you played in 16 bit stereo, you can convert the file to a .au
336 file:
337   audioconvert -o music.au -f sun \
338                -i rate=44.1k,channels=stereo,encoding=linear16 music.raw
339 and play the file:
340     audioplay -p headphone -v 10 music.au
341
342
343 >> SAM9407 DRIVER SPECIFIC INFORMATION (Linux specific)
344 --------------------------------------
345
346 The SAM9407 driver provides an OSS-compatible driver for the soundcards
347 based on the sam9407 audio chip (MaxiSound 64 and Terratec EWS, among
348 others), and provides advanced features such as hardware module
349 playback.
350
351 You can find more information on this driver on the web:
352   http://www.anime.net/~sam9407
353
354 The version of the libmikmod sam9407 driver coincides with the latest sam9407
355 driver release available when this version of libmikmod was released; for the
356 3.1.10 release, this is sam9407 driver v1.0.0.
357
358
359 >> THANKS
360 ---------
361
362 I would like to thank everyone who contributed to libmikmod. Their names
363 are in the AUTHORS file for the significative contributions, but some
364 other names can be found in the NEWS file. Thanks a lot! Keeping
365 libmikmod alive wouldn't be much fun without you.
366
367
368 >> LICENSE
369 ----------
370
371 The libmikmod sound library is covered by the GNU Library General Public
372 License as published by the Free Software Fundation (you'll find it in
373 the file COPYING.LIB); either version 2 of the licence, or (at your
374 option) any later version.
375
376 The GNU Lesser General Public License, version 2.1, in file
377 COPYING.LESSER, can be considered as a later version of the LGPL, and is
378 strongly recommended for people who will embed libmikmod in their
379 application as a shared library.
380
381 Parts of the library (in playercode/mdulaw.c) are derived from the files
382 libst.h and raw.c from an old version of the sox (SOund eXchange)
383 package written by Lance Norskog and Jef Poskanzer. The following
384 copyright 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
399 libmikmod home page is located at SourceForge:
400
401     http://mikmod.sourceforge.net/
402     http://sourceforge.net/projects/mikmod/
403
404 There's a mailing list (mikmod-public) for discussing the development
405 of MikMod (new features, bugs, ideas...) Look for more information on
406 the web site.
407