The San Andreas Audio Toolkit is a set of commandine tools useful for modding the PC version of the video game Grand Theft Auto: San Andreas. SAAT allows the importing of music files into SA audio streams and the importing of WAVe files into SA sfx archives. It will also necessarily allow exporting from each type of archive into individual files.
The official SAAT homepage, containing an HTML version of the README.txt can be found at
http://pdescobar.home.comcast.net/gta/saat/Discussion and feedback on SAAT takes place on its GTAForums thread
http://www.gtaforums.com/index.php?showtopic=225049BACKUP BRIEF DOCUMENTATION
(See file MANUAL.txt for more detail and examples)
Installation (Windows Binaries):
- Unzip the two executables and any ini files into a useful location such as the GTASA main directory.
- Open a command prompt window and cd to the install directory.
Usage (stream tool):
saat_stream.exe -e <stream_file(s)> <target_dir>
Simple export mode; exports all tracks from <stream_file(s)>, storing the Ogg
Vorbis files in an appropriately named subdirectory of <target_dir>.
saat_stream.exe -r <stream_file(s)> <target_dir> <metadata_file>
RFSA export mode; like -e but uses contents of <metadata_file> for additional descriptive information to tag and name the exported files.
Note: running RFSA mode on modified streams could lead to confusion.
saat_stream.exe -i <target_stream> <import_ini> <lookup_file>
Import mode; creates <target_stream> based on the information and filename references in <import_ini>. Also updates <lookup_file> to reflect the changes
Usage (sfx tool):saat_sfx.exe -e <archive_file(s)> <target_dir> <lookup_file>
Export mode; exports all sounds from <archive_file(s)>, storing the WAVe files in an appropriately named subdirectory of <target_dir>.
Uses <lookup_file> to help locate sounds within the archive.
saat_sfx.exe -i <target_archive> <import_ini> <lookup_file>
Import mode; creates <target_archive> based on the information and filename references in <import_ini>. Also updates <lookup_file> to reflect the changes
ACKNOWLEDGEMENTSSAAT is based on the stream export program Radio Free San Andreas (RFSA) by Karl-Johan Karlsson, which was released under the GPL. It also uses and/or modifies other open source code from Marcus Eriksson (RFSA), Ondra Hosek (RFSA for 32-bit Windows), and Michael Smith & Ralph Giles (vorbiscomment program from the vorbis-tools distribution.) Additional contributions to this project (whether they know it or not) were made by Simon El�n (credited by RFSA authors for breaking the stream encoding), Eddie Edwards (author of San Andreas Radio and supplier of most of the original RFSA metadata), and Steve M (GTA Modder Extraordinaire who posted the format of sound effects bank headers to GTA Forums).
SAAT uses the open-source libraries libogg and libvorbis for Ogg Vorbis processing and libsndfile for other sound processing.
LICENSING
(Please see the file COPYING.txt for full details)
The San Andreas Audio Toolkit 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 2 of the License, or (at your option) any later version.
The San Andreas Audio Toolkit 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 the San Andreas Audio Toolkit; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
What follows is the rest of the initial Work-in-Progress post. I will probably be editing out the no longer useful bits soon but I wanted to preserve it for the moment.
====================================
What will SAAT do?Stream toolsExport (simple): Takes an audio stream and exports all the embedded Ogg Vorbis tracks into individual files so that they can be replaced and/or modifed. Also creates an INI file which will control certain aspects of re-importation. The most important INI uses currently are determining the order the files will have in the stream and allowing the modification of the dance moves on the BEATS tracks.
Export (RFSA): Same as the simple export mode with the addition of naming the files descriptively and adding appropriate comment tags to the exported files. SAAT will include a meta-information file similar to that supplied in Radio Free San Andreas and possibly a more generic meta-information file as well.
Import: Reads a list of files and meta-information from an INI file and creates an audio stream ready for use in SA. Also updates the TrakLkup.dat file to reflect the changes, although I have some suspicion that this might be unnecessary.
SFX toolsExport: Takes a sfx archive and exports all the embedded raw sound effects into individual WAVe files so that they can be replaced and/or modifed. Also creates an INI file which will control certain aspects of re-importation. The most important INI uses currently are determining the order the files will have in the archive.
Import: Reads a list of files and meta-information from an INI file and creates a sfx archive ready for use in SA. Also updates the BankLkup.dat file to reflect the changes.
How will SAAT work?SAAT will be a few commands that are run from inside a Command Prompt window. WIN32 binaries and full source code will be released (under GNU GPL.) A simple session might look like this:
Export a stream:c:> saat_stream -e "C:\Program Files\Rockstar Games\GTA San Andreas\audio\streams\BEATS" .\test\export
Replace an Ogg Vorbis file with a new songc:> copy c:\MyNewMusic.ogg .\test\export\BEATS\Track_001.ogg /Y
Edit the saat_import.ini file in notepad to change the dance moves for Track 1. (Note the filename reference doesn't need to be changed because I overwrote the old file above, but I could have left the old file alone and instead changed the reference here.)
Import changes back into game:c:> saat_stream -i "C:\Program Files\Rockstar Games\GTA San Andreas\audio\streams\BEATS" .\test\export\BEATS\saat_import.ini "C:\Program Files\Rockstar Games\GTA San Andreas\audio\CONFIG\TrakLkup.dat"
Play!
What is the current status of the project?
SAAT is still pre-release, but an initial release is planned in the next couple of weeks. The current version can successfully export a stream from SA into a directory full of Ogg Vorbis files and then reimport those files back into a new stream. In testing so far, a new stream made from unmodified export output is identical to the original stream and so is the TrakLkup file. (There is an exception regarding the TrakLkup file -- the lengths of the final 6 Police Band tracks in stream AA are wrong in the original game TrakLkup file; for this reason I have begun to suspect that the TrakLkup file might not always be used by the game.) I have also successfully run the game with a modified stream. (Note: in-game testing was done on PC v1.0)
I want to clean up the stream tool a little bit and add some more robust error-checking of the saat_import INI file and then write the sfx tool before release. Fortunately, a large portion of the stream code can be reused for the sfx tools as many of the processing procedures are the same.
How can you help?For now, if you would be interested in modifying SA audio for whatever reason, you can give me feedback on what I've said so far and also on the following design issues/questions. Once it's stable enough for release, you can try it out and let me know what you like and don't like about it and how it could be better.
Current design questions/issues:Interface: A GUI is not even under consideration for the initial release as I have zero experience with such things. It'll be open source, though, so if someone wants to contribute such an interface later on, they are welcome. That said, the current commandline design specifies almost everything via arguments. A possible change might be the ability to specify certain details (like the location of the game install directory and/or lookup files) in an INI file. Does anyone have a preference on the "arguments vs config file" issue?
Dance beats: The beat information is stored in the stream and will be placed in the saat_import.ini file on export. Currently it looks something like this:
[Track_001]beat_0000.control = 4beat_0000.timing = 18328beat_0001.control = 4beat_0001.timing = 18891[... A whole bunch more ...]beat_0171.control = 3beat_0171.timing = 138219beat_0172.control = 2beat_0172.timing = 138750beat_0173.control = 33beat_0173.timing = 140750beat_total = 174
The timings are in absolute milliseconds and the controls are integers which correspond to button presses. Possible enhancements would be allowing human-readable control definitions and using relative timing rather than absolute. So the above might look something like this:
[Track_001]beat_0000.control = RIGHTbeat_0000.timing = 18328beat_0001.control = RIGHTbeat_0001.timing = 563[... A whole bunch more ...]beat_0171.control = UPbeat_0171.timing = 547beat_0172.control = LEFTbeat_0172.timing = 531beat_0173.control = ENDbeat_0173.timing = 2000beat_total = 174
(Note, dance tracks use controls 1-4 (Down/Left/Up/Right on PC) and Lowrider tracks use 9-16 (some of which are also Down/Left/Up/Right) so there would need to be some way to differentiate which "Up" one meant if some kind of human-readable shortcut was used...) Any preferences on relative vs absolute timings or comments on control references?
Tagging: The RFSA export mode tags/names the exported tracks. A question is what happens to these tags when the files are re-imported? Currently, nothing is done to imported Ogg Vorbis files. The advantage of this is that the tags will be preserved if the stream is later exported via simple export mode. The disadvantage is that comments do take up space and the comments are meaningless to the game. Possible future changes would be allowing stripping of comments when imported. Any comments on how you would like this stuff to be handled?
Backups: The current pre-release version doesn't back up anything. It might be a good idea to auto-backup the lookup files on import since they are small, but the streams/archives can get huge and I'm hesitant to make humongous backups without the user asking first. An alternative would be some sort of specification (config file or switch, probably config file) to backup the lookup and/or archive files. Any comments here?
SFX export layout: (Edited in 03Dec05.) The sound effects archives are made up of "sound banks" which are collections of between 1 and 400 sounds. So, for instance the smallest archive, FEET, looks like this:
FEET Archive (7 banks, 38 total sounds)\--Bank 0 (9 sounds)| \--Sound 0 ... Sound 8| \--Bank 1 (5 sounds)| \--Sound 0 ... Sound 4| \--Bank 2 (5 sounds)| \--Sound 0 ... Sound 4| \--Bank 3 (5 sounds)| \--Sound 0 ... Sound 4| \--Bank 4 (4 sounds)| \--Sound 0 ... Sound 3| \--Bank 5 (5 sounds)| \--Sound 0 ... Sound 4| \--Bank 6 (5 sounds) \--Sound 0 ... Sound 4
The two obvious approaches to exportation are:
a) Create subdirectories for each bank so that the directory structure looks very much like the ASCII picture above (with a single INI file in the root directory) or
b) Save all the files in a single directory (with filenames like BankXXX_SoundYYY.wav or perhaps simply SoundXXXXX.wav)
The idea of bank subdirectories (a) appeals to me, in part because I simply hate the idea of having a directory containing a huge number of files. In the case of the largest archive, SPC_GA, option (a) would result in 209 Bank_XXX subdirectories; the smallest of these subdirectories would have a single file and the largest would have 264 files. However, option (b) would result in a single directory of 31,234 sound files plus the import INI. That bothers me and so I lean towards (a), but the relevant question would be whether the use of such subdirectories would be overly confusing to the user, in which case I'd have to go with (b). Any thoughts on this one?
Some reference links:
Music Files thread -- Bits and pieces about stream formats and previous extraction-only toolsRadio Editing thread -- Some (still) unanswered questions on radio stations and a bit about lookup formats.Radio Free San Andreas, aka RFSA SAAT probably wouldn't exist without this as it is the basis for the SAAT export routines.
GTA3/VC SFX thread -- A tiny bit of SA discussion on the end; file formats are different but general modding is similar.San Andreas SFX Directory -- My contribution of an early directory of SA SFX meant for the above thread, but hosted elsewhere because of its sizeEdits: 03Dec05 -- Added question on SFX export layout.05Dec05 -- Got SFX export working (using Bank subdirectories), although I had to write the WAVe headers myself; am holding off on SFX import for a day or two while I investigate using libsndfile or similar conversion library to give more format options. If I can get import working, I may release a beta for further testing. Also added some more reference links to this post30Dec05 -- Pushed back release to 07Jan06. It's looking good, but I need a bit more time to hammer on it.07Jan06 -- Initial release; first post heavily edited.08Jan06 -- Rapidshare mirror download link added.10Jan06 -- GTA Garage submission approved; added links09Feb08 -- Links to both GUI add-ons and the SFX directory now have prominent placement