AGSC (File Format)

From Retro Modding Wiki
Revision as of 07:33, 5 March 2015 by >MrSinistar (→‎Tables)
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 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.

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 contains tables for SoundMacros, ADSR, keymaps, and layers, if applicable. It starts with a 16-byte header before the different data tables begin.

Offset Size Description
0x0 4 SoundMacros Offset (always 0x10)
0x4 4 Tables Offset
0x8 4 Keymaps Offset
0xC 4 Layers Offset
0x10 End of entry

SoundMacros

The first Pool table denotes MusyX's SoundMacros, small scripts that apply various effects on the sounds in the game. Each macro is composed of a header followed by a number of commands; each command specifies its type through a single-byte command ID, then specifies the parameters of that particular command, which vary.

The header of each SoundMacro is eight bytes, and is structured as follows:

Offset Size Description
0x0 4 SoundMacro size (note: includes the size value itself)
0x4 2 SoundMacro ID
0x6 2 Unknown; usually 0
0x8 Commands begin

On the commands, 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 8 bytes, and 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 will continue with commands until it 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.

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

After the last soundmacro, the table terminated by a value of 0xFFFF.

Tables

Tables have two functions: for defining curves for volume scaling, or to be used as ADSR envelopes.

Offset Size Description
0x0 4 Table size; (usually 0x10)
0x4 2 Table ID
0x6 2 Unknown; (always 0)
0x8 1 Attack time (0-255 milliseconds)
0x9 1 Attack time (256-65280 milliseconds); 1 = 256, and every next byte is multiples of 2 (256,512,768,...)
0xA 1 Decay time (0-255 milliseconds)
0xB 1 Decay time (256-65280 milliseconds); 1 = 256, and every next byte is multiples of 2 (256,512,768,...)
0xC 1 Sustain (percentage)
0xD 1 Sustain (percentage); 6.25^2
0xE 1 Release time (0-255 milliseconds)
0xF 1 Release time (256-65280 milliseconds); 1 = 256, and every next byte is multiples of 2 (256,512,768,...) 0x10 End of entry


The entire Pool chunk is terminated by a value of 0xFFFF.

Project

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

Offset Size Description
0x0 4 Proj chunk size
0x2 2 Unknown
0x4 2 Unknown; Always 0x1
0x8 4 SoundMacro ID table offset
0xC 4 Sample ID table offset
0x10 4 Tables table offset
0x14 4 Keymaps table offset
0x18 4 Layers table offset
0x1C 4 SoundMacro Settings Table offset
0x20 4 Unknown Table D offset (usually 0, indicating table is not present)
0x24 4 Unknown Table E offset (usually 0, indicating table is not present)
0x20 End of proj header

After the header are a number of data tables.

SoundMacro ID Table

This is a table of shorts; there's no count value, so it's terminated with a value of 0xFFFF. It's a list of SoundMacro IDs present in the file. Occasionally there's gaps in the list; these gaps are signified by the top bit, 0x8000, being set on the size value preceding the gap.

Sample ID Table

This functions the same way as the SoundMacro ID table, but it contains a list sample IDs instead.

SoundMacro Settings

This table begins with a 16-bit count value, then 16 bits of padding. Each entry in the table is 10 bytes.

Offset Size Description
0x0 2 ID; referenced in EVNT
0x2 2 SoundMacro ID
0x4 1 Max number of voices
0x5 1 Priority; voices are limited, so priority is used to play more important sounds over others
0x6 1 Definite Velocity; volume (usually 7F)
0x7 1 Panning
0x8 2 Definite Key; The default pitch (usually 0x3C00... the second byte may possibly be the MIDI channel)

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
0x2 2 Padding; always 0
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 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

Retrieved from "https://wiki.axiodl.com/index.php?title=AGSC_(File_Format)&oldid=1206"