AGSC (File Format)
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 essentially just embedded MusyX files.
The audio codec used in AGSC is the standard GameCube DSP ADPCM codec.
|
To do: Better descriptions for how SoundMacros work and a description for what each command does. |
|
This file format needs more research The proj chunk and the sdir chunk still need some reverse-engineering. |
Contents
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 | Pool size |
| 0x8 + D | 4 | Project size |
| 0xC + D | 4 | Sample size |
| 0x10 + D | 4 | Sample directory size |
| 0x14 + D | End of header | |
Pool
The Pool chunk denotes MusyX's SoundMacros, small scripts that apply various effects on the sounds in the game. Each macro is composed of a number of pre-defined commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.
Each 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.
Each command is structured as follows:
| 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 executed. The command ID for END is 0 and has null command arguments; the next SoundMacro begins after reading it. The entire Pool chunk is terminated by a value of 0xFFFFFFFF.
These are the possible commands:
| ID | Name | Arguments | ||||||
|---|---|---|---|---|---|---|---|---|
| 0x1 | STOP | |||||||
| 0x2 | SPLITKEY | Keynumber | SoundMacro ID | SoundMacro step | ||||
| 0x3 | SPLITVEL | Velocity | SoundMacro ID | SoundMacro step | ||||
| 0x4 | WAIT_TICKS | Keyoff | Random | Sampleend | Absolute | ms switch | Ticks/Millisec. | |
| 0x5 | LOOP | Keyoff | Random | Sampleend | SoundMacro step | Times | ||
| 0x6 | GOTO | SoundMacro ID | SoundMacro step | |||||
| 0x7 | WAIT_MS | Keyoff | Random | Sample end | Absolute | Millisec. | ||
| 0x8 | PLAYMACRO | Addnote | SoundMacro ID | SoundMacro step | Priority | MaxVoices | ||
| 0x9 | SENDKEYOFF | Variable | Last started | |||||
| 0xA | SPLITMOD | Mod value | SoundMacro ID | SoundMacro step | ||||
| 0xB | PIANOPAN | Scale | Centerkey | Centerpan | ||||
| 0xC | SETADSR | Table-ID (ADSR) | DLS mode | |||||
| 0xD | SCALEVOLUME | Scale | Add | Table-ID (Curve) | Org vol | |||
| 0xE | PANNING | Pan position | Time ms | Width | ||||
| 0xF | ENVELOPE | Scale | Add | Table-ID (Curve) | Org vol | |||
| 0x10 | STARTSAMPLE | Sample-ID | Mode | Offset | ||||
| 0x11 | STOPSAMPLE | |||||||
| 0x12 | KEYOFF | |||||||
| 0x13 | SPLITRND | RND | SoundMacro ID | SoundMacro step | ||||
| 0x14 | FADE-IN | Scale | Add | Table-ID (Curve) | ms switch | Ticks/Millisec. | ||
| 0x15 | SPANNING | Pan position | Time ms | Width | ||||
| 0x16 | SETADSRCTRL | Attack | Decay | Sustain | Relase | |||
| 0x17 | RNDNOTE | Note Lo | Detune | Note Hi | Fixed/Free | Abs/Rel | ||
| 0x18 | ADDNOTE | Add | Detune | org key | ms switch | Ticks/Millisec. | ||
| 0x19 | SETNOTE | Key | Detune | ms switch | Ticks/Millisec. | |||
| 0x1A | LASTNOTE | Add | detune | ms switch | Ticks/Millisec. | |||
| 0x1B | PORTAMENTO | Port. State | Port. Type | ms switch | Ticks/Millisec. | |||
| 0x1C | VIBRATO | Level note | Level fine | Modwheel flag | ms switch | Ticks/Millisec. | ||
| 0x1D | PITCHSWEEP1 | Times | Add | ms switch | Ticks/Millisec. | |||
| 0x1E | PITCHSWEEP2 | Times | Add | ms switch | Ticks/Millisec. | |||
| 0x1F | SETPITCH | Frequency (Hz) | Fine | |||||
| 0x20 | SETPITCHADSR | Table-ID (ADSR) | Note range | Detune range | ||||
| 0x21 | SCALEVOLUME DLS | Scale | Org vol | |||||
| 0x22 | MOD2VIBRANGE | Key range | Cent range | |||||
| 0x23 | SETUP TREMOLO | Tremolo scale | Modw. add scale | |||||
| 0x24 | RETURN | |||||||
| 0x25 | GOSUB | SoundMacro ID | SoundMacro step | |||||
| 0x28 | TRAP_EVENT | Event | SoundMacro ID | SoundMacro step | ||||
| 0x29 | SEND_MESSAGE | IsVar | Macro | VID | Varibale | |||
| 0x2A | GET_MESSAGE | Varibale | ||||||
| 0x2B | GET_VID | Varibale | PLAY_MACRO | |||||
| 0x30 | ADDAGECOUNT | Add | ||||||
| 0x31 | SETAGECOUNT | Counter | ||||||
| 0x32 | SENDFLAG | Flag-ID | Value | |||||
| 0x33 | PITCHWHEELR | Range up | Range down | |||||
| 0x34 | SETPRIORITY | Prio | ||||||
| 0x35 | ADDPRIORITY | Add | ||||||
| 0x36 | AGECNTSPEED | Time | ||||||
| 0x37 | AGECNTVEL | AGE Base | AGE Scale | |||||
| 0x40 | VOL_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x41 | PAN_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x42 | PitchW_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x43 | ModW_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x44 | PEDAL_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x45 | PORTA_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x46 | REVERB_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x47 | SPAN_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x48 | DOPPLER_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x49 | TREMOLO_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x4A | PREA_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x4B | PREB_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x4C | POSTB_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x4D | AUXAFX_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x4E | AUXBFX_SELECT | MIDI Contr. | Scaling percentage | Combine | is var. | Fine scaling | ||
| 0x50 | SETUP_LFO | LFO Nr. | Period in ms | |||||
| 0x58 | MODE_SELECT | DLS vol | ITD | |||||
| 0x59 | SET_KEYGROUP | group | kill | |||||
| 0x5A | SRCMODE_SELECT | SRC type | Type 0 SRC filter | |||||
| 0x60 | ADD_VARS | Var/Ctrl | A = | Var/Ctrl | B + | Var/Ctrl | C | |
| 0x61 | SUB_VARS | Var/Ctrl | A = | Var/Ctrl | B - | Var/Ctrl | C | |
| 0x62 | MUL_VARS | Var/Ctrl | A = | Var/Ctrl | B * | Var/Ctrl | C | |
| 0x63 | DIV_VARS | Var/Ctrl | A = | Var/Ctrl | B / | Var/Ctrl | C | |
| 0x64 | ADDI_VARS | Var/Ctrl | A = | Var/Ctrl | B + | Immediate | ||
| 0x70 | IF_EQUAL | Ctrl | A == | Ctrl | B | Not | SoundMacro Step | |
| 0x71 | IF_LESS | Ctrl | A < | Ctrl | B | Not | SoundMacro Step | |
| 0x0 | END | |||||||
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
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 | Pitch; stored as a half-float, always be 0x3C00 (1.0) |
| 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; always 8 |
| 0x2 | 1 | Initial predictor/scale (matches first frame header) |
| 0x3 | 1 | Loop predictor/scale (matches loop start frame header) |
| 0x4 | 2 | Loop context sample history 1 |
| 0x6 | 2 | Loop context sample history 2 |
| 0x8 | 2 × 16 | Decode coefficients |
| 0x28 | End of entry | |
Tools
- Prime Audio Decoder by Parax will dump all sound effects contained in a given AGSC file.
