1Musserver 1.4 (June 14, 1997)
2
3 Michael Heasley
4 mheasley@hmc.edu
5
6
7Table of Contents
8=================
9
101. Introduction
112. System requirements
123. Installation
13 3.1. Installing the Doom executable patch
14 3.2. Installing the latest version of Voxware
154. Using musserver
16 4.1. What musserver does
17 4.2. Command line options
18 4.3. New .doomrc entry
195. Troubleshooting
20 5.1. Musserver error messages
21 5.2. Kernel error messages
22 5.3. If it still doesn't work...
236. Future enhancements
24 6.1. Known bugs
25 6.2. Other enhancements
267. Obtaining musserver and related packages
278. Acknowledgments
28
29
30
311. Introduction
32
33 When Linux Doom was originally released, the music support had been
34left out. Musserver, a companion to Id's sndserver, provides full music
35support for doom. Its behavior is similar to, if not indistinguishable from,
36that of the DOS version of Doom. Musserver plays the music for Doom via the
37/dev/sequencer interface. It automatically changes music whenever
38appropriate, and loops songs while the user is in a level. It also changes
39music volume according to the "MUSIC VOLUME" slider in Doom.
40
41 With previous versions of musserver, the user was required to manually
42send a command to musserver whenever music was supposed to change. This
43version fully integrates musserver with the Doom executable. A binary patch
44(written by Steffen Winterfeld) for the Doom executable allows Linux Doom to
45automatically notify musserver whenever the music selection or volume should
46change.
47
48
492. System requirements
50
51 In order to use this version of musserver, you must have the
52following:
53
54 - A general midi synth device (SB16 Midi, MPU-401, 6850 UART, etc),
55 FM synth device (Adlib, OPL3, etc), or AWE32/AWE64 card (this
56 requires the AWE32 kernel driver, found at
57 http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/midi.html)
58 - A version of Linux or FreeBSD capable of running Doom (SystemV
59 IPC support is required)
60 - For general midi users: Voxware (USS) 2.9 and up
61 For FM synth users: Voxware (USS) 3.0.1 and up
62 (Voxware or USS is the kernel's sound driver)
63 - Linux Doom version 1.8. The included Doom executable patch will
64 work only with this version of Doom. It may be used with or without
65 the Ultimate LinuxDoom patch (also by Steffen Winterfeld).
66
67Apparently some versions of FreeBSD can run musserver along with Doom.
68Since I don't have FreeBSD, I've never tested this and can't tell you
69any more.
70
71
723. Installation
73
74 To install the binary included in this package, simply copy it to the
75desired destination directory (i.e. 'cp musserver /usr/local/bin'). The
76binary was compiled as ELF under Linux 2.0.30, using gcc-2.7.2.1 and
77libc-5.4.17. To recompile the program, follow these steps:
78
79 - Edit the Makefile to your liking. You will probably only want to
80 change DESTDIR, but may want to change CFLAGS as well.
81 - Edit musserver.h, if desired, to change musserver's default
82 behavior or add support for AWE32 cards.
83 - Type 'make' to compile musserver, or 'make install' to compile and
84 install the program.
85
86Once you have finished all of the installation described in this section,
87please read section 4 carefully before using musserver.
88
893.1. Installing the Doom executable patch
90
91** NOTE: the patch has not changed since musserver version 0.98. If you have
92** already installed it, you need not do so again.
93
94This version of musserver includes a linuxdoom patch (file doompat.tgz) that
95allows full integration of musserver into the doom executable. In other
96words, this patch allows Doom to communicate with musserver, automating music
97changes. Follow these steps to install the patch:
98
99 1. Make sure you have version 1.8 of Linux Doom. It is available at
100 sunsite.unc.edu and mirrors, under the games directory. This patch will
101 not work with previous versions of Linux Doom. It is, however, fully
102 compatible with the recently released Ultimate LinuxDoom patch.
103 2. Make a backup of your current doom executable(s)
104 3. Unpack the patch into a directory containing the doom executable(s)
105 4. Edit the included shell script (file muspat) and run it. The script
106 assumes the executables are named xdoom (X version) and sdoom (SVGA
107 version). You may want to change these. If no errors appear, the patch
108 should have applied correctly.
109
110The patch was done by Steffen Winterfeld (wfeldt@tph100.physik.uni-leipzig.de)
111
1123.2. Installing the latest version of Voxware (USS)
113
114Versions of Voxware (the kernel's sound driver, now known as USS) before 3.0.1
115had a small bug in FM pitch bending. Previous versions of musserver were
116distributed with a kernel patch to fix this bug. This patch is no longer
117necessary or supported by the author, now that Voxware 3.0.1 fixes the bug.
118Instead, you are encouraged to upgrade your version of Voxware to 3.0.1 or
119later if you wish to use musserver with an FM synth device. There are two
120basic ways to do this:
121
122 1. Install and compile kernel 1.3.18 or later (2.0.30 is recommended at
123 the time of this update). Voxware 3.0.1 or higher comes standard in
124 these kernels.
125 2. Merge Voxware 3.0.1 into your existing kernel source tree, then
126 recompile and install that kernel. To do so, follow these basic steps:
127 a. From the base linux source directory (usually /usr/src/linux),
128 rename the drivers/sound directory to something else
129 (ie, 'mv drivers/sound drivers/sound.old').
130 b. From the drivers subdirectory, unpack the Voxware 3.0.1 archive
131 (ie, 'cd drivers; tar xzvf VoxWare-3.0.1.tar.gz'). This should
132 put Voxware 3.0.1 in the proper place under the linux source tree.
133 c. Recompile and install your kernel as usual.
134
135** NOTE: Voxware 3.0.1 is not required for general midi users. If you have
136** at least version 2.9, and use general midi, do not worry about this part.
137** You can check your version of Voxware by looking at the first line of
138** output from 'cat /dev/sndstat'
139
140
1414. Using musserver
142
1434.1. What musserver does
144
145 In its normal mode of operation musserver does the following:
146
147 - Checks to see if you've used the -file option with Doom, to load a
148 PWAD. If so, it checks the PWAD(s) to see if there are music
149 entries, and plays the ones it finds. The patch for this was done
150 by Michael Bischoff (mbi@mo.math.nat.tu-bs.de).
151 - Waits until an IPC message queue has been created by Doom, then
152 obtains the queue id. Use the -t option to set the timeout for
153 this.
154 - Waits for IPC messages from Doom, telling it what music to play
155 - Loops music while in a level
156 - Changes music upon receiving a SystemV IPC message from Doom that
157 contains the name of a valid music resource
158 - Changes music volume upon receiving an appropriate IPC message
159 from Doom
160 - Quits upon receiving any one of SIGTERM, SIGQUIT, SIGINT, SIGKILL
161 - Quits when the IPC message queue is removed (this occurs when
162 Doom exits normally)
163 - Or quits when it appears that the Doom process no longer exists
164 (Doom exited abnormally)
165
1664.2. Command line options
167
168 -a
169 Force use of the AWE32 synth device. This option only works
170 if you have compiled musserver with AWE32 support (see the
171 user configurable section in musserver.h).
172
173 -c
174 Normally musserver periodically checks to see if its parent
175 process (presumably Doom) is still alive. If the parent
176 process no longer exists (Doom died abnormally for some
177 reason), musserver will normally exit. Use the -c option to
178 disable this feature.
179
180 -d directory
181 Look in 'directory' for the Doom wad file. Ordinarily,
182 musserver uses the same rules as Doom for finding the wad
183 file and thus the appropriate Doom version. It uses the
184 environment variable "DOOMWADDIR" if present, otherwise it
185 uses the current working directory. The -d option overrides
186 both of these.
187
188 -f
189 Force use of FM synth device for music playback. This is
190 sounding much better than in previous versions. Use this
191 if your soundcard has both midi and FM devices, but nothing
192 attached to the midi device.
193
194 -h
195 Print a help message and exit.
196
197 -l
198 List detected music devices and exit. If used in conjunction
199 with the -m option, musserver will only list detected midi
200 devices. Similarly, it will only list FM synth devices if the
201 -f option is specified.
202
203 -m
204 Use general midi device for music playback. If both FM and
205 general midi devices are detected, musserver will use the
206 midi device by default. If only one or the other is
207 detected, musserver will use that one. If more than one
208 device of either type is detected, the last one detected will
209 be given highest priority.
210
211 -t number
212 Cause musserver to timeout after 'number' seconds while
213 waiting to get the IPC message queue id. Default is 300.
214
215 -u number
216 Use device of type 'number' where 'number is the device type
217 reported by 'musserver -l'. This must be used in conjunction
218 with either the -f option or the -m option. For example,
219 'musserver -m -u 7' would use midi device type 7 if it exists.
220 If no device of the specified type is detected, musserver
221 prints an error message and exits.
222
223 -V
224 Ignore volume change messages from Doom. Use this if you have
225 an FM synth card, and mixer functions are not supported for
226 it. This should not be necessary for most cards. But I know
227 of one case where volume changes do not work with a Windows
228 Sound System card.
229
230 -v
231 Verbose mode. Prints status messages while detecting music
232 hardware and playing music. Specify this option more than
233 once to get even more output.
234
2354.3. New .doomrc entry
236
237 One important feature of the new doom patch is new entry in the
238$HOME/.doomrc file, describing what program to use as the music server. The
239entry is very similar to that for sndserver. The default entry follows:
240
241musserver "musserver"
242
243This will be automatically added to your $HOME/.doomrc the first time you run
244the patched doom program. Just as with the sndserver entry, you can change the
245string in quotes to specify the full pathname to the musserver program.
246
247If you currently require any command line options to run musserver, you may be
248able to specify new default behavior by editing musserver.h. Make any changes
249based on the instructions given in the comments, then recompile musserver by
250doing a 'make clean;make'.
251
252If this is not sufficient, I suggest you put your needed options in a small
253shell script. For example:
254
255#!/bin/sh
256exec /usr/local/bin/musserver.bin -f -u 3
257
258Install the musserver binary as /usr/local/bin/musserver.bin, and install the
259shell script as /usr/local/bin/musserver. Of course you can change the
260pathnames to suit your needs. One important note: if you do not use "exec"
261in the shell script to execute musserver, it will be unable to check to make
262sure Doom hasn't died unexpectedly (see the description of the -c option for
263more on this behavior).
264
265
2665. Troubleshooting
267
2685.1. Musserver error messages
269
270These messages are all prefixed by the string "musserver: "
271
272 * game mode indeterminate.
273
274 This means that musserver cannot find a wadfile to use. As with
275 Doom, you must tell it where to look for the wadfile (either use the
276 environment variable DOOMWADDIR or the current directory)
277
278 * could not get IPC message queue id, exiting.
279
280 No IPC message queue has been created during a specified waiting
281 period. Normally the patched Doom executable is responsible for
282 creating the queue, at which time musserver gets the queue id and
283 continues. The default waiting period is 300 seconds. It may be
284 changed with the -t option.
285
286 * unknown error in music playing, exiting.
287
288 This message occurs when the function that actually plays music exits
289 with an unknown return value. It should never happen.
290
291 * unrecognized music entry (D_j)
292
293 Music resource names in the Doom wadfiles all begin with "D_". Some
294 versions of the Doom wadfiles contain resources beginning with this
295 string, but containing no music. In general these are very harmless.
296 "D_j" is one, and "D_." is another common one.
297
298 * could not allocate %d bytes for music data, exiting.
299
300 %d represents the size in bytes of the current music data lump. This
301 message indicates that your system is nearly out of virtual memory.
302 Typical data sizes are around 30 kbytes.
303
304 * couldn't find GENMIDI entry in wadfile, exiting.
305
306 This indicates that you have a corrupted wadfile. All Doom wadfiles
307 should contain the GENMIDI entry, which has FM synth patches.
308
309 * no music devices found, exiting.
310
311 This means that either no music hardware exists on your system, or
312 your kernel is not configured for music hardware. Consult the
313 Voxware documentation (probably in /usr/src/linux/drivers/sound) for
314 information on recompiling a kernel with music hardware support.
315 This could also mean that you are missing the device file
316 /dev/sequencer. Again, consult the Voxware documentation.
317
318 * could not open /dev/sndstat, exiting.
319
320 Musserver uses /dev/sndstat to check the Voxware version. Check the
321 Voxware documentation on how to properly setup this and the other
322 sound device files.
323
3245.2. Kernel error messages
325
326 * volume change: Invalid argument
327
328 For some reason, the mixer functions of your soundcard are not
329 supported. This could be due to an improperly compiled sound driver
330 in your kernel, or Voxware may not currently support your card's
331 mixer functions (if they exist). You may need to use the -V option
332 to eliminate these error messages (see section 4.2 for more).
333
334 * volume change: Bad file number
335
336 This will occur when you are in FM synth mode and the device file
337 /dev/mixer does not exist. Consult the Voxware documentation to
338 properly create it.
339
340I'm sure there are many other possible kernel error messages, but none have
341been brought to my attention.
342
3435.3. If it still doesn't work...
344
345This section outlines my suggested procedure for determining the cause of a
346problem when musserver will not work.
347
348 1. Run "musserver -l" to list detected music devices. Musserver will
349 normally use the last music device detected, unless told otherwise by
350 command line options. Your problem may be that musserver is trying to
351 use a device to which nothing is attached. For example, the SB16 has a
352 FM synth chip and a MIDI interface. By default musserver will choose the
353 MIDI interface. But if you have nothing attached to it, you'll need to
354 use the -f option to tell musserver to use the FM synth chip instead.
355 This also applies if you have more than one FM or MIDI device. In this
356 case, you may need the -u option to specify the device type to use.
357 2. If you found your problem in step 1, you'll need to create a shell script
358 to pass the required options to musserver (or edit musserver.h to set the
359 default options). This is detailed in section 4.3.
360 3. Make sure the synth volume is up on your soundcard's mixer. You may
361 use any mixer program, such as setmixer or xmix.
362 4. If it still doesn't work, try creating a shell script (as in section 4.3)
363 that adds the option -vv (that's right, two v's: verbosity level of 2)
364 to musserver's command line. Then run Doom, redirecting the output to a
365 file. You should be able to tell from this whether musserver and Doom
366 are communicating properly. If you can't figure out the problem from
367 this, send me the output and I'll try to help. Along with this output,
368 please include the output from 'cat /dev/sndstat' so I'll have
369 information about your kernel and hardware.
370 5. GUS is not supported in this release. The Linux Ultra Sound Project
371 (http://www.pf.jcu.cz/~perex/ultra) has ported musserver 1.0 to use
372 their GUS kernel driver. See their web page for details. I plan to
373 merge their changes into this version of musserver sometime in the
374 future.
375 6. If pitch bending does not seem to work in FM synth mode, see section 3.2.
376 7. If you have an AWE32 or AWE64 card, be sure you have the awedrv kernel
377 driver (http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/midi.html) and you have
378 recompiled musserver with AWE32_SYNTH_SUPPORT defined in musserver.h.
379
380
3816. Future enhancements
382
3836.1. Known bugs that may or may not be fixed:
384
385 - None (that doesn't mean there aren't any bugs).
386
3876.2. Other enhancements
388
389 - Fix FM synth playback. Getting closer, but still not quite perfect. The
390 remaining items to be fixed are main volume and panning. I've talked to
391 Hannu Savolainen, the Voxware author, and he says these are not supported
392 in the current kernel sound driver.
393 - Currently, volume changes in FM synth mode are accomplished by changing
394 the synth volume in the mixer. This should really be accomplished via
395 midi main volume events (as they are in general midi mode), but this has
396 not been implemented in the kernel sound driver. See above.
397 - Add support for MPU-401 intelligent mode. Again, I don't have a MPU-401,
398 making debugging difficult.
399 - Add support for a configuration file ($HOME/.musserverrc), thus
400 eliminating the need for a shell script (as in section 4.3). Maybe not,
401 now that defaults can be changed easily at compile-time.
402 - Update when a new version of Voxware (USS) comes out. Add code to detect
403 the Voxware (USS) version and then act accordingly.
404 - Code cleanup, optimization, etc
405 - More error checking, fault tolerance, etc
406 - This README always needs revision...
407 - Other suggestions are welcome
408
409
4107. Obtaining musserver and related packages
411
412Musserver:
413 ftp://sunsite.unc.edu/pub/Linux/games/doom/musserver.tgz
414 ftp://ftp.cdrom.com/pub/idgames/utils/linux/musserver.tgz
415 http://www3.hmc.edu/~mheasley/musserver.tgz
416
417The first 2 sites only contain the latest "official" release; the last one
418should always contain the very latest version.
419
420Voxware 3.0.1:
421 ftp.funet.fi /pub/OS/Linux/util/sound/snd-kit/VoxWare-3.0.1.tar.gz
422 sunsite.unc.edu /pub/Linux/kernel/sound/VoxWare-3.0.1.tar.gz
423
424Doom 1.8:
425 sunsite.unc.edu /pub/Linux/games/doom/linux[s,x]doom.tar.gz
426 ftp.cdrom.com /pub/idgames/idstuff/linux/linux[s,x]doom.tar.gz
427
428
4298. Acknowledgments
430
431 I would like to thank the following people for their (in)direct
432contributions to musserver:
433
434 - Id Software for Doom
435 - Dave Taylor for porting Doom to Linux
436 - Steffen Winterfeld for the doom executable patch
437 - Michael Bischoff for the external PWAD patch
438 - Hannu Savolainen for the Voxware driver
439 - Nathan Laredo for playmidi 1.1 and 2.2 (I learned a lot
440 about how to use /dev/sequencer from
441 playmidi's code)
442 - Vladimir Arnost for documentation on the MUS file format
443 - Matthew S Fell for the Unofficial Doom Specs
444 - Takashi Iwai for the AWE32 driver and patch to musserver
445 - Of course, the whole Linux crowd for Linux
446
447
448
449Please email me with any questions, bug reports/fixes, or comments.
450
451 Michael Heasley
452 mheasley@hmc.edu
453