AGSC (File Format)

From Retro Modding Wiki
Revision as of 14:36, 3 February 2015 by >Aruki (→‎Format)
Jump to navigation Jump to search

AGSC is the sound effect format for Metroid Prime and Metroid Prime 2: Echoes. Each AGSC file contains a group of sound effects. The first two Metroid Prime games utilize the MusyX audio engine created by Factor5 and as a result, AGSC files are created by utilizing files generated from MusyX's SDK.

According to the debug maps in Metroid Prime, there are references to various "classes", with one of them controlling audio in the map, known as AudioGroupSet. So presumably, AGSC is an abbreviation for Audio Group Set Class or Audio Group Set Cooked, as all the game data had to be cooked into their final formats.

The audio codec used in AGSC is the standard GameCube DSP ADPCM codec, as described in the GameCube SDK.

This file format needs more research
The proj chunk and the sdir chunk still need some reverse-engineering.

Format

The AGSC format is essentially four data chunks combined into one resource, each of which is a standard MusyX file. Of the four data chunks (pool, proj, samp, and sdir), there's one for sound engine scripts, one for sound properties, one for actual ADPCM sound data, and one for sound metadata. The main difference between Prime 1 and 2 is the header, and some slight changes in the way the four chunks are organized. In Metroid Prime, each chunk begins with its own size value; in Metroid Prime 2, every chunk instead has its size listed at the beginning of the file, at the end of the header. In addition, in Metroid Prime, the third chunk is samp, and the fourth is sdir; in Metroid Prime 2, it's the other way around.

Header

Metroid Prime

Offset Size Description
0x0 D Audio Directory. Always "Audio/." Zero-terminated.
0x0 + D N Audio Group Name. Zero-terminated.
0x0 + D + N End of header

Metroid Prime 2

Offset Size Description
0x0 4 Unknown; always 1
0x4 D Audio Group Name. Zero-terminated.
0x4 + D 4 Chunk 1 size
0x8 + D 4 Chunk 2 size
0xC + D 4 Sound metadata chunk size
0x10 + D 4 ADPCM chunk size
0x14 + D End of header

Pool

The Pool chunk denotes MusyX's "SoundMacros", small scripts that apply various effects and commands on the sounds in the game. The chunk first calls out a command ID then the parameters of that particular command, which varies.

Every 4 bytes were originally little endian, but have been swapped to big endian in the AGSC files (despite not being longs). To read the data as originally formatted, every four bytes needs to be byte-swapped.

Offset Size Description
0x0 1 Command ID (varies; there are 79 known commands in the MusyX audio engine.)
0x1 7 Command arguments (varies between commands)
0x8 End of entry

The Soundmacro terminates when the END command is read. The command ID for END is 0 and has no command arguments, so when 0x00000000 is read, start the next SoundMacro. The entire chunk terminates when 0xFFFF is read.

Project

The Project properties chunk contains values for the sounds, including priority, polyphony, volume, etc.

Sample

The Sample chunk is all the sound data encoded using the standard Gamecube DSP ADPCM codec. It can be decoded the same way as a DSP file. Each sound's size is padded to 32 bytes before the next sound's data begins.

Sample Directory chunk

The Sample Directory chunk (chunk 4 in Metroid Prime, chunk 3 in Metroid Prime 2) is made up of two sets of tables. The structure of both these tables is identical between both games.

Table A

The first metadata table has one entry per sound, and is terminated with 0xFFFFFFFF; since there's no known sound count anywhere in the file, the only way to read this correctly is to read until you reach the terminator value. Each entry is 0x20 bytes long.

Offset Size Description
0x0 2 Sound ID (note: not 100% confirmed)
0x2 2 Padding.
0x4 4 Sound start offset, relative to the start of the ADPCM chunk
0x8 4 Unknown
0xC 2 Unknown; appears to always be 0x3C00
0xE 2 Sample rate
0x10 4 Number of samples
0x14 4 Loop start sample
0x18 4 Loop length, in samples. To get the loop end sample, add this to the start sample and subtract 1.
0x1C 4 Table B entry offset, relative to the start of the sound metadata chunk
0x20 End of entry

Table B

These are accessed through the offsets in table A's entries; note that it might not match the sound count, because the same entry in this table can be used with multiple sounds. Each entry is 0x28 bytes long.

Offset Size Description
0x0 2 Unknown
0x2 2 Unknown
0x4 4 Unknown
0x8 2 × 16 Decode coefficients
0x28 End of entry

ADPCM Data

This data is formatted using the standard GameCube ADPCM codec, and can be decoded the same way as a DSP file. Each sound's size is padded to 32 bytes before the next sound's data begins.

Tools