+----------------------------------------+
| The Official Quake Deathmatch TEST     |
| Released Saturday, February 24th, 1996 |
| Copyright (C) 1996 id Software, inc.   |
+----------------------------------------+
| Sound Subsystem Documentation          |
| by Dave Taylor                         |
+----------------------------------------+

For DOS Box Quake to get the correct settings for DMA channel and PORT
address, you must set your BLASTER environment variable (or have it set
for you with the DIAGNOSE utility in your SB16 directory).  If you do
not have the BLASTER environment variable set, your sound will not work.
If your sound card supports Sound Blaster compatibility, Windows 95
should set this variable for you.

If (when) you see bugs, please use the form attached to the end
of these docs to submit a bug report.  Bugs submitted properly to
quake@idsoftware.com with this form will get attention.  Unformatted
ones sent to personal accounts will be ignored.  If you see problems,
please take the time to do this.  It will help the final game will come
out faster.

DMA-style Sound Card Command Line Options, Commands, and Variables
==================================================================

DMA-style sound cards are the most common sound cards available.
They include almost everything on the market as of this demo release.
They play sounds by transferring memory over the system bus via DMA
directly to a digital-to-analog converter, filter, and amplifier, which
goes to your speakers or headphones.  The commands and variables below
apply to these cards but may appear for other styles of sound card later.
These commands work under any operating system.  Command-Line options
are typed on the command line in most any place but only in operating
systems which support command line interfaces, like DOS's COMMAND.COM,
or NEXTSTEP's or Linux's csh, sh, or bash.  For example, under DOS,
the NOSOUND option would be used like this: "C:> quake -nosound".

Command-Line Options
--------------------

NOSOUND
  Syntax: -nosound
  Description: Not to be confused with the NOSOUND variable specified
    below, this will prevent *any* sound code from being executed.  If
	you are having technical difficulty with the game and then try
	running the game with this option and the problem goes away, then
	the problem is probably somewhere in the sound code.

SIMSOUND
  Synxtax: -simsound
  Description: This runs all the sound code, except for the hardware
    code.  In other words, it is loading, mixing the sound effects, doing
	the whole nine yards, and it creates a virtual sound card which
	appears to be playing back sounds, but it is completely fake.
	This is a good way to isolate problems with just the hardware-related
	parts of the sound code.

SSPEED
  Syntax: -sspeed <speed>
  Description: This will ask the sound code to set the playback speed
    within the constraints of the capabilities of the card.  This is
	22050 Hz by default and usually from 8000 to 44100.  Making this
	faster does require more CPU horsepower.

SBITS
  Syntax: -sbits <sample bits, 8 or 16>
  Description: This will ask the sound code to set the size of the samples
    within the constraints of the capabilities of the sound card.  This is
	16 bits by default.  If your card can support 16, leave it be.  It's
	free on the CPU and sounds better.

SMONO
  Syntax: -smono
  Description: This will ask the sound code to do mono playback.  This
    doesn't sound so bad, it might be all your sound card supports.
	The default is stereo.

Commands
--------

PLAY
  Syntax: play <sound effect relative pathname> ...
  Description: Will play a sound effect at 100% volume at the location of
    the player.  The sound effect must be a WAV (RIFF) file or an
    AIFF file.  If a WAV file, the sound effect may have a cue list.
    The first cue in that list will be interpreted as a loop startpoint,
    and the loop endpoint will be the end of the sound effect.  Sound
	effects may be recorded at any speed and may be either 8-bit or 16-bit.
	If you specify more than one sound effect on the line, they will play
	simultaneously.  If a specified sound effect is not already loaded into
	memory, it will first be loaded from disk.
  Demo Examples: play american/grenade.wav nin/slimbrn2.wav
                 play american/gib.wav

PLAYVOL
  Syntax: playvol <sound effect relative pathname> <volume 0.0-1.0> ...
  Description: Will play a sound effect at specified volume at the location
  	of the player.  The sound effect must be a WAV (RIFF) file or an
    AIFF file.  If a WAV file, the sound effect may have a cue list.
    The first cue in that list will be interpreted as a loop startpoint,
    and the loop endpoint will be the end of the sound effect.  Sound
	effects may be recorded at any speed and may be either 8-bit or 16-bit.
	If you specify more than one sound effect on the line, they will play
	simultaneously.  If a specified sound effect is not already loaded into
	memory, it will first be loaded from disk.
  Demo Examples: playvol american/grenade.wav 0.5 nin/slimbrn2.wav 0.7
                 playvol american/gib.wav 0.9

SOUNDLIST
  Syntax: soundlist
  Description: Will list all the currently cached (loaded) sound effects.
    Each entry will contain the last 11 characters of the filename,
	followed by the length of the sound in bytes, the # of bits in each
	sample (either 8b or 16b), then the speed of the recording (usually
	between 11025 and 44100).  At the end of the list will be the total
	memory usage by all cached sound effects.  If you are experiencing
	memory shortages, experiment with the DECIMATE_SFX variable.  When you
	PLAY a new sound effect which was not previously loaded, it will
	appear in this list.

SAVESND
  Syntax: savesnd <sound effect relative pathname>
  Description: Will cache (load) the specified sound effect then save
    it to a file named "snd.raw" in the directory you ran Quake in.  The
	format of this file is raw sound data.  Run SOUNDLIST to see the
	sample bit width and recording speed.  If 8-bit, then the output may
	be either signed or unsigned.  If it sounds funny on playback in a
	sound program, try the other way.
  Demo Examples: savesnd american/gib.wav

NUMCHANNELS
  Syntax: numchannels <number of software sound channels>
  Description: This will specify the number of sound channels to mix in
    software.  This number must be 2 or higher.  The first channel is
	not used and may be used later for streaming CD audio.
	Increasing the number of channels will let you hear more
	similtaneous sounds in game play.  However, the more sounds you
	have, the higher the demand on CPU performance.  The default
	is 8 channels.	Note that some times sounds will get cut off
	for other reasons which will be sorted out in later versions.
	Running NUMCHANNELS several times may cause memory problems.
	There are as many "sleeping channels" as there are sound channels.
	Sleeping channels are sound channels which are currently inaudble,
	usually because the sound source is out of your range of hearing,
	but the channels are woken back up when the sound comes back in
	range, assuming the sound effect is not already over, or is looping.
  Demo Examples: numchannels 5

SOUNDINFO
  Syntax: soundinfo
  Description: This prints the "portable" information on your current
    audio hardware setting in the game.  It specifies whether there is
	stereo output (0 or 1), the number of samples in the DMA buffer
	(usually 32768 or 65536), the current sample position (changes each
	time you run SOUNDINFO and ranges from 0 to the number of samples),
	the number of sample bits (either 8 or 16), the submission chunk
	(1 in DOS or Linux w/ mmaped sound, larger in Linux w/o mmaped sound),
	playback speed in Hz (usually 11025 to 44100), the DMA buffer address
	in hexadecimal (usually 8 digits after the 0x, starting with 0xf00..
	in DOS, starting with 0x400.. in Linux, and less than 8 digits if the
	hardware was not initialized successfully), and the number of channels
    mixed in software (8 by default, changeable w/ NUMCHANNELS command).

Variables
---------

NOSOUND
  Syntax: nosound [0 or 1]
  Description: Setting NOSOUND to 1 will prevent further sound effects
    from being loaded or started.  Returning it to 0 (default) will allow
	sound effects to be started again.  However, if a level is started with
	NOSOUND set to 1, and then it is returned to 0, no sounds will be
	precached, and they will not be cached during play.
  Demo Examples: nosound 1

DECIMATE_SFX
DECIMATE_SFX_SPEED
DECIMATE_SFX_WIDTH
  Syntax: decimate_sfx [0 or 1]
  Description: Setting DECIMATE_SFX to 1 will decimate all cached sound
    effects to the lower of their recorded sound rate or the value of
	DECIMATE_SFX_SPEED.  It will also reduce 16 bit sound effects to 8 bit
	sound effects if DECIMATE_SFX_WIDTH is 1.  DECIMATE_SFX can save a
	great deal of memory at the cost of making some of the sounds a bit
	muffled or perhaps staticky.  After setting this, a level must be
	reloaded for it to take effect.  SOUNDLIST will display the new memory
	footprint and sound effect lengths.  The following example will probably
	save 75% of the RAM required for a level's sound effects while keeping
	the sound effects at roughly the same playback quality of Doom's sound
	effects.  After setting these variables, a map must be reloaded for them
	to take effect.  By default, DECIMATE_SFX is 0, and sfx are not decimated.
  Demo Examples : decimate_sfx_speed 11025
                  decimate_sfx_width 1
                  decimate_sfx 1


Sound Blaster Sound Card Command-Line Options and Commands
==========================================================

The following applies to Sound Blaster cards or compatibles under DOS
or a DOS box.

Command-Line Options
--------------------

SBVER
  Syntax: -sbver <major version #> <minor version #>
  Description: This will force the sound code to behave as though the
    card's version is as specified instead of reading the actual version.
	When running the SBINFO command, the major and minor version numbers
	are separated by a decimal point.  In this command-line option, they
	are separated by a space.

DMASIZE
  Syntax: -dmasize <DMA buffer size in bytes>
  Description: Instead of using a 16k DMA buffer, the sound code will
    use one the size specified.  The size *must be* a power of 2.
	Examples of valid sizes are 2048, 4096, 8192, 16384, 32768, and
	65536.  Do not go higher than 65536.  You might want to make the
	DMA buffer size larger if you hear jumbled or poppy sound and tend
	to have a slow frame rate (under 15 fps).  Or you might want to make
	it smaller if you have a fast machine and are having troubles under
	Win95.

Commands
--------

SBINFO
  Syntax: sbinfo
  Description: This will print information on the Sound Blaster card
    in the system.  If the version is 4 or greater, then it is some
	kind of Sound Blaster 16 or compatible.  If less, then it is
	probably a Sound Blaster or Sound Blaster Pro or compatible.
	If the version is 3, then it will be reported as 2.  This is
	a hack that may be fixed later.  The port is the I/O port
	sensed from the A variable in the BLASTER environment variable.
	The DMA is the DMA channel and is confirmed in hardware if the
	card is version 4 or higher.  The mixer port can be ignored.


Linux Sound Driver Environment Variables
========================================

The Linux sound driver in the demo version runs in a seperate process
and communicates via shared memory with the game.  The process is called
"dmasim" and from the game process's point of view, simulates the behavior
of a DMA buffer feeding a sound card.  Later, there may be a version of
the game which can look directly at the actual DMA buffer and has no need
for the seperate process.  Because you may not pass command-line options
to the dmasim process, you may set variables using environment variables.
If using bash, you set these by typing "export QUAKE_SOUND_SPEED=22050" on
the command line before you run xquake.

QUAKE_SOUND_SPEED
  Syntax: export QUAKE_SOUND_SPEED=<valid speed for your sound card>
  Description: This will set the playback speed for the sound driver.
    Higher speeds will allow some sound effects to sound better but
	require more CPU horsepower.  Typical speeds are 11025, 22050, or
	44100, however it's likely you can specify any value between 8000
	and 44100.  The default speed is 44100 Hz.

QUAKE_SOUND_SAMPLEBITS
  Syntax: export QUAKE_SOUND_SAMPLEBITS=<8 or 16>
  Description: This will set the playback sample bits for the sound
    driver.  8 sample bits will not mix sounds as accurately and may
	sound cheesey, but it is supported on all cards.  16 sample bits
	sounds better, and it does not cost any CPU performance, but your
	sound card must support it.

QUAKE_SOUND_CHANNELS
  Syntax: export QUAKE_SOUND_CHANNELS=<1 or 2>
  Description: Not to be confused with the software mixing channels,
    this simply refers to whether to output mono or stereo sound
	effects.  Mono sound effects will be quieter with distance in
	the game, and sounds pretty good, but stereo sound effects will
	also come out of different speakers depending on whether the sound
	effect in the game is to your left or right.  This can be important
	to game play as your ears can help you locate nasties.

QUAKE_DEBUG_DMA
  Syntax: export QUAKE_DEBUG_DMA=<filename or "|command">
  Description: For the hacker only.  This will stream the sound output
    to a file in a raw format with sample bits and speed as reported by
	the SOUNDINFO command.  Be very careful with this.  A stereo playback
	at 16bit, 44kHz (CD quality) is generating 176400 bytes/second of
	data.  Leaving a game running for one minute will create a 10Mb file.
	If the filename starts with the pipe character "|" then the rest of the
	filename is interpreted as a command and is piped to it through the
	popen() call and fwrite()'s & fflush()'s every submission chunk
	sample sets, as reported by SOUNDINFO.

-------------------------------cut here----------------------------------

                  Quake Deathmatch TEST #1 Sound Bug Report


E-mail (preferred) to: qtest1@idsoftware.com
or FAX to: 214 686 9288

Date:

Name:

Company:

Street address:

City, state, ZIP:

Phone:

Fax:

E-mail:

What operating system are you running?:

Manufacturer/model of sound card:

Attach here the "qconsole.log" file generated when you run quake with the
"-condebug" option and run the SOUNDINFO and SBINFO (DOS only) commands:

If DOS or a DOS box, please run the command "set > set.txt" then
attach set.txt here:

If DOS, please attach your AUTOEXEC.BAT file here:

If DOS, please attach your CONFIG.SYS file here:

If Win95, pray.

Please describe the problem you are encountering, including a procedure
for reproducing the problem:

If program crashed with nasty undecipherable techno-garbage, please
look for the eight-digit number/letter thingy which comes after "eip="
and write it down here:

Please list any error messages, crash dump, or other information
that you think might be relevant:

Do you program or do technical support at school or work?

-------------------------------cut here----------------------------------

