readme

The source code of Doom legacy for windows

Musserver 1.4  (June 14, 1997)

	Michael Heasley
	[e-mail]


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),
	  FM synth device (Adlib, OPL3, etc), or AWE32/AWE64 card (this
	  requires the AWE32 kernel driver, found at
	  http://bahamut.mm.t.u-tokyo.ac.jp/~iwai/midi.html)
	- A version of Linux or FreeBSD capable of running Doom (SystemV
	  IPC support is required)
	- For general midi users: Voxware (USS) 2.9 and up
	  For FM synth users: Voxware (USS) 3.0.1 and up
	  (Voxware or USS 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).

Apparently some versions of FreeBSD can run musserver along with Doom.
Since I don't have FreeBSD, I've never tested this and can't tell you
any more.


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 as ELF under Linux 2.0.30, using gcc-2.7.2.1 and
libc-5.4.17.  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 change CFLAGS as well.
	- Edit musserver.h, if desired, to change musserver's default
	  behavior or add support for AWE32 cards.
	- 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 musserver 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 ([e-mail])

3.2. Installing the latest version of Voxware (USS)

Versions of Voxware (the kernel's sound driver, now known as USS) 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 (2.0.30 is recommended at
     the time of this update).  Voxware 3.0.1 or higher 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:

	- Checks to see if you've used the -file option with Doom, to load a
	  PWAD.  If so, it checks the PWAD(s) to see if there are music
	  entries, and plays the ones it finds.  The patch for this was done 
	  by Michael Bischoff ([e-mail]).
	- 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.
	- 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
	- Quits when the IPC message queue is removed (this occurs when
	  Doom exits normally)
	- Or quits when it appears that the Doom process no longer exists
	  (Doom exited abnormally)

4.2. Command line options

	-a
		Force use of the AWE32 synth device.  This option only works
		if you have compiled musserver with AWE32 support (see the
		user configurable section in musserver.h).

	-c
		Normally musserver periodically checks to see if its parent
		process (presumably Doom) is still alive.  If the parent
		process no longer exists (Doom died abnormally for some
		reason), musserver will normally exit.  Use the -c option to
		disable this feature.

	-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