=======================================
GBAMusRiper by Bregalad
Release 1.0 July 2012
=======================================

GBAMusRiper is a collection of tools, written in java, to rip music from Game Boy Advance (GBA) games using the "Sappy" sound engine, a really common engine among commercial GBA games.
Music ripers from GBA games already exists, but this one is more complete and versatile, and less buggy than the existing ones (as for the date of writing this).
It's the first one that actually converts instruments to SoundFont format, including GameBoy instruments.

GBAMusRiper is free and open source software. Anyone is free to redistribute/improve the program but just DON'T CLAIM IT IS YOUR OWN WORK THANK YOU.

Applications :
- Listen to GBA music with higher quality sound hardware than a GBA or an emulated GBA which only have 8-bit sound
- Make other music sound like a GBA game.
- Simply get music sheets of GBA games.

The tools comes in several parts.

== 1) GBAMusRiper ==

This is the main program which does everything automatically. Normally you'd only want to use this one, but the other parts can also be used individually too.
It detects the presence of the sappy sound engine in a given rom, and converts all detected songs to .mid files, and rip all detected sound banks to a .sf2 file.

!!! HOW TO USE THIS PROGRAM !!!

To use this program you'll need Java Runtime Environment (JRE). To know if you already have JRE installed, just enter in a command line and type "java" then enter. Normally you should get a long message explaining how to use Java from the command line. If a short error message appears then JRE isn't installed on your machine and you should download it from the internet.

Now to use GBAMusRiper. Enter a command line and go inside the \bin directory (type "cd bin"), but do NOT go into the \gbaMus directory.
And type :
java gbaMus.GBAMusRiper name_of_your_rom.gba

And everything should happen automatically. For mode details :

Usage :
SappyRipper game.gba [flags]
-gm : Give General MIDI names to presets. Note that this will only change the names and will NOT magically turn the soundfont into a General MIDI compliant soundfont.
-xg : Output MIDI will be compliant to XG standard (instead of default GS standard)
-rc : Rearrange channels in output MIDIs so channel 10 is avoided. Needed by soundcards where it's impossible to disable "drums" on channel 10 even with GS or XG commands
-sb : Separate banks. Every sound bank is riper to a different .sf2 file and placed into different sub-folders (instead of doing it in a single .sf2 file and a single folder
- raw : Output MIDIs exactly as they're encoded in ROM, without linearize volume and velocities and without simulating vibratoes.


== 2) SappyDetector ==

This part of the program is here to detect the sappy sound engine. If an engine is found, it prints info about how the game uses the engine on the screen. This is the easiest way to know if a givien GBA games use the sappy sound engine or not.

Usage : SappyDetector game.gba


== 3) SongRiper ==

Rips sequence data from a GBA game using sappy sound engine to MIDI (.mid) format.

Usage :
MidiRipper infile.gba outfile.mid song_adress [-b1 -gm -gs -xg]

-b : Bank : forces all patches to be in the specified bank (0-127)
In general MIDI, midi channel 10 is reserved for drums
Unfortunatly, we do not want to use any "drums" in the output file
I have 3 modes to fix this problem
-rc : Rearrange Channels. This will avoid using the channel 10, and use it at last ressort only if all 16 channels should be used
-gs : This will send a GS system exculsive message to tell the player channel 10 is not drums
-xg : This will send a XG system exclusive message, and force banks number which will disable "drums"
-lv : Linearise volume and velocities. This should be used to have the output "sound" like the original song,but shouldn't be used to get an exact dump of sequence data.
-sv : Simulate vibrato. This will insert controllers in real time to simulate a vibrato, instead of justwhen commands are given. Like -lv, this should be used to have the output "sound" like the original song,but shouldn't be used to get an exact dump of sequence data.
It is possible, but not recommanded, to use more than one of these flags at a time.

== 4) SoundFontRiper ==

Dumps a sound bank (or a list of sound banks) from a GBA game which is using the sappy sound engine to SoundFont 2.0 (.sf2) format
Usage :
SoundFontRipper in.gba out.sf2 [-v[Out.txt]] [-s22050] address1 [address2] ....

Instruments at address1 will be dumped to Bank0, instruments at address2 to Bank1, etc.....
addresses should be in hex format. Example : "0x123abc"
-v : verbose : Display info about the sound font in text format. If -v is followed by a file name,info is output to the specified file instead.-s : Sampling rate for samples. Default : 22050 Hz
-gm : Give General MIDI names to presets. Note that this will only change the names and will NOT magically turn the soundfont into a General MIDI compliant soundfont.
-mv : Main volume for sample instruments. Range : 1-15. Game Boy channels are unnaffected.

IMPORTANT NOTE : You need to leave the included file "psg_data.bin" INTACT for SoundFontRiper to work properly. If you remove or affect the file in any way, the GameBoy instruments won't properly be dumper.


== 5) GbaMusMerger ==
This is a little extra included with the package. It allows you to play music from any game using the sappy engine with the music player from any Final Fantasy Advance (U) or (E) game. This program is a bit messy and wasn't supposed to be distributed to the public, but I changed my mind. Because of this please don't complain that this program is slow and buggy, and that the source code is dirty, I already know. I still tried to make it usable though.

You need to do it in 2 setps. First you should concatenate the Final Fantasy Advance ROM with the game with music you'd like to play.
This is done like this in windows : Enter in a command line and type, for example :
copy /b ff4_advance.gba + golden_sun.gba golden_sun_music_player.gba
copy ff4_advance.sav golden_sun_music_player.sav

Then type :
java gbaMus.GBAMusMerger golden_sun_music_player.gba 1

If everything works fine, you'll get a FF4 advance ROM that plays music from Fire Emblem when you use the music player. The number 1 refers to a ff4(e) rom, but you'll need to use another number if you use another ROM.
You need a save file where you beat the game to acess the music player. However such save files can be easily downloaded from the net, therefore you don't actually need to beat the game to use the player ;)

Usage :
GBAMusMerger pathname ROM-number [offset] [table-address]

Where "table-adress" is the hex adress of the music table in the new ROM
ROM number indicate in which Final Fantasy Advance ROM the music is inserted:
0 = Final Fantasy 1&2 (E)
1 = Final Fantasy IV Advance (E)
2 = Final Fantasy V Advance (E)
3 = Final Fantasy VI Advance (E)
4 = Final Fantasy 1&2 (U)
5 = Final Fantasy IV Advance (U)
6 = Final Fantasy V Advance (U)
7 = Final Fantasy VI Advance (U)


To play back converted data, I recommand BASSMIDI driver, which is free and allows playback of MIDI files using a sound font file. Use Google to get it.
To play back MIDIs I recommand Winamp. Unfortunately it seems song looping is error prone in Winamp (Nullsoft MIDI reader v3.5). I hope they'll fix it some day.

For linux users, you should look for a program called TiMidity++. I have no idea how it works so I'll let you experiment (after all if you're a linux user you should know more than myself about computer science^^).

FAQ :
Q : How do I know if game XXX uses sappy engine ?
A : Just try to run GBAMusRiper on it, if it doesn't work then it's very likely the game doesn't use the sappy engine. A good 80-90% of commercial GBA games uses this engine.

Q : Will it sound EXACTLY like on the GBA ?
A : No, but in all honesty very damn close. The sampled instruments will actually sound BETTER, because the GBA sound hardware has 8-bit sound output, this means the Digital to Analog in the GBA can only output 256 voltage levels, which means the output is being quantified and is very noisy.
On the other side the good old GameBoy instruments will sound different because the're emulated using samples. These instruments are quantified in volume and pitch, and there is no way to reproduce this imperfection in the .SF2 standard. I used samples actually recorded from my DS in GBA mode.

Q : Can I re-use the soundfont to play other MIDIs / Can I use soundfont from Game A to play music from Game B ?
A : Yes but unfortunately there is a 99% of chances it will sound like total crap, because very few games have a Gerneral MIDI compliant soundfont. If you're looking for games with partially Genral Midi compliant soundfonts, I know of Golden Sun, my Final Fantasy V and VI hacks, and Castlevania : Aria of Sorrow. (All of these have a lot of missing instruments too so in all cases you'd need some MIDI editing to get the sound you'd expect).
If you accept however to do some MIDI editing and/or some SoundFont editing manutally, then the answer to both of these questions is of course yes, and GBAMusRiper will probably be a great help.

Q : Can I also rip voices/sound effects ?
A : Yes absolutely. In fact the engine does not differenciate music, sound effects and voices in any way so you'll rip them all automatically.

Q : The first song/first few songs works fine, but the following songs doesnt work.
A : This is probably a problem with using various sound font banks. You should be sure the driver and MIDI player you use supports banks. It it doesn't work in normal (GS) mode try to use the -xg argument for XG mode maybe you'll get better results.

Q : The songs works usually fine but they sometimes sound wrong
A : Maybe your driver doesn't support the GS message to disable "drums" on midi channel 10. The way I rip the sound font requires that no channel is ever using MDI "drums" (even if there is drums in the song - they'll be mapped to a normal instrument). You should try the -rc (rearrange channels) and/or -xg options.

Q : The songs in Golden Sun (and Golden Sun : The Lost Age) works fine but there is missing instruments.
A : Sadly this is normal and I can do nothing about it. In fact the developpers were so awesome they improved the sappy engine and implemented their own kind of instruments using mathematical formulas instead of samples, for a cool "synth" sound, especially heard in the battle themes. Unfortunately I have no clue how this instrument works and how to simulate it using Sound Fonts.

Q : Why does it takes so long to rip the songs/soundfont ?
A : It really depends on the game. Some games use a different sound bank for every single song, so those games takes a very long time to rip. In all cases it's normal the conversion can't be done instantly.

Q : Can you adapt this riper to work with Game X which doesn't use the sapy sound engine ?
Q : Can you make this riper work with GameBoy Color / Nintendo DS / Wathever console games ?
A : No, because other sound engines works completely differently.

Q : The soundfonts causes major trouble / crashes the program when I'm trying to use it
A : Some games uses too many different soundbanks for different songs and this causes problems in extreme cases. You should use the -sb command to separate sound banks into different folders, which will result in many sound font files instead of a single sound font with many sound banks.

=== Plans for future updates ===
- Any suggetions are welcome
- Could someone make a nice GUI for this program ? It would be amazing ! And presonally I have zero knownledge in GUI programing.

=== Contact ===
Contact me at jmasur at bluewin dot ch if you want to give ideas about how I can improve GBAMusRiper, or even better, if you improved the program by yourself.

=== History ===
v1.0 july 2012
First public release

v1.1 august 2012
Added -raw and -sb options.