                            StrangeUtil (v2.04)
                            -------------------

- Strange Company MP3 Decoding Utility
- Copyright (c) 1999, James Payne.


StrangeUtil is a utility for decoding MPEG Audio files and performing
operations on Quake .PAK files. It is distributed under the
GNU General Public License Version 2 (see file COPYING).


References:

 - MP3 decoder from AMP11, (c) '97 Niklas Beisert
  - which was developed with:
    - reference code (DIST10) by MPEG Software Simulation Group
    - maplay by Jeff Tsay, Tobias Bading et al. (Mikko Tommila)
    - mpg123 by Michael Hipp, Oliver Fromme et al.
 - Quake 'PAK' file format documentation by Olivier Montanuy


Background:

StrangeUtil was developed to assist in the distribution of Eschaton: Nightfall,
an animation produced by Strange Company using the QuakeII game engine.


Files:
Included in the StrangeUtil package should be at least the following files:
STRANGE.EXE - StrangeUtil itself
FILE_ID.DIZ - brief text file
README.TXT - this file
COPYING -  GNU General Public License


Operation:

Run
STRANGE <file.sc>
where <file.sc> is the name of the script file to parse.


Script Files:

A script file is a plaintext file, with one instruction per line. The valid
instructions are:

AUTODEL [off|on]
 - if 'on', .MP3 files are automatically deleted after conversion.
 - default is 'off'.

ERROR [ignore|warn|halt]
 - sets behaviour for dealing with errors encountered, for example
   a missing file.
 - 'ignore' will skip past any errors with no message
 - 'warn' will prompt for continuation
 - 'halt' will stop the current process and quit
 - default is 'warn'

OUTPUT [mono|stereo] [4x|2x|1x]
 - Sets the output .WAV format for the converted .MP3 files.
 - 4x or 2x is the rate of downsampling performed on files, ie
   a 44khz .MP3 file downsampled by 2x will be a 22khz .WAV file.
 - Default: mono output, no downsampling
   OUTPUT mono 1x
 - Other examples:
   OUTPUT mono 4x  - mono output, 4 times downsampling
   OUTPUT stereo 2x

WORKING dir
 - Sets the path where the operations are to be performed.
 - N.B. Remember the trailing slash.
 - Default:
   WORKING ./     (The path where Strange was called from)
 - Examples:
   WORKING c:/quake2/night/

CONVERT mp3file wavfile
 - Converts the MPEG audio file, <mp3file>, into a standard .WAV file.
 - Should work for all layer 1, 2 or 3 MPG Audio files, ie mp1, mp2 and
   mp3.
 - Example:
   CONVERT scene1.mp3 scene1.wav

EXTRACT pakfile pakpath outfile
 - where 'pakfile' is the name of a .PAK file, eg PAK1.PAK
   'pakpath' is the full location of a file within the PAK, eg maps/q2dm1.bsp
   'outfile' is the name of the file to create in the working dir
 - Examples:
   EXTRACT pak0.pak maps/q2dm3.bsp q2dm3.bsp
   EXTRACT pak1.pak default.cfg extract.ed

INSERT pakfile pakpath infile
 - where 'infile' is the name of a file to insert into the PAK
   'pakfile' is the name of the .PAK file
   'pakpath' is the full location of the file to create in the .PAK
 - N.B. Remember, PAK file locations cannot be more than 50 characters.
 - Examples:
   INSERT pak1.pak env/skyup.tga sky1.tga
   INSERT pak2.pak readme.txt readme.txt

REMOVE pakfile pakpath
 - removes <pakpath> from the .PAK file <pakfile>
 - N.B. This will not reduce the file size of the .PAK. Use OPTIMISE
   after removing files from a .PAK to regain the disk space.
 - Example:
   REMOVE pak1.pak useless.dat

OPTIMISE pakfile
 - consolidates the free space in the .PAK file <pakfile>
 - you should use this feature after any set of commands including
   INSERT or REMOVE

DELETE filename
 - will delete the file named 'filename' from the working directory
 - N.B. Does not delete files from within .PAKs.


History:
v1.xx - First release version.
v2.00 - Added inbuilt MP3 conversion
v2.01 - Added PAK file support
v2.02 - Bugfixes
v2.03 - Added script file support
v2.04 - Bugfixes


To do:
Planned future additions:
- Command line interface as alternative to scripting.
- Commands for manipulating whole directories.
- A check for diskspace - at the moment it could run out of space, when
  it does it'll just report an error and quit.


Warning:
Myself or Strange Company provide NO WARRANTY and will NOT be held
responsible for any loss or damage to data (or anything else) due to
StrangeUtil in any way. For this reason I recomend that you BACK UP your
files, especially .PAK files before use.


Source Code:
Is available, should you feel the need. Just mail me, address is below.


Bugs?
StrangeUtil hasn't been completely tested yet. If you find a problem,
please mail me with a description of what goes wrong, in as much detail
as possible. Cheers.


Distribution:
You can distribute this program in any way you like, so long as you include
this text file, and the file COPYING (which contains the details of the
license for this software) and the FILE_ID.DIZ.
Please read the file 'COPYING' for license details.


Features:
Any ideas for useful features for StrangeUtil to incorporate?
I'll happily add any sensible suggestion.


Contact:
James Payne - email: j.payne@sms.ed.ac.uk
            - web: http://www.dcs.ed.ac.uk/home/jxp/jamesweb
Strange Company - web: http://www.strangecompany.org



---

The .PAK file format was created by 'Id Software'. 'Quake' is a registered
trademark of 'Id Software'.
