Tomb Raider III cdaudio.wad Editor
==================================
v3.0

CONTENTS OF THIS FILE
---------------------

 • Introduction
 • Usage
 • Usage Examples
 • Potential Errors
 • Source Notes
 • Source Patching
 • Format Specifications
 • Changelog
 • License


INTRODUCTION
------------

audio3 is a tool written by b122251 in C programming language
for GNU/Linux, Mac OS X, Windows and DOS.
It can read and modify the cdaudio.wad files that Tomb Raider III uses.
It is released under the GNU General Public License version 3 or later.


USAGE
-----

audio3 uses the following syntax:

	audio3 list cdaudio.wad
	audio3 rename cdaudio.wad track "New Title"
	audio3 extract cdaudio.wad track output(wave file)
	audio3 unpack input(cdaudio.wad) output(directory)
	audio3 pack index.xml output(cdaudio.wad)

 • list:	Lists all titles in the cdaudio.wad file.
 • rename:	Changes the title of a track in the cdaudio.wad file.
			track is the number of the track to be renamed (0-129).
			New Title is the new title for the track.
 • extract:	Extracts a track from cdaudio.wad
			track is the number of the track to be renamed (0-129).
			output(wave file) is the file the track is to be written to.
 • unpack:	Unpacks a wad file into individual tracks and an xml-file.
			output is the output directory (must not yet exist).
 • pack:	Makes a new cdaudio.wad file from an index.xml file.
			output(cdaudio.wad) is the output file.

For further clarification, see USAGE EXAMPLES and FORMAT SPECIFICATIONS.


USAGE EXAMPLES
--------------

audio3 list cdaudio.wad
	This lists the titles of all tracks cdaudio.wad contains.

audio3 list cdaudio.wad >> ls.txt
	This writes the titles of all tracks cdaudio.wad contains to ls.txt.

audio3 rename cdaudio.wad 5 "Main Title.wav"
	This renames track 5 in cdaudio.wad to "Main Title.wav".

audio3 extract cdaudio.wad 121 121.wav
	This extracts track 121 inside cdaudio.wad into 121.wav.

audio3 unpack cdaudio.wad cdaudio
	This makes a directory called cdaudio, and extracts the contents of
	cdaudio.wad into it. This will be in the form of index.xml and
	individual wave-files.

audio3 pack index.xml cdaudio.wad
	This reads the contents of index.xml, and builds a new cdaudio.wad
	based on it. (Please note that audio3 reads file paths from the
	current working directory. If in the index.xml the file paths are
	relative, make sure you are in the same directory as index.xml.)


POTENTIAL ERRORS
----------------

audio3 may give one of the following error messages:

 • "audio3: missing operands"
	This means there were an insufficient number of operands.

 • "audio3: file could not be opened"
	This means the specified file doesn't exist or can't be opened.

 • "audio3: Buffer could not be allocated"
	This means no buffer could be allocated.

 • "audio3: file is not a valid wad-file"
	This means the specified file is not a valid cdaudio.wad file.

 • "audio3: Reading from file failed"
	This means the file is either non-readable or non-existent.

 • "audio3: Writing to file failed"
	This means the file's location is either read-only or doesn't exist.

 • "audio3: file.xml is not valid"
	This means the specified xml-file is not valid.

 • "audio3: Track number outside of 0-129 range"
	This means the track number is outside of the allowed range.

 • "audio3: Directory could not be made"
	This means the specified directory either already exists, or could
	not be made because its location is read-only or non-existent.

 • "audio3: Filepath too long (>512 characters)"
	This means the specified file path is longer than audio3 can handle.


SOURCE NOTES
------------

The source code to audio3 comes in the form of audio3.c, and several
patches. audio3.c is the standard source file. It is designed for
unix-like operating systems. The windows version was compiled using
MinGW, but requires a slight alteration to the source code. This change
can be found in windows.patch. The DOS version was compiled using
Borland Turbo C 2.01. The source code requires no alteration to work on
it, other than conversion from unix-like line endings to dos-like line
endings.

It is assumed that "long int" is 32-bits. If on the system you are
compiling for, this is NOT the case, please replace all "long int"
occurences with the 32-bit integer for your system. For 64-bit systems,
this has already been done in 64bit.patch.

To make the source code compatible with Big-Endian computers, some
changes had to be made. These changes can be found in be.patch.


SOURCE PATCHING
---------------

To patch the source code for Windows:
	$ patch audio3.c windows.patch

To patch the source code for Big-Endian:
	$ patch audio3.c be.patch

To patch the source code for 64-bits:
	$ patch audio3.c 64bit.patch

To patch the source code for 64-bit Windows:
	$ patch audio3.c windows.patch
	$ patch audio3.c 64bit.patch

To patch the source code for 64-bit Big-Endian:
	$ patch audio3.c 64bit.patch
	$ patch audio3.c be.patch


FORMAT SPECIFICATIONS
---------------------

 • cdaudio.wad
	entry[130]{
		string Title;	// Title of the track	(260 bytes)
		uint32 length;	// Length of the track	(4 bytes)
		uint32 offset;	// Offset of the track	(4 bytes)
	}
	WAVE DATA;		// Embedded wave files	(unknown length)
	
	________________________________________________________
	The file starts with a 130-entry index, consisting of 268 bytes per
	entry (34840 bytes in total). Each entry consists of a 260-bytes 
	long title (in the form of a string), a 32-bit unsigned 
	integer (length) containing the length of that track in bytes, and a
	32-bit unsigned integer (offset) containing the absolute position of
	that wave-file within cdaudio.wad. These integers are Little-Endian.
	Following this index, the rest of the file is 
	filled up with embedded	wave-files.

 • index.xml
	When unpacking a cdaudio.wad file, audio3 will produce individual
	wave-files, and a file titled index.xml. Index.xml specifies where
	the tracks that made up the original wad-file are stored, and what
	their titles are. This is also the file format the program requires
	as input when packing a new cdaudio.wad file.
	The structure of index.xml goes as follows:
	The root element is cdaudio (for obvious reasons).
	Inside the cdaudio-element are several track-elements. A track-
	element MUST contain a number-element, and may contain a title- 
	and/or file-element. Number specifies what track number this entry
	represents (0-129), file specifies where the wave-file that contains
	this track is located, and title specifies the title of this track.


CHANGELOG
---------

v3.0
 • Rewrote the program entirely
 • Added a DOS-port
 • Improved stability


LICENSE
-------

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.


<b122251.org>
