· 8 years ago · Mar 04, 2018, 03:20 AM
1
2 The San Andreas Audio Toolkit (SAAT) User Manual
3
4Current Version: 1.10
5
6 The San Andreas Audio Toolkit (SAAT) is a set of commandline tools useful
7 for modding the PC version of the video game Grand Theft Auto: San Andreas.
8 SAAT allows the importing of music files into SA audio streams and the
9 importing of WAVe files into SA sfx archives. It will also necessarily
10 allow exporting from each type of archive into individual files.
11
12 SAAT was written by Dave Schmitt (AKA "P.D. Escobar") in C++; it is an
13 open-source program released under the [1]GNU General Public License. It
14 was based on the open-source program [2]Radio Free San Andreas and uses
15 several open-source libraries: [3]libogg and libvorbis for Ogg Vorbis
16 processing and [4]libsndfile for other sound processing.
17
18Resources
19
20 Download Locations for Version 1.10
21
22 SAAT is distributed in two primary locations.
23 * From the official website:
24 [5]http://pdescobar.home.comcast.net/gta/saat/SAAT_release_1_10.zip
25 * From GTA Garage: [6]http://www.gtagarage.com/mods/show.php?id=1186
26
27 Official Website
28
29 The official SAAT website is
30 [7]http://pdescobar.home.comcast.net/gta/saat/. It contains the most recent
31 version of this README file, other documentation, and the distribution
32 downloads.
33
34 Feedback
35
36 The main place for discussion and feedback on SAAT is its GTA Forums
37 thread: [8]http://www.gtaforums.com/index.php?showtopic=225049. You may
38 also contact the author directly via email at <pdescobar@comcast.net>.
39
40Installation
41
42 Windows Binaries
43
44 To install, simply unzip the archive and copy/move saat_stream.exe,
45 saat_sfx.exe, and all INI files to a useful location such as the GTASA main
46 directory. To use, follow the directions below and then follow the usage or
47 examples.
48 1. Open a Command Prompt window. On Windows XP this is done by choosing
49 Start -> All Programs -> Accessories -> Command Prompt.
50 2. In the Command Prompt window, type the name of the drive where you
51 installed the executables and hit return. For example, if you installed
52 the executables to drive D: you would type
53 D:
54 and then return.
55 3. Change to the directory where you installed the executables by using
56 the cd command. For example, if you installed the executables to
57 D:\Program Files\Rockstar Games\GTA San Andreas you would type
58 cd "D:\Program Files\Rockstar Games\GTA San Andreas"
59 and then return.
60 4. You are now ready to use the program; see the usage or examples for
61 more.
62
63 Source
64
65 To install from source, unzip the full archive and open a command prompt to
66 the src directory. Open Makefile in an editor and change the PLATFORM
67 variable to a value useful for your environment, editing as necessary. Then
68 simply type 'make' in the source directory to compile. After compilation,
69 you would follow the instructions for the binary installation above.
70
71Usage
72
73 Stream tool
74
75saat_stream.exe -e <stream_file(s)> <target_dir>
76 Simple export mode; exports all tracks from <stream_file(s)>, storing the Ogg
77 Vorbis files in an appropriately named subdirectory of <target_dir>.
78
79saat_stream.exe -r <stream_file(s)> <target_dir> <metadata_file>
80 RFSA export mode; like -e but uses contents of <metadata_file> for additional
81 descriptive information to tag and name the exported files.
82 Note: running RFSA mode on modified streams could lead to confusion.
83
84saat_stream.exe -i <target_stream> <import_ini> <lookup_file>
85 Import mode; creates <target_stream> based on the information and filename
86 references in <import_ini>. Also updates <lookup_file> to reflect the changes
87
88 SFX tool
89
90saat_sfx.exe -e <archive_file(s)> <target_dir> <lookup_file>
91 Export mode; exports all sounds from <archive_file(s)>, storing the WAVe
92 files in an appropriately named subdirectory of <target_dir>.
93 Uses <lookup_file> to help locate sounds within the archive.
94
95saat_sfx.exe -i <target_archive> <import_ini> <lookup_file>
96 Import mode; creates <target_archive> based on the information and filename
97 references in <import_ini>. Also updates <lookup_file> to reflect the changes
98
99Examples
100
101 I. Stream Tool
102
103 A. Exporting streams example: BEATS
104 Assumptions:
105 + This example assumes that GTASA is installed to the directory
106 c:\Program Files\Rockstar Games\GTA San Andreas\.
107 + It also assumes that saat_stream.exe is in that directory.
108 + It further assumes that directory c:\temp exists and is usable.
109 Steps:
110 1. Open a command prompt window and change to the GTASA install
111 directory
112 2. At the command prompt type the following:
113 saat_stream -e audio\streams\BEATS c:\temp\saat
114 3. This will create a directory called c:\temp\saat\BEATS which will
115 contain the 10 Ogg Vorbis tracks from that stream (files named
116 simply such as "Track_001.ogg") and a file called
117 stream_import.ini which can be used to import any changes.
118 B. Exporting streams with metadata example: BEATS
119 Assumptions:
120 + This example assumes that GTASA is installed to the directory
121 c:\Program Files\Rockstar Games\GTA San Andreas\.
122 + It also assumes that saat_stream.exe and metadata-full.ini are in
123 that directory.
124 + It further assumes that directory c:\temp exists and is usable.
125 Steps:
126 1. Open a command prompt window and change to the GTASA install
127 directory
128 2. At the command prompt type the following:
129 saat_stream -r audio\streams\BEATS c:\temp\saat metadata-full.ini
130 3. This will create a directory called c:\temp\saat\Beats which will
131 contain the 10 Ogg Vorbis tracks from that stream (files named
132 descriptively such as "Club Dance Track #2 (Hollywood
133 Swingin').ogg" & tagged with appropriate comments) and a file
134 called stream_import.ini which can be used to import any changes.
135 C. Importing streams example: Replacing two dance tracks.
136 Assumptions:
137 + This example assumes you've done the above BEATS export (example
138 A) and it makes all of the same assumptions that example A makes.
139 + It also assumes that you have a file somewhere called "New
140 Dance.ogg"
141 + It further assumes that you have a second file
142 c:\music\dance_mix.ogg
143 Steps:
144 1. Copy "New Dance.ogg" into the c:\temp\saat\BEATS directory.
145 2. Open c:\temp\saat\BEATS\stream_import.ini in notepad and look in
146 the section [Track_003] (this is originally "Funky President")
147 3. Change the line which says "filename = Track_003.ogg" so that it
148 says "filename = New Theme.ogg"
149 4. Now look in the section [Track_004] (this is originally "Nuthin'
150 But a 'G' Thang")
151 5. Change the line which says "filename = Track_004.ogg" so that it
152 says "filename = c:\music\dance_mix.ogg"
153 6. Save the changes and exit notepad.
154 7. Backup your original BEATS audio stream and the TrakLkup.dat file
155 Using the game directory from the example, these files would be:
156 c:\Program Files\Rockstar Games\GTA San
157 Andreas\audio\streams\BEATS
158 c:\Program Files\Rockstar Games\GTA San
159 Andreas\audio\CONFIG\TrakLkup.dat
160 8. Go back to the command prompt from the previous example and type:
161 saat_stream -i audio\streams\BEATS c:\temp\saat\BEATS\stream_import.ini audio\CONFIG\TrakLkup.dat
162 9. Start a new game, head to the dance club, enter the red marker and
163 hear your new music.
164 10. Note, the dance moves remain unchanged from the original songs in
165 this example.
166
167 II. SFX Tool
168
169 A. Exporting sound effects example: GENRL
170 Assumptions:
171 + This example assumes that GTASA is installed to the directory
172 c:\Program Files\Rockstar Games\GTA San Andreas\.
173 + This example assumes that GTASA is installed to the directory
174 c:\Program Files\Rockstar Games\GTA San Andreas\
175 + It also assumes that saat_sfx.exe is in that directory
176 + It further assumes that directory c:\temp exists and is usable
177 Steps:
178 1. Open a command prompt window and cd to the GTASA install directory
179 2. At the command prompt type the following:
180 saat_sfx -e audio\SFX\GENRL c:\temp\saat audio\CONFIG\BankLkup.dat
181 3. This will create a directory called c:\temp\saat\GENRL which will
182 contain a file called sfx_import.ini and 137 Bank_XXX
183 subdirectories; each of these directories will contain WAV format
184 sound files.
185 B. Importing sound effects example: Changing the emergency vehicle siren.
186 Assumptions:
187 + This example assumes you've done the above GENRL export and
188 assumes all of the same things that example assumed.
189 + It also assumes that you have a 16-bit PCM mono WAV file somewhere
190 called "siren.wav"; the sample rate of the sound shouldn't matter.
191 Steps:
192 1. Open c:\temp\saat\GENRL\sfx_import.ini in notepad and look in the
193 section [Bank_068]
194 2. Copy siren.wav to the c:\temp\saat\GENRL directory.
195 3. The main siren is sound 011 and the alternate siren that plays
196 when you use the horn is sound 012. Assuming we want to replace
197 the main siren, change the line "sound_011.filename =
198 Bank_068\sound_011.wav" to instead say "sound_011.filename =
199 siren.wav"
200 4. Save the changes and exit notepad.
201 5. Backup your original GENRL sfx archive and the BankLkup.dat file
202 Using the game directory from the example, these files would be:
203 c:\Program Files\Rockstar Games\GTA San Andreas\audio\SFX\GENRL
204 c:\Program Files\Rockstar Games\GTA San
205 Andreas\audio\CONFIG\BankLkup.dat
206 6. Go back to the command prompt from the previous example and type:
207 saat_sfx -i audio\SFX\GENRL c:\temp\saat\GENRL\sfx_import.ini audio\CONFIG\BankLkup.dat
208 7. Load a game, grab an emergency vehicle and enjoy your new siren.
209
210Notes on import formats
211
212 In order for your sounds to play correctly in the game, they must be in the
213 proper format. Thus, it will be highly useful to have an audio editor or
214 conversion program available. There are many such programs, but one of note
215 is Audacity. I single out Audacity because it is an open source audio
216 editor and it is one of the tools used to test SAAT. Audacity is available
217 at [9]http://audacity.sourceforge.net/
218
219 Streams
220
221 Currently, SAAT will only accept Ogg Vorbis files for stream import. The
222 bitrate shouldn't matter but the unmodified game uses variable bitrate
223 files so that would be the preference. The most important thing is that the
224 Ogg Vorbis files must be in stereo. If you import a mono file, it will play
225 at double speed resulting in a "chipmunk" effect. If you have a mono file,
226 make a stereo file out of it by duplicating the original single track for
227 both the left and right channels before importing.
228
229 Also note that there appear to be some minimum length restrictions on
230 stream tracks. In testing, very short (< 2 seconds) sounds worked fine for
231 AMBIENCE sounds, but caused problems when used as part of radio songs.
232 Within the radio streams, all radio songs/shows are broken up into several
233 pieces. There are one or more small "intro" segments, a large "mid"
234 segment, and one or more small "outro" segments. When the track is played,
235 the game randomly picks an intro and outro and then plays the three
236 selected pieces in order. In the unmodified game, the shortest pieces are
237 in the area of 7-10 seconds. In limited testing, pieces of 5 seconds or
238 less seemed to confuse the game and cause long pauses of "dead air" after
239 the piece was played. More testing should be done in this area, but for now
240 be cautious about using very short song pieces.
241
242 Sound Effects
243
244 SAAT can handle most of the file formats that libsndfile can process. Since
245 all the original sound effects are mono, 16-bit integer (little endian),
246 PCM (uncompressed) WAVe files (without headers,) that is the preferred
247 format. As with the streams, the most important thing is that it is a mono
248 sound. If you have a stereo sound, you must mix it down to a single channel
249 before you import it. Otherwise, in the game it will play at half speed.
250 You should not have to worry about the sample rate as the game uses
251 whatever rate it is told to use; however, the sample rate of the exported
252 sound is listed in the import INI file. This will allow you to ensure the
253 replacement sound uses the same rate if you would like to be extra
254 cautious.
255
256 The following formats have worked in testing and will probably work for
257 you:
258 * mono 16-bit PCM WAV (preferred as no internal conversion is necessary)
259 * mono 8-bit PCM WAV
260 * mono 4-bit MS ADPCM WAV
261 * mono 4-bit IMA ADPCM WAV
262 * mono 16-bit PCM AIFF
263 * mono 8-bit PCM AIFF
264 * mono 16-bit PCM AU
265 * mono 8-bit ULAW AU
266
267 The following formats have not worked in testing and should be avoided:
268 * mono 32-bit float WAV
269 * mono 32-bit float AIFF
270 * mono headerless RAW
271 * stereo anything (see notes above)
272
273 These formats may be supported in future versions of SAAT.
274
275 For other formats, if it is supported for reading by libsndfile, there is a
276 chance it will work. Feel free to experiment with such formats and report
277 back to the author so it can be included in the documentation of future
278 versions. The libsndfile homepage is
279 [10]http://www.mega-nerd.com/libsndfile/
280
281 One final note, imported sfx files must be less than 10MB. Anything over
282 that will definitely cause a problem, and sfx files close to that might
283 cause a problem. Since the largest sound in the unmodified game is
284 approximately .5 MB this really shouldn't be an issue.
285
286Useful INI values
287
288 SAAT uses INI files for a variety of purposes. Currently, there are three
289 main types of INI files: metadata files, stream import files, and sfx
290 import files. What follows are brief format outlines and useful values for
291 these.
292
293I. metadata INI files
294
295 Because SAAT was born of RFSA, it uses an INI file for metadata information
296 when doing stream exports.
297
298 A. [global] section
299
300 The metadata INI should have a [global] section for tagging
301 information relevant to every stream in the game. In this section,
302 two key strings are useful.
303
304 1. albumprefix -- The ALBUM tag for each file will be comosed of this
305 prefix followed by the 'station' name for the stream.
306
307 2. defaultartist -- If ARTIST tag information is not given for an
308 individual track or individual stream, this is used; it is the last
309 resort and if missing, the hardcoded default is "Rockstar North"
310
311 B. stream sections (md5 string or basename)
312
313 RFSA used an MD5 checksum as the stream identifier. In order to
314 maintain RFSA compatibility, these checksums can still be used, but
315 due to the SAAT implementation, they are faked. That means that the
316 checksum [8a388107cdf3934b3f7a3f1e2b33199c] will be interpreted as
317 the AA stream regardless of the actual contents of AA.
318
319 SAAT also allows a more simple basename as the stream identifier.
320 Thus, information for stream AA can be placed in a section [AA]
321 This is the preferred identifier and will be used first if found.
322
323 In stream sections the following key strings are useful. Note that
324 most are of the form "trackX.YYYY"; these are track-specific and
325 only apply to track 'X'. For example, track5.title is the title
326 for track 5.
327
328 1. stream -- unused by the program; mere description in the supplied
329 metadata-full.ini so that the user knows at a glance which stream
330 the section applies to since most people don't know the md5 sums.
331
332 2. station -- used as the subdirectory name for the exported tracks
333 and as part of the ALBUM tag for each track in the stream.
334
335 3. defaultartist -- default ARTIST tag for the stream; generally the
336 voice actor for the station DJ(s).
337
338 4. trackX.title -- TITLE tag for the track and default filename;
339 if it is used for the filename, ".ogg" is appended and it may be
340 sanitized to remove problem characters.
341
342 5. trackX.filename -- specific filename to override use of title. If
343 not present, trackX.title is used; if neither is present the
344 hardcoded default of "Track_xxx.ogg" is used.
345
346 6. trackX.artist -- ARTIST tag for the track. If not present, the
347 stream defaultartist is used; if neither is present, the [global]
348 defaultartist is used.
349
350II. stream import INI files
351
352 Information related to how to build a stream when importing is stored
353 in a stream import INI file. Such a file is automatically generated
354 when exporting, but in theory could be created from scratch.
355
356 A. [Stream] section
357
358 The stream import INI must have a [Stream] section for global
359 stream-related information. Note the capitalization. In this section,
360 the following key strings are useful.
361
362 1. basename -- currently unused by importer; contains the base filename
363 of the stream which was exported
364
365 2. lookup_index -- in order to pick out the proper track in the stream
366 archive, the game uses a lookup table called TrakLkup.dat; this is
367 the index of the imported stream within that file. You should only
368 change this if you really know what you are doing. Note that if
369 you export from a stream with a nonstandard name, SAAT will warn
370 and set the lookup_index to -1; in that case you must change it
371 to a valid value before importing with that INI. In the unmodified
372 game, the following indices are used for the streams:
373
374 0 = AA (Police)
375 1 = ADVERTS
376 2 is unused by the game
377 3 = AMBIENCE
378 4 = BEATS
379 5 = CH (Playback)
380 6 = CO (KROSE)
381 7 = CR (KDST)
382 8 = CUTSCENE
383 9 = DS (Bounce FM)
384 10 = HC (SFUR)
385 11 = MH (Radio Los Santos)
386 12 = MR (Radio X)
387 13 = NJ (CSR)
388 14 = RE (KJAH West)
389 15 = RG (MasterSounds)
390 16 = TK (WCTR)
391
392 3. num_tracks -- the number of actual tracks in the stream; this really
393 should not be changed and there must be an equivalent number of
394 [Track_XXX] sections or bad things will happen.
395
396 B. Track sections
397
398 The stream import INI must have a [Track_XXX] section for each track
399 which will be imported into the stream. The first track will use
400 section [Track_001], the second [Track_002], etc. Useful key strings:
401
402 1. beat_total -- If a given track will be used for the Dance minigame
403 or the LowRider Challenge minigame, it must have the "beat"
404 information defined in the stream. If the beat_total is 0, there
405 will be no such information stored in the stream. However, if the
406 beat_total is nonzero then the track section should contain the
407 beat information which will be imported. In the unmodified game,
408 only 6 tracks in the BEATS stream contain such information.
409
410 2. beat_YYY.timing -- If the track has beats, there should be timings
411 defined for each one. Thus if your beat_total is 170 there should
412 be 170 separate beat_YYY.timing entries numbered consecutively
413 from beat_000.timing through beat_169.timing; they don't necessarily
414 have to be listed in numerical order. Each timing value is the number
415 of elapsed miliseconds from the start of the song when the beat
416 should be entered. As such, beat_001.timing should be a higher
417 value than beat_000.timing and so on. If this is not the case, SAAT
418 will warn you on import and attempt to adjust the timings.
419
420 3. beat_YYY.control -- If the track has beats, there should be controls
421 defined for each one. Thus if your beat_total is 170 there should
422 be 170 separate beat_YYY.control entries numbered consecutively
423 from beat_000.control through beat_169.control; they don't
424 necessarily have to be listed in numerical order. Each control
425 value is an identifier for which key must be pressed to enter that
426 beat. The following control values are useful and dance values
427 probably should not be mixed with bounce values; invalid controls
428 will cause SAAT to warn you on import and prematurely end the beats.
429
430 Dance Controls LowRider Challenge Bounce Controls
431 1 = Down Arrow 9 = Right (6) 13 = Up (8)
432 2 = Left Arrow 10 = Left (4) 14 = Down (2)
433 3 = Up Arrow 11 = Up/Rt (8+6) 15 = Up/Lt (8+4)
434 4 = Right Arrow 12 = Dn/Lt (2+4) 16 = Dn/Rt (2+6)
435
436 33 = Beat End token (should be the last defined control)
437
438 4. filename -- The name of the sound file which is being imported for
439 this track. This can be a relative path ("foo.ogg", "..\bar\baz.ogg")
440 or an absolute local path ("\temp\moo.ogg", "C:\music\my song.ogg").
441 The filename should not be quoted in any way and embedded spaces
442 are okay. The INI file will be scanned on import and missing/invalid
443 filenames will cause an error and the import will be aborted.
444
445 5. length_index -- The length of the Ogg Vorbis file is stored in the
446 track header within the stream; however, the position of this length
447 varies somewhat. Tracks which have beat information generally use
448 a length_index of 1 while other tracks use a length_index of 0. This
449 value is stored in the INI on export and shouldn't be changed.
450
451 6. length_extra -- There is an unknown 32-bit integer value stored in
452 the track header after the length. It looks like it may have once
453 been intended as a sample rate but is now probably unused. To be
454 cautious, this value is stored in the INI on export and probably
455 shouldn't be changed. For the curious, most tracks have 48000 here,
456 but all the AMBIENCE tracks use 24000. Additionally, most of the
457 CUTSCENE tracks use 0 aside from a couple 48000s and one 25137.
458
459III. sfx import INI files
460
461 Information related to how to build a sfx archive when importing is stored
462 in a sfx import INI file. Such a file is automatically generated
463 when exporting, but in theory could be created from scratch.
464
465 A. [Archive] section
466
467 The sfx import INI must have an [Archive] section for global
468 archive-related information. Note the capitalization. In this section,
469 the following key strings are useful.
470
471 1. basename -- currently unused by importer; contains the base filename
472 of the archive which was exported.
473
474 2. lookup_index -- in order to pick out the proper sound from the sfx
475 archive, the game uses a lookup table called BankLkup.dat; this is
476 the index of the imported archive within that file. You should only
477 change this if you really know what you are doing. Note that if
478 you export from a archive with a nonstandard name, SAAT will warn
479 and set the lookup_index to -1; in that case you must change it
480 to a valid value before importing with that INI. In the unmodified
481 game, the following indices are used for the archives:
482
483 0 = FEET
484 1 = GENRL
485 2 = PAIN_A
486 3 = SCRIPT
487 4 = SPC_EA
488 5 = SPC_FA
489 6 = SPC_GA
490 7 = SPC_NA
491 8 = SPC_PA
492
493 3. num_banks -- sfx archives are divided up into several sound "banks"
494 which each contain between 1 and 400 actual sound effects. This is
495 the number of sound banks within the archive; this really
496 should not be changed and there must be an equivalent number of
497 [Bank_XXX] sections or bad things will happen.
498
499 B. Bank sections
500
501 In bank sections the following key strings are useful. Note that
502 most are of the form "sound_YYY.ZZZZ" ; these are specific to an
503 individual sound effect. For example sound004.filename is the
504 filename of the fourth sound in the bank.
505
506 1. num_sounds -- This is the number of sound effects within the bank.
507 Once again, it really shouldn't be changed and there should be
508 an equivalent number of sound_YYY.ZZZZ entries in the bank section.
509
510 2. sound_YYY.filename -- The name of the sound file which is being
511 imported. This can be a relative path ("foo.wav", "..\bar\baz.wav")
512 or an absolute local path ("\temp\moo.wav", "C:\sound\cool sfx.wav").
513 The filename should not be quoted in any way and embedded spaces
514 are okay. The INI file will be scanned on import and missing/invalid
515 filenames will cause an error and the import will be aborted.
516
517 3. sound_YYY.sample_rate -- The sample rate of the exported sound
518 effect. This is for informational purposes only in case you wish
519 to save your replacement sound at the same rate as the original.
520
521 4. sound_YYY.unknown_16 -- There is an unknown 16-bit integer value
522 stored in the bank header for each sound after the sample rate.
523 The most common value is 0 but a wide variety of non-zero values
524 are also seen. If a given sound entry has a non-zero value, it is
525 stored on export with this key string. It is probably a bad idea
526 to change this value or to add this key with a different value.
527
528 5. sound_YYY.unknown_32 -- There is an unknown 32-bit integer value
529 stored in the bank header for each sound. The standard value used
530 is -1, but if a given sound entry has a non-standard value, it is
531 stored on export with this key string. It is probably a bad idea
532 to change this value or to add this key with a non-standard value.
533
534End of SAAT User Manual
535
536References
537
538 1. http://www.gnu.org/licenses/licenses.html#GPL
539 2. http://www.lysator.liu.se/~creideiki/radio-free-san-andreas/
540 3. http://www.xiph.org/downloads/
541 4. http://www.mega-nerd.com/libsndfile/
542 5. http://pdescobar.home.comcast.net/gta/saat/SAAT_release_1_10.zip
543 6. http://www.gtagarage.com/mods/show.php?id=1186
544 7. http://pdescobar.home.comcast.net/gta/saat/
545 8. http://www.gtaforums.com/index.php?showtopic=225049
546 9. http://audacity.sourceforge.net/
547 10. http://www.mega-nerd.com/libsndfile/