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