============================================================================
		 Game Audio Player v1.28 Documentation		  7-Sep-1999
============================================================================
					     Copyright (C) 1999 ANX Software

Table Of Contents
==================

1     Introduction to GAP
2     Disclaimer
3     GAP Files
4     Currently Supported Games
5     GAP Actions:
5.1	Main (Playback) Window
5.2	Playlist Window
5.3	Keyboard Shortcuts
6     Options:
6.1	Playback
6.2	Playlist
6.3	Saving
6.4	Audio File Plug-Ins (AF Plug-Ins)
6.5	Resource File Plug-Ins (RF Plug-Ins)
7     Audio File Plug-Ins Configurations:
7.1	ACM Plug-In Configuration
7.2	ASF Plug-In Configuration
7.3	AUD Plug-In Configuration
7.4	RAW Plug-In Configuration
7.5	SOL Plug-In Configuration
7.6	MUS/ASF Plug-In Configuration
7.7	WADSFX Plug-In Configuration
7.8	BNK Plug-In Configuration
8     Resource File Plug-Ins Configurations:
8.1	MPQ Plug-In Configuration
8.2	WAD Plug-In Configuration
8.3	DSND Plug-In Configuration
9     Credits
10    Known Problems
11    GAP Future Plans
12    GAP Project
13    Appendix: ANX APL Playlist Format

1 Introduction to GAP
======================

Game Audio Player (GAP) is an utility capable of...
1) Searching various games resource files for various audio files (music/sfx/speech)
2) Extracting found files "as is" and converting them to WAVs
3) Playing found/added files with seeking and other features

Features supported include...
1) Plug-in system: plug-ins for audio files and resource files
2) Playlist functionality: remove node, duplicate node, move up/down,
   clear, multiselect, add directory, scan directory
3) Saving/Converting multiple files at once using filename template
4) Game oriented playlist: option for loading/saving playlists so that they can
   be used on systems with different CD drive letters
5) Playback options: repeat one/all, shuffle, introscan, single-file playback
6) Several ready-for-use playlists for CD-games: NFS, NFS II, NFS III,
   Command & Conquer, Red Alert, Diablo, Quake II, NBA Live'96, Fallout,
   Torin's Passage, NBA Live'99, Gabriel Knight II, Phantasmagoria,
   Phantasmagoria II: The Puzzle Of Flesh, King's Quest 8, etc.

New in version 1.28:
1) Plug-in directories are now configurable
2) Playback is now performed by a separate thread
3) GAP now can convert audio files to compressed WAVs!
4) GAP info box improved: now it provides lots of tips/help/info/links/mails!
5) WAV plug-in improvement: now it supports compressed WAV formats
6) New WAD/WADSFX plug-ins: DOOM, DOOM2, Heretic, Hexen, etc. sounds!
7) New DSND plug-in: Descent I, Descent II sounds!
8) ASF plug-in search bug fixed: now it finds soundtracks in NFS .TGV videos
9) MUS/ASF plug-in decoder bug fixed: now it should play .WVE/.TGQ music/sound correctly
10) MPQ plug-in improvement: now it's unloaded successfully when using StarCraft's STORM.DLL
11) RAW plug-in upgrade: added support for A-law/u-law
12) SOL plug-in improvements: added auto-detection of SOL ADPCM decompression scheme and stereo SOLs support
13) VOC plug-in bug fixed: now it closes verified files :-)
14) AUD plug-in improvement: added support for stereo AUDs
15) ASF, AUD, MUS/ASF and SOL plug-ins improvement: added option for sample clipping
16) Minor GAP bugfixes/improvements
17) New GAP features: single-file playback, add/scan directory
18) New (very limited) BNK plug-in for NFS 2, NFS 3 sounds/speech

New in version 1.10:
1) New MUS/ASF plug-in for Electronic Arts music (NFS 2, NFS 3, etc.)!
2) AUD plug-in now plays Westwood-compressed AUDs!
3) SOL plug-in now plays SOLs without noise!
4) Saving/converting of multiple audio files using filename template
5) Keyboard shortcuts
6) Some user interface elements improved
7) Search for SOL, ACM and ASF plug-ins improved
8) More games supported!
9) GAP/plug-ins speed/size optimizations

GAP and all current plug-ins are Copyright (C) 1998-1999 ANX Software.
E-mail: anxsoftware@avn.mccme.ru

GAP is the official audio player of Absolute Games Music Site:
http://www.music.ag.ru
The site is maintained by Gektor: gektor@ag.ru, ICQ: 10336025
Please visit this site for comprehensive docs on GAP and its plug-ins,
latest news/releases, game audio file formats, loads of game music.

GAP and its plug-ins may also be found on the Internet:
http://www.fortunecity.com/campus/electrical/81/samael.html,
http://anx.da.ru (which is just the same as previous),
http://denver.da.ru,
http://tarkus.ran.gpi.ru/valentin/ (this URL may change!)

GAP is completely FREEWARE.

2 DISCLAIMER
=============

This software comes with NO WARRANTY.
You use it at YOUR OWN RISK.
The author of this software may not be kept responsible for any damage caused
by any usage of this software.

3 GAP Files
============

GAP.ZIP package should include the following files...

GAP.EXE -- Game Audio Player Win32 Executable
GAP.INI -- GAP Initialization File
GAP.TXT -- This document

PLUGINS\AF_ACM.DLL   -- ANX ACM Audio File Plug-In
PLUGINS\AF_ASF.DLL   -- ANX ASF Audio File Plug-In
PLUGINS\AF_AUD.DLL   -- ANX AUD Audio File Plug-In
PLUGINS\AF_MUS.DLL   -- ANX MUS/ASF Audio File Plug-In
PLUGINS\AF_BNK.DLL   -- ANX BNK Audio File Plug-In
PLUGINS\AF_RAW.DLL   -- ANX RAW Audio File Plug-In
PLUGINS\AF_SOL.DLL   -- ANX SOL Audio File Plug-In
PLUGINS\AF_VOC.DLL   -- ANX VOC Audio File Plug-In
PLUGINS\AF_WAV.DLL   -- ANX WAV Audio File Plug-In
PLUGINS\AF_WADSX.DLL -- ANX WADSFX Audio File Plug-In
PLUGINS\RF_PLAIN.DLL -- ANX Plain Resource File Plug-In
PLUGINS\RF_MPQ.DLL   -- ANX MPQ Resource File Plug-In
PLUGINS\RF_WAD.DLL   -- ANX WAD Resource File Plug-In
PLUGINS\RF_DSND.DLL  -- ANX DSND Resource File Plug-In
PLUGINS\STORMD.DLL   -- Diablo STORM library (may be used by RF_MPQ.DLL)
PLUGINS\STORM.DLL    -- StarCraft STORM library (may be used by RF_MPQ.DLL)

MPQ Archives Filelists:
PLUGINS\DIABLO.TXT   -- Diablo File List
PLUGINS\HELLFIRE.TXT -- Hellfire File List
PLUGINS\STARCRAF.TXT -- StarCraft File List
PLUGINS\BROODWAR.TXT -- BroodWar File List

4 Currently Supported Games
============================

Via ACM audio plug-in (using PLAIN resource plug-in):
    Fallout
    Fallout II
    Hopefully many other Black Isle/Interplay games (*)
Via ASF audio plug-in (using PLAIN resource plug-in):
    NBA Live'96
    FIFA'96
    NHL'96					(*)
    The Need For Speed (SE)
    Hopefully many other Electronic Arts games	(*)
Via MUS/ASF audio plug-in (using PLAIN resource plug-in):
    NBA Live'99
    FIFA'98
    Need For Speed II (SE)
    Need For Speed III
    Need For Speed IV				(*)
    Fighter Pilot
    Warhammer II: Dark Omen			(*)
    Hopefully many other Electronic Arts games	(*)
Via AUD audio plug-in (using PLAIN resource plug-in):
    Legend Of Kyrandia III: Malcolm's Revenge
    Command & Conquer
    Command & Conquer: Covert Operations	(*)
    Red Alert
    Red Alert: The Aftermath			(*)
    Red Alert: Counterstrike			(*)
    Lands Of Lore II				(*)
    Lands Of Lore III				(*)
    Blade Runner				(*)
    Dune 2000					(*)
    Hopefully many other Westwood Studios games (*)
Via WAV audio plug-in (using MPQ resource plug-in):
    Diablo
    Hellfire					(*)
    StarCraft					(*)
    BroodWars					(*)
    Hopefully many other Blizzard games 	(*)
Via WADSFX audio file plug-in (using WAD resource file plug-in):
    DOOM
    Ultimate DOOM
    DOOM II
    DOOM II: Plutonia Experiment
    DOOM II: TNT Evilution
    Heretic
    Hexen
    Hopefully some other ID Software/Raven Software games (*)
Via RAW audio plug-in (using PLAIN resource plug-in):
    Space Bucks
    X-COM III: Apocalipse			(*)
Via RAW audio plug-in (using DSND resource plug-in):
    Descent I
    Descent II
    Hopefully some other Parallax Software games (*)
Via SOL audio plug-in (using PLAIN resource plug-in):
    King's Quest VI
    Leisure Suit Larry VI
    Pepper's Adventures in Time
    Quest For Glory III
    Space Quest V
    Torin's Passage
    Phantasmagoria I
    Phantasmagoria II: The Puzzle Of Flesh
    Gabriel Knight				(*)
    Gabriel Knight II
    King's Quest VII				(*)
    King's Quest VIII
    Hopefully many other Sierra On-Line games	(*)
Via VOC audio plug-in (using PLAIN resource plug-in):
    Rise Of The Triad
    Duke Nukem 3D
    Redneck Rampage
    Dark Forces
    TIE Fighter
    The Day Of The Tentacle
    Sam & Max Hit The Road
    Dune II
    Lands Of Lore I
    Legend Of Kyrandia II
Via WAV audio plug-in (using PLAIN resource plug-in):
    WarCraft
    WarCraft II
    Mortal Kombat III
    Space Quest VI
    MDK
    Monster Truck Madness II
    Blood II: The Chosen
    Quake I/II
    Hexen II
    Heretic II
    MageSlayer
    Dark Reign
    Tomb Raider
    Tomb Raider II				(*)
    Tomb Raider III				(*)
    Sanitarium
    Unreal
    Half-life
    Harvester

And also...
    Many-Many-Many More !!!
    Just make search (SCAN FILES... in playlist window) !!!

NOTE: (*) means GAP is not tested with that game, but should work.
      If it does not work please mail me!

NOTE: For Electronic Arts games like NFS 2, NFS 3, FIFA'98, etc., use ADD FILES
      for .ASF and .MUS files. Note that plug-in is able to find audio stream
      in video files (.MAD, .DCT, etc.) -- use SCAN FILES for them.

NOTE: For Legend Of Kyrandia III, make search in all .PAK/.TLK and .AUD files.
      Songs are stand-alone .AUD files, which may be just added to playlist
      with ADD FILES button. The speech is in .TLK files -- make search in them.

NOTE: For Fallout I & II make search in *.DAT files. Before that you should
      enable ACM search in ACM plug-in configuration dialog.
      Songs are stand-alone .ACM files (which could be added to playlist
      with ADD FILES...).

NOTE: For DOOM, DOOM2, Heretic, Hexen, etc., press ADD FILES..., choose all
      .WAD files and then press SELECT ALL in the lump list dialog box,
      so that all sounds in .WAD will be added to playlist.

NOTE: For Descent I/II, press ADD FILES..., then choose DESCENT.PIG (for
      Descent I) or DESCENT2.S11 and/or DESCENT2.S22 (for Descent II) and
      then press SELECT ALL button in the file list dialog box, so that all
      sounds in .PIG/.S11/.S22 will be added to playlist.
      For Descent I all sounds are Unsigned 8-bit Mono 11025 Hz RAWs, while
      for Descent II sounds in DESCENT2.S11 are Unsigned 8-bit Mono 11025 Hz RAWs
      and in DESCENT2.S22 they are Unsigned 8-bit Mono 22050 Hz RAWs.

NOTE: X-COM Apocalipse music should be added as RAW with the following
      parameters: Stereo, 16-bit, Little-endian, 22050 Hz, Signed.
      Music files may be found in the MUSIC subdirectory.
      Sounds are in RAWSOUND subdirectory and they should be added with
      the following parameters: Mono, 8-bit, 22050 Hz, Unsigned.

NOTE: For Tomb Raider III make search in AUDIO\CDAUDIO.WAD file on CD.

NOTE: For Duke Nukem 3D sounds make search (SCAN FILES...) in DUKE3D.GRP and DUKE.RTS,
      For Rise Of The Triad sounds -- in DARKWAR.WAD and REMOTE1.RTS,
      For Redneck Rampage sounds -- in REDNECK.GRP and REDNECK.RTS,
      For Dark Forces sounds -- in SOUNDS.GOB and JEDISFX.LFD.
      For TIE Fighter -- in SFXBLAST.LFD, TIESFX.LFD, TIESPCH.LFD (RESOURCE dir).
      For The Day Of The Tentacle -- in MONSTER.SOU file.
      For Sam & Max Hit The Road -- in MONSTER.SOU file.
      For Dune II, Lands Of Lore I and Legend Of Kyrandia II -- in all .PAK files.
      For Mortal Kombat III -- in all .FTR files,
      For Quake, Heretic II -- in all .PAK files.

NOTE: For Electronic Arts games (like FIFA'96, NFS, etc.) make search in
      .BNK and .CRD files. Songs (sometimes, sounds) are usually .ASF and
      .AS4 files and speech files usually have extension .SPH. Plug-in is also
      able to find audio stream in .TGV video files -- use SCAN FILES for them.

NOTE: For all Sierra On-Line games (KQx, GQx, Larry, SQx, etc.) make search
      in RESOURCE.SFX and RESOURCE.AUD files.

NOTE: For WarCraft, WarCraft II make search in all *.WAR and *.SUD files.

Supported are maybe, much more games, but I've got no opportunity to test
GAP with them. Select ALL game files in SCAN FILES... and ADD FILES... in
playlist window to search for supported audio files within game resource
files (see section 5.2 for description of SCAN/ADD actions).
The candidates to check:
Westwood Studios games (for AUD plug-in),
Monster Truck Madness, many-many other WAV-using games (for WAV plug-in),
Sierra On-Line games (for SOL plug-in),
Interplay games (for ACM plug-in),
ID Software and Raven Software games (for WAD/WADSFX plug-ins),
Electronic Arts games (for ASF and MUS/ASF plug-ins).
Please let me know whether GAP works with these if you can!

5 GAP Actions
==============

The following subsections describe the GAP actions which may be performed
using the controls in the GAP windows.

5.1 Main (Playback) Window
===========================

Playback buttons:

PLAY/PAUSE (depending on playback state) -- starts/pauses playback,

STOP -- stops playback,

PREVIOUS -- plays or goes to the previous file in the current playlist,

NEXT -- plays or goes to the next file in the current playlist.

NOTE: Playback trackbar allows you to seek position in the played file only
      if the correspondent audio file plug-in supports seek function. If it
      does not support seek, the trackbar will be disabled (its slider will be
      grayed).

Other buttons:

PLAYLIST -- opens/closes playlist window.

EQUALIZER -- in this version of GAP equalizer is not implemented.

OPTIONS -- brings up options dialog.

In the bottom of GAP main window there're current GAP stats:
GAP state: Idle/Playing/Paused <file number>/<number of files>,
Current playback time,
Current audio file type,
Current resource file type.

INFO -- brings up info dialog.

5.2 Playlist Window
====================

Double-clicking on the file in the playlist will start playback of the file.
Clicking on the selected file will start editing name for the file.

NOTE: You can select multiple files in the playlist using SHIFT and CTRL.

NOTE: Some playlist buttons will be disabled (grayed) if their actions are
      not relevant with the selected files in the playlist.

OK -- closes playlist.

LOAD LIST(S)... -- loads APL playlist.

NOTE: You can select multiple playlist files in the playlist loading dialog:
      press SHIFT and CTRL to use that feature.

SAVE LIST... -- saves APL playlist.

WARNING: Do not try to load files which does not have APL playlist structure.
	 To produce APL playlist files, use ADD FILES/SCAN FILES and then
	 SAVE LIST. If you want to produce APLs manually, refer to the APL
	 format description in the Appendix.

ADD FILES... -- adds files to playlist: select any game files and GAP checks
whether they are in any of the supported format. As games often use various
file extensions for audio files, there's no common rule for files to
try adding. Just try all and see if it works. If not, mail me! If yes, mail
me anyway!

NOTE: Some audio files could not be verified, e.g. RAW sound. For such
      files the correspondent plug-in may ask user to specify their
      parameters, e.g. channels number (mono/stereo), resolution (8/16-bit),
      sample rate, byte order (Intel/Motorola), data format
      (signed/unsigned/sign-bit), etc. Such behaviour of the plug-in is
      configurable (see Options->AF Plug-Ins->Configuration).
      If asked, you may select different settings and check the result.
      For some audio files it's the only way to determine their parameters.

NOTE: Some resource file plug-ins may also ask user to enter information
      necessary for dealing with resource archives (e.g. MPQ plug-in requires
      the list for files in MPQ archive). Sorry for inconvenience!
      These plug-ins are also configurable and I did my best to make their
      usage convenient to the greatest possible extent.

ADD DIRECTORY... -- lets you add files from the directory of your choice.

NOTE: Directory browsing dialog lets you enable or disable recursing of chosen
      directory subdirectories.

SCAN FILES... -- selects files to search for supported audio files
within. Same as for the previous button: try to search in all game files.

NOTE: When you select files for ADD or SCAN, GAP checks them all whether they
      are resource library of any supported format. If a file is a resource
      library, added/searched are the files found in it via the correspondent
      resource file plug-in.

NOTE: You can select multiple files in the adding and searching dialogs:
      press SHIFT and CTRL to use that feature (or select multiple files
      by dragging mouse cursor over them).

SCAN DIRECTORY... -- lets you scan files from the directory of your choice.

NOTE: Directory browsing dialog lets you enable or disable recursing of chosen
      directory subdirectories.

PLAY -- plays currently selected audio file.

SAVE FILE(S)... -- saves currently selected audio file(s) "as is". If multiple
files are selected, the saving depends on the saving settings (Saving tab in
Options dialog).

CONVERT FILE(S)... -- converts currently selected audio file(s) to WAV(s). If
multiple files are selected, the saving depends on the saving settings
(Saving tab in Options dialog).

NOTE: Both filename template (for MultiConverting) and SaveFileName dialog
let you select WAV format (compression) for converting to WAV. Some formats
may turn out to be not suitable for converting to. GAP will bring up error
message if such format is chosen.

SELECT ALL -- selects all audio files in the playlist.

INVERT SELECTION -- inverts selection.

CLEAR LIST -- clears the playlist.

MOVE UP/DOWN -- moves up/down audio file in playlist.

REMOVE -- removes currently selected file from playlist.

DUPLICATE -- duplicates currently selected file.

FILE INFO -- displays currently selected audio file info box.

FILE TITLE -- lets you change name for currently selected file: this may differ
from the name of file this audio is stored in. For audio found
by SCAN operation, the initial name is <Unknown>. For those added by ADD
operation, the initial name is the correspondent filename.

5.3 Keyboard Shortcuts
=======================

General shortcuts (may be used in both main and playlist windows):

Z or Keypad 5		  -- Play/Pause,
C or LeftArrow/Keypad 4   -- Previous,
V or RightArrow/Keypad 6  -- Next,
X			  -- Stop,
CTRL+P			  -- Playlist,
CTRL+E			  -- Equalizer,
CTRL+O			  -- Options,
F1			  -- GAP Info,
CTRL+I			  -- Current audio file info box,
CTRL+A			  -- Add files,
CTRL+L or Insert/Keypad 0 -- Load playlist(s).

Playlist window shortcuts:

ALT+K			  -- Close playlist,
ALT+L			  -- Load playlist,
ALT+S			  -- Save current playlist,
ALT+A			  -- Add files,
ALT+Y			  -- Add files from directory,
ALT+F			  -- Scan files,
ALT+X			  -- Scan files from directory,
ALT+P			  -- Play currently selected file,
ALT+V			  -- Save/extract currently selected file(s) "as is",
ALT+O			  -- Convert currently selected file(s) to WAV(s),
ALT+C			  -- Clear playlist,
ALT+U			  -- Move up currently selected file in playlist,
ALT+W			  -- Move down currently selected file in playlist,
ALT+R			  -- Remove currently selected file,
ALT+D			  -- Duplicate file in playlist,
ALT+I			  -- File info,
ALT+T			  -- Edit/enter title for currently selected file,
ALT+E			  -- Select all items in playlist,
ALT+N			  -- Invert playlist selection.

6 Options
==========

The following subsections describe the GAP settings which may be set in
the property pages of the options dialog.

6.1 Playback
=============

WAVEOUT DEVICE -- lets you select waveform playback device.

PROCESS PRIORITY CLASS -- sets GAP process priority class.

PLAYBACK BUFFER -- sets playback buffers size.

GAP PRIORITY -- sets GAP main thread priority.

PLAYBACK PRIORITY -- sets GAP playback thread priority.

NOTE: Priority class and thread priorities may be set to higher values,
      if you have audio playback latencies. But the defaults
      ("Normal" for all) is recommended. Too high values may
      negatively affect other applicattions, while too low values
      may negatively affect GAP.

DEFAULT -- sets default values for all options (RECOMMENDED!).

6.2 Playlist
=============

PLAY NEXT FILE IN PLAYLIST -- if checked, the next file in the playlist is
played after current playback finishes. Otherwise playback stops after that.

INTROSCAN -- sets introscan mode and introscan length in seconds.

SHUFFLE -- sets shuffle mode.

REPEAT/ONE/ALL -- sets repeat mode: repeat one file, repeat whole playlist.

LOAD LAST PLAYLIST ON STARTUP -- allows autoloading last playlist during GAP
startup.

PLAY LOADED PLAYLIST ON STARTUP -- allows autoplayback of autoloaded last
playlist just after GAP startup.

ESTIMATE TIME ONLY BEFORE PLAYBACK -- instructs GAP to estimate audio
file length only before playback. Otherwise it tries to do that during
playlist loading, adding audio files to playlist and before playback.
Setting this option is recommended because estimating length for some
audio files when loading playlist may take some time and may be very
annoying.

WHEN LOADING PLAYLIST REPLACE [CD] WITH... -- allows replacing of [CD] string
in the resource filename with CD drive letter of your choice and sets that CD
drive letter.

WHEN SAVING PLAYLIST PUT [CD] FOR CD DRIVE LETTER -- allows replacing of CD
drive letter in the resource filename for files situated on CD with [CD]
string so that saved APL will be usable on systems with other CD drive letter
than that of the system it was saved on.

DEFAULT -- sets default values for all options (RECOMMENDED!).

6.3 Saving
===========

MultiSaving filename -- defines how GAP gets filenames when saving/converting
multiple files:
ASK USER FOR FILENAME FOR EVERY FILE -- when saving/converting multiple files
GAP will ask user for filename for every file being saved.
ASK USER FOR FILENAME TEMPLATE -- when saving/converting multiple files GAP
will ask user for filename template which will then be used for all files
being saved.
USE DEFAULT FILENAME TEMPLATE -- when saving/converting multiple files GAP
will use the default template for all files being saved.

Default template directory -- defines directory for the default filename
template:
CURRENT -- the default template directory is current directory.
CUSTOM -- the default template directory is that in the edit line below.
BROWSE -- lets user browse the default template directory.

Default template file title -- defines file title for the default template:
USE AUDIO FILE TITLE -- audio file title is used for the default template
file title.
USE RESOURCE FILE TITLE -- resource file title is used for the default
template file title.
CUSTOM -- the default template file title is that in the edit control below.

Extension -- defines extension for the default filename tamplate:
DEFAULT -- the default extension for saved file is used for the default
template filename extension.
CUSTOM -- the default filename template extension is that in the edit control
below. You can set it to single point "." to save to files with no extension.

MILTICONVERTING WAV FORMAT -- lets you select default WAV format (compression)
for MultiConverting. Listed in this control will be only WAV formats
supported in your system.

DEFAULTS -- sets default settings.

6.4 Audio File Plug-Ins (AF Plug-Ins)
======================================

AUDIO FILE PLUG-IN DIRECTORY -- defines the directory in which GAP will
search for audio file plug-ins. When GAP is started for the first time,
it sets this to "<GAP directory>\Plugins". If you move GAP to other directory
or move plug-ins to the directory other than "Plugins", change this setting!

CONFIGURE -- calls configuration routine of the chosen plug-in.

NOTE: you can also double-click on plug-in description string in the plug-in
      list to call its configuration routine

ABOUT -- calls about routine of the chosen plug-in.

ALLOW MULTIPLE PLUG-INS TO WORK WITH ONE FILE -- allows multiple audio
plug-ins to try to add files (chosen to add), which may result in many
annoying RAW Parameters dialogs from RAW Plug-In, but it may be used if you
want some files to be added as being in different formats.

6.5 Resource File Plug-Ins (RF Plug-Ins)
=========================================

RESOURCE FILE PLUG-IN DIRECTORY -- defines the directory in which GAP will
search for resource file plug-ins. When GAP is started for the first time,
it sets this to "<GAP directory>\Plugins". If you move GAP to other directory
or move plug-ins to the directory other than "Plugins", change this setting!

CONFIGURE -- calls configuration routine of the chosen plug-in.

NOTE: you can also double-click on plug-in description string in the plug-in
      list to call its configuration routine

ABOUT -- calls about routine of the chosen plug-in.

ALLOW MULTIPLE PLUG-INS TO WORK WITH ONE FILE -- allows multiple resource
plug-ins to try to process files (chosen for adding/searching), which may
result in several addition checks or searches done by different resource file
plug-ins for one file, but it may be used if you want some resource files to
be searched as being in PLAIN format (i.e. make plain file search).

7 Audio File Plug-Ins Configurations
=====================================

The following subsections describe audio file plug-ins configuration
options (for audio file plug-ins requiring configuration).

7.1 ACM Plug-In Configuration
==============================

DISABLE ACM SEARCH -- disables search (SCAN FILES...) opportunity for ACMs.

ENABLE CHANNELS CHECK -- enables channels number check when verifying
added/found file. This's recommended.

ENABLE PACK ATTRIBUTES CHECK -- enables pack attributes check when verifying
added/found file. This's NOT recommended.

The above two options may be used in order to avoid finding fake (incorrect)
files.

ACM FILE SIZE -- controls the means plug-in uses to determine found ACM size:
ESTIMATE -- estimate ACM size using "size" ACM header field (fast, but VERY
inaccurate).
WALK THE WHOLE ACM -- walk the whole found ACM file to determine its size.
This's recommended setting.

ACM CHANNELS -- controls the behaviour of plug-in when dealing with the ACM
which "channels" header field is equal to 2, which may be both stereo and mono
files:
TRY TO GUESS -- plug-in will try to determine channels number itself.
ASK USER     -- plug-in will ask user to set channels number.
USE DEFAULT  -- plug-in will use the default value for channels number.

NOTE: All music files in Fallout 1 & 2 are stereo while all sounds/speech
      are mono.

DEFAULT -- sets the default value for channels number:
MONO	-- the default is mono (1 channel).
STEREO	-- the default is stereo (2 channels).

DEFAULTS -- sets the default settings for all options.

7.2 ASF Plug-In Configuration
==============================

IGNORE ASF LOOP BLOCKS -- makes plug-in ignore ASF loops blocks, so that
looped songs are played once (without looping). Otherwise such songs are
played repeatedly.

WALK ASF BLOCKS CHAIN BEFORE PLAYBACK -- makes plug-in walk ASF blocks
chain when preparing for playback, so that seeking and looping will be
done fast. May take much time when starting playback.

ALLOW PLAYBACK AFTER END BLOCK ENCOUNTERED -- allows plug-in continue
playback after ending block encountered if it finds data after that block.
Some songs may contain such additional data. Useless when loop blocks
are not ignored (i.e. looped songs are played repeatedly). This feature
is poorly implemented due to the ASF file structure uncertainty.

CHECK SAMPLE RATE -- check sample rate header field of the file when verifying
added/found file.

CHECK CHANNELS NUMBER -- check channels number header field of the file when
verifying added/found file.

CHECK RESOLUTION -- check resolution header field of the file when verifying
added/found file.

USE SAMPLE CLIPPING FOR DECOMPRESSION -- makes plug-in use sample clipping
for IMA ADPCM data decompression. You may turn this setting on and off to
avoid "popping" in sound playback.

The above three options are recommended in order to avoid finding fake
(incorrect) files.

DEFAULTS -- sets the default settings for all options.

7.3 AUD Plug-In Configuration
==============================

USE "OUTSIZE" AUD HEADER FIELD (FAST, BUT INACCURATE) -- instructs plug-in
to use "outsize" field of AUD header for calculation of AUD time. Fast,
but may be inaccurate and is only applyable for new AUDs (ignored for
others).

USE "SIZE" AUD HEADER FIELD AND ESTIMATE (FAST) -- instructs plug-in
to use "size" field of AUD header for calculation of AUD time. Fast, but
only applyable for IMA ADPCM compressed AUDs (ignored for others).

USE AUD FILE SIZE AND ESTIMATE (FAST) -- instructs plug-in to use file
size of AUD file for calculation of AUD time. Fast, but only applyable
for IMA ADPCM compressed AUDs (ignored for others).

WALK AUD CHUNKS CHAIN (MAY BE SLOW) -- instructs plug-in to walk AUD
chunks chain for calculation of AUD time. May be TOO SLOW.

USE "OUTSIZE" AUD CHUNK HEADER FIELD -- makes plug-in use "outsize" AUD
chunk header field when walking AUD chunks chain for calculation of AUD
time. May be inaccurate. Applyable for all AUDs.

USE "SIZE" AUD CHUNK HEADER FIELD -- makes plug-in use "size" AUD chunk
header field when walking AUD chunks chain for calculation of AUD time.
May be inaccurate. Only applyable for IMA ADPCM compressed AUDs (ignored
for others).

DON'T USE WALKING IF FAILED TO ESTIMATE BY FAST METHODS -- disables
walking for the cases when fast methods (all other than walking) failed
to get data for calculation of AUD time. This IS RECOMMENDED, because
walking may be TOO SLOW, but if used this setting will disable playback
trackbar for Westwood-compressed AUDs as well as it will disable you to seek
in those AUDs.

USE SAMPLE CLIPPING FOR IMA ADPCM DECOMPRESSION -- makes plug-in use
16-bit sample clipping for IMA ADPCM data decompression. This IS REQUIRED
for C&C sounds and most of RedAlert sounds, but disabling it IS REQUIRED
for some RedAlert sounds/speech. If this setting is inconsistent with the
game sound data, it will most likely sound noisy. You may turn this setting
on and off to avoid "popping" in sound playback.

DEFAULTS -- sets the default settings for all options.

7.4 RAW Plug-In Configuration
==============================

ADD FILES -- sets RAW Plug-In behaviour when adding files:
ALWAYS			     -- Add any file as RAW.
ONLY WITH RAW/SND EXTENSIONS -- Add only files with RAW/SND extensions.
NEVER			     -- Never add files as RAW.

RAW PARAMETERS -- set RAW Plug-In behaviour for getting RAW parameters:
ASK USER	-- Ask user to specify RAW file parameters.
ASSUME DEFAULTS -- Assume default values for RAW file parameters.

DEFAULT PARAMETERS -- Default values for RAW file parameters:
SAMPLE RATE	      -- Sample rate.
CHANNELS	      -- Channels: mono/stereo/etc.
RESOLUTION	      -- Resolution: 8-bit/16-bit.
BYTE ORDER	      -- Byte order: little-endian/big-endian (Intel/Motorola).
FORMAT		      -- RAW data format: signed/unsigned/sign-bit/u-law/A-law.

DEFAULTS -- sets default values for all options.

7.5 SOL Plug-In Configuration
==============================

ENABLE EXTRA CHECKS -- enables some extra checks when searching for SOLs and
verifying stand-alone SOLs. This should prevent plug-in from finding fake SOLs,
but this also may prevent it from finding non-standard SOLs.

DECODING SCHEME DETECTION -- defines how the plug-in detects decoding scheme
for SOL ADPCM-compressed SOLs:
USE HEADER -- use header to detect decoding scheme: if header size is equal
to the shift byte in header, "old" scheme is used, otherwise "new" scheme is used,
DECODE FIRST 1 KB OF DATA -- decode first 1 KB of compressed data to determine
which scheme is more suitable for that SOL. This is RECOMMENDED, while this
may sometimes fail.

USE SAMPLE CLIPPING FOR DECOMPRESSION -- makes plug-in use sample clipping
for SOL ADPCM data decompression. You may turn this setting on and off to
avoid "popping" in sound playback.

DEFAULTS -- sets default values for all options.

7.6 MUS/ASF Plug-In Configuration
==================================

DISABLE LOOPING -- plug-in will ignore .ASF loop blocks and .MUS loops in .LIN/.MAP.
Otherwise files containing loop blocks or .LIN/.MAP loops will be looped.

WALK BLOCKS CHAIN BEFORE PLAYBACK -- plug-in will walk the whole block chain
of the file before its playback, so that seek and looping will be performed
almost without latency, but walking itself may take quite much time.

WALK BLOCKS CHAIN WHEN CALCULATING TIME -- plug-in will walk the whole block
chain of the file in order to calculate its time. This may take much time but
this SHOULD be used to calculate time for MUS files correctly. This is not needed
for ASF files.

MULTI-HEADER (MUS) FILES PLAYBACK -- sets the plug-in bahaviour when playing
back multi-header (MUS) files:

STRAIGHTFORWARD -- all MUS file sections are played one after another
straightforwardly. This is not recommended, as many MUS files contain
duplications and are not really supposed to be played in that manner.
SKIP IDENTICAL BLOCKS -- identical blocks will be skipped. This is a good way
to play some MUS files from NFS2.
USE .LIN/.MAP FILE -- use .LIN or .MAP file to play MUS file.
That's the way MUS files are supposed to be played.

.LIN/.MAP FILE FOR MULTI-HEADER (MUS) FILE -- sets plug-in behaviour when it
needs .LIN/.MAP file for MUS playback:

DEFAULT: <MUSFILENAME>.LIN/.MAP -- use <MUSFileName>.LIN/.MAP located in
the same directory as MUS file. Plug-in first tries to open .LIN file and
then (if it fails) it tries to open .MAP file.
ASK USER -- ask user for .LIN/.MAP file name.

USE SAMPLE CLIPPING FOR DECOMPRESSION -- makes plug-in use sample clipping
for EA ADPCM data decompression. You may turn this setting on and off to
avoid "popping" in sound playback.

DEFAULTS -- sets default values for all options.

7.7 WADSFX Plug-In Configuration
=================================

DISABLE WADSFX SEARCH -- disables search (SCAN FILES...) opportunity for
WADSFX files.

CHECK SAMPLE RATE -- enables sample rate check when searching for WADSFX files.
This has no effect if WADSFX search is disabled and this's recommended otherwise.

DEFAULTS -- sets the default settings for all options.

7.8 BNK Plug-In Configuration
==============================

USE SAMPLE CLIPPING FOR DECOMPRESSION -- makes plug-in use sample clipping
for EA ADPCM data decompression. You may turn this setting on and off to
avoid "popping" in sound playback.

8 Resource File Plug-Ins Configurations
========================================

The following subsections describe resource file plug-ins configuration
options (for resource file plug-ins requiring configuration).

8.1 MPQ Plug-In Configuration
==============================

PATH TO STORM.DLL -- sets the path (with filename) to Blizzard STORM library.
This setting takes effect only on the start of Storm operation, e.g. on
the start of WAV playback, etc.

SPEEDING UP MPQ VERIFICATION -- allows to speed up MPQ verification for
add/search actions:
CHECK EXTENSION  -- enables file extension check.
CHECK MPQ HEADER -- enables file header check.

NOTE: MPQ verification (without speed-ups like the above) may be VERY LONG
      for large files which ARE NOT MPQs! So speeding up MPQ verification is
      RECOMMENDED. But be careful: MPQ header check is not recommended because
      for many MPQ-containing files (like some EXEs) this check fails!
      Moreover, extension check may fail for non-standard MPQ-containing files
      (I have not seen such files yet, but they may exist), so for such
      "suspecious" files I can recommend TURNING OFF ANY speeding up for
      MPQ verification, but ONLY for such files!

FILE LIST FOR MPQ ARCHIVE -- sets the MPQ Plug-In behaviour for getting file
list for MPQ archive:
USE DEFAULT: <MPQFILENAME>.TXT	    -- use default file list filename.
ASK USER FOR MPQ FILE LIST FILENAME -- ask user to set file list filename.

NOTE: MPQ filelists shipped with GAP does not bear default names, so usage
      of default file list filename is NOT RECOMMENDED.

ASK USER TO SELECT FILES FROM LIST -- ask user to select files from open
MPQ archive for adding/searching.

DEFAULTS -- sets the default settings for all options.

8.2 WAD Plug-In Configuration
==============================

ASK USER TO SELECT LUMPS FROM LIST -- ask user to select lumps from open
WAD archive for adding/searching.

8.3 DSND Plug-In Configuration
===============================

ASK USER TO SELECT FILES FROM LIST -- ask user to select files from open
DSND/PIG archive for adding/searching.

9 Credits
==========

GAP and its plug-ins enumerated above are written by:
Asatur V. Nazarian (samael@avn.mccme.ru)

Web-support is courtesy of...
Gektor (gektor@ag.ru, ICQ: 10336025)
Alexey Schepetilnikov (a.shepetilnikov@globalone.ru),
Valentin Plotnichenko (valentin@nsc.gpi.ru)

Testing:
Alexey Schepetilnikov (a.shepetilnikov@globalone.ru),
Valentin Plotnichenko (valentin@nsc.gpi.ru),
Anthony Larme (larme@bit.net.au),
Tarek Al-Azem (talazem@hotmail.com).

ACM Plug-In is based on the ACM2WAV converter written by
Alexander Belyakov (abel@krasu.ru)

AUD Plug-In is based on the specs written by Vladan Bato:
E-mail: bat22@geocities.com
http://www.geocities.com/SiliconValley/8682

MUS/ASF plug-in is based on the WVE2PCM converter written by
Dmitry Kirnocenskij (ejt@mail.ru)

RAW Plug-In uses A-law/u-law->PCM parts of g711.c by Sun Microsystems, Inc.

VOC Plug-In is based on the VOC file format description by:
galt@dsd.es.com
and uses parts of VOC-dealing SOX source code which is
Copyright 1991 Lance Norskog and Sundry Contributors

WAD and WADSFX plug-ins are based on the Unofficial DOOM specs
written by Matthew S Fell:
msfell@aol.com

The author is also very grateful to...

Andrey Filimonov (filim@aha.ru) FIDO: 2:5020/779
For finding AUD docs for me on the Internet.

Valentin Plotnichenko (valentin@nsc.gpi.ru, http://denver.da.ru)
For finding ACM2WAV for me on the Internet.

Max Ushakov (ushakov@mccme.ru)
For lots of useful discussion and advice regarding RAW and WAV Plug-Ins.

Anthony Larme (larme@bit.net.au)
For the invaluable help with SOL file format.

MPQ Plug-In wouldn't be possible without the help of the following people
whom I'd like to thank:

(brainspin@hanmail.net)
For the STORMING source code

Ted Lyngmo (ted@lyncon.se)
For the StarCrack mailing list

King Arthur (KingArthur@warzone.com),
Unknown Mnemonic (zorohack@hotmail.com)
For sending me the filelists for many MPQ-games

Sean Mims (smims@hotmail.com),
David "Splice" James (beta@rogers.wave.ca)
For the invaluable help with the STORM.DLL API

10 Known Problems
==================

ACM Plug-In:
ACM file structure is uncertain and thus ACM search is poorly implemented.
Plug-In cannot reliably determine channels number of ACM file (which is either
guessed of set by user). If you know how to get this info from ACMs, please
mail me!

MUS/ASF Plug-In:
The plug-in cannot determine sample rate and resolution of MUS/ASF files thus
22KHz and 16-bit used for all files. If you know anything about Electronic Arts
.MUS/.ASF SCHl-headers, please mail me!

SOL Plug-in:
The decoding scheme (using or not using compressed code complement) detection
is poorly implemented: the plug-in decodes first 1 KB of compressed data and
determines which scheme is more suitable. If you know how this could be
reliably determined, please mail me!

BNK Plug-In:
The plug-in plays ONLY EA ADPCM (7) BNK sections.
I know nothing about others to support them anyhow...

11 GAP Future Plans
====================

-- Implementation of equalizer/noise filter
-- Making use (if possible) of WinAmp vis/dsp plug-ins

12 GAP Project
===============

If you have docs/specs regarding the following game sound/music/video/resource
file formats (as well as other intersting game (and not necessarily game)
sound/music/video/resource file formats), please mail me!

Here's the list:

.HSC (FM synth music used by many old games, e.g.: FINTRIS, Rol Crusaders),
.HMP and .HMI (Human Machine Interfaces MIDI music files: Descent, etc.),
.XMI (the Miles eXtended MIDI, used by Miles sound system: WarCraft2, etc.),
.DSM (DSIK module music file),
.PSM (MASI module music used by Epic MegaGames Pinball, Jazz JackRabbit, etc.),
.AMF (DSMI/Asylum module music used by some games: Crusader: No Remorse, Aladdin, etc.),
.IIM (module music),
.IMF (Corridor 7, Blake Stone, Wolfenstein 3D, Spear Of Destiny, etc.),
.DLS (Microsoft Interactive Music Architecture (IMA) -- Blood2, etc.).

.SMK (Smacker video: WarCraft2, Diablo, Blood2, Heretic2, Hexen2, etc.),
.MVE (Interplay video: Descent2, Fallout2, etc.),
.RPL (Tomb Raider video),
.VMD (Sierra On-Line video: Torin's Passage, etc.),
.TGV/.DCT/.MAD (Electronic Arts video: The Need For Speed I/II/III, NBA'96, etc.),
.LFD (LucasArts movies: Dark Forces, etc.).

13 Appendix: ANX APL Playlist Format
=====================================

APL consists of the strings, ended by newline, one string for audio file
each string being of the following format:

<Name> <AFType> <AFInfo> <ResFileName> <RFType> <RFInfo> Start Length

NOTE: "<" and ">" characters are important delimiters!

where:

Name -- Audio file name,

AFType -- Audio file type,

AFInfo -- Audio file info. Currently, ASF, BNK and RAW plug-ins require
that:

ASF Info is <SHIFT> where SHIFT (HEXADECIMAL) is the position of "EACS" id
string in the .BNK, .CRD, or any other "bank" file containing the ASF file.

BNK Info is <POS> where POS (HEXADECIMAL) is the position of "PT\0\0" id
string in the .BNK, .VIV, or any other "bank" file containing the BNK file
section RELATIVE TO "BNKl" id string (which indicates the start of BNK file).

RAW info is <RATE CHANNELS BITS FLAGS> (note the space between the numbers!),
all numbers are HEXADECIMAL!
RATE is sample rate,
CHANNELS is the number of channels (2 for stereo, 1 for mono, etc.),
BITS is the resolution of RAW sound (16 for 16-but, etc.),
FLAGS is the RAW data format flags:
bit 0 -- if set, little-endian byte order is used (Intel), otherwise big-endian
	 byte order is used (Motorola),
bits 1..3 -- data format used: 0 -- signed,
			       1 -- unsigned,
			       2 -- sign-bit,
			       3 -- u-law,
			       4 -- A-law.

ResFileName -- filename for the resource file audio file is contained in,
(use "[CD]" for CD drive letter to enable APLs to be usable on systems with
other CD drive letter that your system has -- refer to GAP Options section for
more details on this feature)

RFType -- resource file/library type. Currently, these types are supported:
PLAIN -- resource file containing game files "as is", without encoding or
compression,
MPQ   -- used by Blizzard's Diablo, StarCraft, HellFire, etc.,
DSND  -- Descent, Descent2 sound resources: .PIG, .S11, .S22,
WAD   -- ID Software .WAD resources.

RFInfo -- resource file info.
PLAIN resource plug-in does not require that,
MPQ resource file needs name for file stored in MPQ archive -- look into
MPQ games filelists, shipped with GAP,
DSND plug-in uses that for sound file number/filename: NUMBER/FILENAME.RAW,
as well as WAD plug-in uses that for the same: NUMBER/LUMPNAME,
for both NUMBER is hexadecimal.

Start -- start position of audio file in the file determined by
ResFileName and RFInfo (HEXADECIMAL). May be FFFFFFFF for audio file
spreading up to the end of file it's contained in.

Length -- length of audio file in the file determined by
ResFileName and RFInfo (HEXADECIMAL).

NOTE: The above two numbers are required for ALL audio files even if
      they are single standalone files not contained in any archive! And
      these two numbers are important, because placing game files into
      resource library or even into a file contained in the resource
      library itself is a common thing for many-many-many games.

NOTE: If a parameter is not required (like AFInfo for most plug-ins),
      there should be corresponding "<>" delimiters pair for that parameter
      anyway!

NOTE: Strings enclosed in "<>" delimiters should have equal number of "<" and
      ">" symbols, otherwise GAP will fail to get right string.