Summary of GBA standard sound driver (MusicPlayer2000)

Nintendo’s Game Boy Advance SDK comes with a sound driver library for playing music and sound effects in the game. This driver is officially called AGB MusicPlayer2000 or m4a and is often informally also called Sappy.

Inevitably, MP2k is used in a large number of games (especially in games released in Japan). Also, since it has been analyzed by many people for a long time, there is a great deal of analysis information and tools.

This article does not explain the details of MP2k. Instead, this article introduces you an overview of MP2k and various resources to learn more.

日本語で読む

MusicPlayer2000 Specifications Overview

Almost everything is explained in the following document:

Romhacking.net - Documents - GBA “Sappy” sound engine information

To summarize the main explanation MP2k has the following features.

• Software-synthesized PCM sound (DirectSound) + Gameboy compatible sound available
• PCM sound (DirectSound)
  • Playback frequency is selectable between 5734 Hz and 42048 Hz (default is 13379 Hz)
  • The number of channels is selectable between 1 and 12 (default is 8)
  • ADSR is configurable per instrument (resolution is 8-bit)
  • Resampling with linear interpolation
  • Equipped with a simple reverb (echo) effect with fixed delay
  • The processing speed and output quality of the mixer are not very good (refer to the above-mentioned document for details)
• Gameboy compatible sound
  • 2 square waves + 1 programmable waveform + 1 noise
• Data format
  • Convert MIDI / AIFF file to assembly (*.s) and build GBA ROM
  • Sequences are multitrack format like SMF Format 1 (PPQN is 24)
  • Samples are uncompressed 8-bit PCM (note that they have the opposite sign to Microsoft Wave)
  • There is no distinction between BGM and SFX. All sounds consist of sequence + bank combinations

In fact, this standard sound driver is also implemented in the System ROM (BIOS). However, those system functions are almost never used in actual commercial games, because the MP2k driver has been released as a compatible driver with bugfixes and improvements. See GBATEK for GBA BIOS functions.

Versions and variations

As far as I know, MP2k has the following standard variations:

Note: Minor version differences are considered identical here.

Also, some games use compatible drivers that improve and extend MP2k.

• Pokemon Series (uses compressed samples)
• Games developed by Camelot, Inc., such as the Golden Sun
• Metroid Fusion and Metroid Zero Mission
• etc.

Basic use of MusicPlayer2000 driver functions

The driver basically works with 4 functions.

First, the m4aSoundInit function must be called in the initialization routine to initialize the sound.

void m4aSoundInit(void);

The VBlank interrupt handler must call the m4aSoundVSync function immediately after the interrupt.

void m4aSoundVSync(void);

The m4aSoundMain function must be called by main routine in every frame (approximately every 1/60 of a second).

void m4aSoundMain(void);

Lastly, call the m4aSongNumStart function with a song number to start playing.

void m4aSongNumStart(u16 n);

The addresses of these functions can usually be detected with saptapper, an automated ripping tool for MP2k.

loveemu/saptapper: Automated GSF ripper

Internally, when a song starts playing through these functions, the sound driver stores information about the playback, into an instance of music player. Usually, a game has more than one music player instances on memory. One is used for music and the other ones are used for SFXs and such, typically. The instance of the music player to play a song is determined by its song header.

ROM / RAM data map

See m4a_internal.h and sappy.txt for more informations.

List of commands of MusicPlayer2000 sequence

The table below shows a list of MP2k sequence commands.

In principle, most of 1-byte arguments are values in the range 0 to 127, and values greater than 0x80 are not used.

Note

The Wxx command (0x80 to 0xB0) and the Nxx command (0xD0 to 0xFF) represent lengths from 1 to 96. The lookup table below shows the list of lengths.

const u8 noteLengthTable[48] = {
   1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16,
  17, 18, 19, 20, 21, 22, 23, 24, 28, 30, 32, 36, 40, 42, 44, 48,
  52, 54, 56, 60, 64, 66, 68, 72, 76, 78, 80, 84, 88, 90, 92, 96
};

Memory access (MEMACC)

MEMACC (0xB9) is a command to perform a conditional jump dynamically according to the state of the game. The command uses a shared memory area (up to 256 bytes of RAM area m4a_memacc_area). This command is rarely used.

This command basically takes three arguments, except that the conditional branch instruction specifies the branch destination address as the fourth argument.

@ for arithmetic operations
MEMACC, mem_set, adr, dat

@ for branching instructions
MEMACC, mem_set, adr, dat, dest

Specify the type of operation with mem_set, and specify the arguments of the operation with adr and dat (0-255).

Specify one of the following values for mem_set:

List of known functions

void m4aSoundVSync(void);
void m4aSoundInit(void);
void m4aSoundMode(u32 mode);
void m4aSoundMain(void);
void m4aSongNumStart(u16 n);
void m4aMPlayStart(MusicPlayerArea *ma, SongHeader *so);
void m4aSongNumStartOrChange(u16 n);
void m4aSongNumStartOrContinue(u16 n);
void m4aSongNumStop(u16 n);
void m4aMPlayStop(MusicPlayerArea *ma);
void m4aSongNumContinue(u16 n);
void m4aMPlayAllStop(void);
void m4aMPlayContinue(MusicPlayerArea *ma);
void m4aMPlayAllContinue(void);
void m4aMPlayFadeOut(MusicPlayerArea *ma, u16 sp);
void m4aMPlayImmInit(MusicPlayerArea *ma);
void m4aSoundVSyncOff(void);
void m4aSoundVSyncOn(void);
void m4aMPlayTempoControl(MusicPlayerArea *ma, u16 te);
void m4aMPlayVolumeControl(MusicPlayerArea *ma, u16 tb, u16 vo);
void m4aMPlayPitchControl(MusicPlayerArea *ma, u16 tb, s16 pi);
void m4aMPlayPanpotControl(MusicPlayerArea *ma, u16 tb, s8 pa);
void m4aMPlayModDepthSet(MusicPlayerArea *ma, u16 tb, u8 md);
void m4aMPlayLFOSpeedSet(MusicPlayerArea *ma, u16 tb, u8 ls);

Documents

Romhacking.net - Documents - GBA “Sappy” sound engine information (by Bregalad, ipatix)

Tools and Source Codes

• ipatix/agbplay: Music player for the most common GBA sound format
  • Music player for PC that can play MP2k format (LGPLv3)
  • The source code will be helpful in understanding the driver (see StreamGenerator.cpp for sequence parser)
  • ipatix is one of the prominent MP2k analysts, and his github also has other MP2k tools such as m4a2s, midi2agb and wav2agb. They are useful for ROM hacking etc.
• Kermalis/VGMusicStudio: A program that lets you listen to the music from popular video game formats.
  • New music player and visualizer for GBA music format, written in C# (LGPLv3)
• ipatix/gba-hq-mixer: HQ mixer for GBA games which use the m4a/mp2k sound driver
  • Provides additional relocatable code for higher quality mixing
• loveemu/saptapper: Automated GSF ripper (A reimplementation of Caitsith2’s saptapper)
  • Automated GSF ripping tool for MP2k
  • It can also be used to detect fundamental m4a functions
  • Forked from: GSF Ripping Tools - caitsith2.net
• jpmac26/gba-mus-ripper: A fork of Bregalad’s “GBA Mus Riper” program
  • Conversion tool that can export MP2k format to MIDI/SF2 format
  • sappy_detector.exe can be used to detect MP2k driver and view some basic information
  • Forked from: Utilities - GBA Mus Riper - Romhacking.net
• pret/pokeruby: Disassembly of Pokémon Ruby/Sapphire
  • Actual example of music data
  • m4a_internal.h is a good representation of the internal data structure of MP2k
  • As mentioned above, the Pokémon sound driver is a little more customized, but the differences are slight
• IDA FLIRT Signatures for GBA (experimental)