[Pokeemerald] How To Add, Edit, And Understand Music in Pokeemerald

With this method, you'll be adding loop points to your instrument sample. You'll need to download Awave Studio. The demo version is free, and that's all you need to add loop points. It has a trial period of 30 days, but you can just uninstall it and reinstall it to reset the timer. Once you've downloaded the software, you can open it up, and then open your instrument sample by clicking on File/Open Files. Once you select your file, it should appear in a table to the right. Double click on it. Click on the "Loop" tab. Click "Find Loop", and then "Finish". You can then listen to the loop that Awave Studio has created for you! If there seems to be a clicking sound or something that makes the loop sound bad, you can try clicking "X-Fade" and then "Finish", which will help it somewhat. If you already had particular loop points that you wanted to use, you can enter those points into the "Start:" and "End:" boxes. Once you're satisfied with your loop, click "Ok". Right-click on your file in the table, then click "Save selected....as". Enter a filename for your instrument, and set the save type to "AIF - Audio interchange (*.aif)". Set the Data Format to "PCM 8-bit", and the Channel Format to "Mono". With that, you officially have a looped instrument sample!

You'll need to take your sample and manually loop it. What I mean by this is you need to edit your sample to be several seconds long by copying parts of it over and over, while making sure it doesn't sound like it's looping. I'd suggest making the sample last for at least 5 seconds. I personally make mine 10 just to be safe, but I doubt I'm ever going to be making a song that plays a single 10 second long note. This video does a decent job of explaining how to loop audio. You will need some form of audio editing software. Audacity is a free software that can get the job done.
Once you have your sample looped, save it off as a .aiff file. Make sure it uses mono channels, not stereo. If you end up getting an error when you try to compile your ROM with this sample, then just take your looped sample to Audacity, choose to "Export Audio", and make the save type "Other uncompressed files". Then, in Format Options, have the header be "AIFF (Apple/SGI)", and the encoding be "Signed 8-bit PCM". This method can be done with simpler software than the other method, but takes up more space on your ROM. This allows the GBA to play a note from your instrument up to however long you made your sample. If you had made it only 1 second long, every note from this instrument would need to be no longer than 1 second. If you tried to play a longer note, it would just get cut off after 1 second.

The first line will have this: This means that all of the commands within sound/MPlayDef.s can be used in this file. sound/MPlayDef.s is a good file to look at in case you forget what a certain command does, so keep that in mind.

Next, you'll see something like this: Every instance of "mus_rg_ajito" will be whatever the name of the .s file is. This file is named "mus_rg_ajito", so you'll be seeing a lot of that throughout this file.

The first line, "mus_rg_ajito_grp", tells the game which voicegroup to use for the song's voices. The voicegroup used in this song is my custom voicegroup, "voicegroupmidi". (Sometime after initially writing this, I've changed the name of my voicegroup to "voicegroup200", as it is better to have numeric names for voicegroups)

The second line, "mus_rg_ajito_pri", has something to do with the priority of the song. I'm not exactly sure what its purpose is.

The third line, "mus_rg_ajito_rev", sets the amount of reverb that is heard in the song. Shocking. You'll always have to set this value by typing "reverb_set+(the value you want the reverb to be)", or make it 0. I've experimented a bit with this value, and I've noticed something interesting: If you have a song playing that, for example, has a rev value of "reverb_set+50", it will have a slight reverb to it. However, if a sound-effect that has a rev value of 0 plays on top of that song, the song loses it's reverb quality, as if the rev value of the sound effect took precedence over the rev value of the song. I initially thought that maybe this has to do with that priority value that I mentioned earlier. Sound effects tend to have high priority values, so maybe the higher prioritized sounds set the reverb for whatever other sounds are being made. However, when I increased the priority of my song to be higher than the sound effects priority, the song's reverb would still disappear. This means there's some strange connection between reverb and sound effects that I don't understand yet.

The fourth line, "mus_rg_ajito_mvl", is the master volume. Changing this value will affect the volume of the entire song. It cannot go above 127, as the game uses unsigned 8-bit ints to hold these values, and 127 is the highest value that type of variable can hold.

The fifth line, "mus_rg_ajito_key", represents the key that the song is in. If you change this value, the entire song will be pitch shifted. It's handy for if you think the entire song is a little too low pitched.

The sixth line, "mus_rg_ajito_tbs", is used to affect the tempo of the song. I have only ever seen it as 1. If you set it to 2, the song would be twice as fast. 3, three times, and so on.

The seventh line, "mus_rg_ajito_exg", is a mystery to me. Sometimes it's 0, but most of the time it's 1. If anyone knows what this does, feel free to speak up.

The eighth line, "mus_rg_ajito_cmp", is yet another mystery. It always seems to be 1.

The ".section .rodata" line tells the game where to store the information of this song. Don't touch it.

The ".global" line holds the name of the file. I'm not sure why, but it does. And it does it well.

".align 2" is once again there for formatting purposes.

Now we get into the real nitty-gritty of the .s file. We'll look at how tracks are designed, as well as the many commands that are used within these tracks.

Each track is seperated with a line, as well as a denotation of which track it is. It'll look something like this: This line is only here for us humans that look at these files. This line is completely ignored by the GBA due to it being commented out. Any line that has a "@" at the far left is commented out.

Then we see an important label: This tells the GBA that this is the first track of this song, and everything below it is part of this track. At the top of each track, you'll see a line similar to this, with the number relating to the track in question.

As we go through this track, you'll see dashed lines with numbers to the left of them like this: Again, due to them being commented out, these are meant for us humans. Each of these sections can be considered as one measure of the song. Of course, since this is used for a program, the first measure is 000 rather than 001, since us programers love starting with 0. We then see several commands, which I will explain. You can see all of these commands in sound/MPlayDef.s if you so desire.

Just a side-note that I feel like I need to point out: every single command in a .s file starts with ".byte". Always. Without exception.
The first command we see is: KEYSH is the key-shift command. It will shift the key of the track it's in. Whatever value you add or subtract the key with will shift the track's pitch by that many half-steps. As you may notice, it uses the key of the entire song, "mus_rg_ajito_key", and then adds a value to it. In this case, the command does nothing, since it shifts the key by 0. Sometimes when a .mid file is turned into a .s file, some commands are made that serve no purpose. Just a minor glitch with mid2agb, I guess. Or maybe mid2agb is designed to put one of these commands at the top of each track, just in case the user wants to change the key? Who knows. The next command is this: TEMPO is the tempo-changing command. This sets the tempo for the entire song, not just the one track that it's in. This is one of the few (if not only) commands that affects every track. This command takes a number, which is the BPM that you want the song to be, multiplies it by the song's tbs value, and then divides it by 2. Why does it need to be divided by 2, you ask? I don't know, but it does. This is always the format for TEMPO commands.
Next line: VOICE is the voice-changing command. This sets which voice from the voicegroup of the song is being used in this track. The number is the location of the voice within the voicegroup. This particular command sets Track 1 to use the 39th instrument in the voicegroup. Not the 38th. Remember, this is a program, so the first voice in the voicegroup would be 0, the second voice would be 1, and so on. If a track is never given a VOICE command, it cannot make any sound whatsoever. This can actually be a handy trick if you want to mute a track: just comment out all of the VOICE commands in the track, and the track will be completely muted.
Next line: VOL is the volume-changing command. The volume can go up to 127 and no higher, and the number must be multiplied by the song's mvl value and then divided by mxv, which is a constant for the loudest possible volume on the GBA. Kind of a weird format, but that's how it's done.
Next line: PAN is the....pan...command. Pan is where the sound is being placed in stereo space. Whether it's coming more from the right speaker or the left speaker. You always need to add/subtract from c_v. Adding moves the sound to the right, subtracting to the left.
Next line: MOD is the...mod...command. There are three types of mods: vibrate (mod_vib), tremolo (mod_tre), and auto-panpot (mod_pan). Before you would use MOD, you would use the command MODT and set the type to be whichever one of these that you want, using the names in the parenthesis. However, when I tested using anything except mod_vib, I didn't notice any change to the music. Perhaps I was using too low a value for MOD (I tried entering 15, which is higher than I've ever seen it used), but it is something to note. MODT is set to mod_vib by default.
Next line: Ah, here is our first actual note! Whenever a note is played, it follows this format: note-length, pitch, velocity. This note will last for 17...time units, and it will play E1 at a velocity of 112 (max is 127). Time units is just the term I have for the numbers used with N##. If a song is in 4/4, a single measure has 96 time units, which would mean one beat lasts for 24 time units. If the song is in 3/4, a single measure will instead have 72 time units, still leaving a single beat with 24 time units. En1 means E-natural-1. Each number represents an octave. The higher the number, the higher pitched the octave. You can look through sound/MPlayDef.s to see all of the possible notes you can use. And for those that don't know, velocity is another term for volume that is often used in music, especially with midis. That velocity value will affect specifically this one note. The volume set by a VOL command is still in effect here, but this velocity element gives us a bit more precision when it comes to volume control.
Next line: Pretty short, but pretty important. This is a wait command. This forces the track to wait 24 time units before going to the next command. An important thing to point out here: even though the prior command had a note that lasted for 17 time units, that doesn't mean 17 time units pass before this wait command starts. The note starts to play, and then we immediately start the wait command. Every command will immediately play one after the other if no wait commands are between them. As such, each measure should have a number of wait commands that add up to 96 (or 72 if the song is in 3/4), so as to have the measure last it's full length.
Next line: Mmmm, now here's where things get interesting. This looks like a note command, and yet we don't see the duration of the note! Strange, isn't it? This is actually an opitimization that the GBA's programming uses. Since we aren't given a note duration here, the GBA will just use the prior note duration, which would be N17. If we hadn't given a velocity value, it would have also used the prior one, which was 112. The GBA can look back like this to fill empty spots for every type of command. Say we set the volume to 110 like this: But then we want to immediately change the volume to 100. We can just type this: The GBA will remember that the prior command was a VOL command, so it knows what to do with this data. An important thing to point out: if we had typed a different command between these two volume changes, like a note command, we would have still needed to type VOL into that second command. If we had typed this: The GBA would get real confused. It would try to play a note using "100*mus_rg_ajito_mvl/mxv" since the prior command was a note command, but it can't do anything with that data. The only command that won't cause this confusion is a wait command. The GBA will look further back to the prior non-wait command to get it's missing data. Back to note commands, if we want to repeat a note, we could write something like this: Or this: These two would both play the exact same thing. Since all of the data was given in an earlier command, we just need to give a single element of the prior note to let the GBA know that we want to play another note. I'm not sure if you can do this by just giving the velocity, though. We can also get a bit more creative in writing our notes by typing something like this: This bit of code would first play an E-natural-1 for 17 time units at 112 velocity. Once 20 time units passed, it would then play another E-natural-1 at 112 velocity, but this time for 20 time units. After waiting another 20 time units, another note would be played for 20 time units at 112 velocity, but this time it's a C-natural-2. As you can see, we can leave out certain commands and change others to simplify the data for each line without losing any information. mid2agb does this automatically, so it's important to be aware of how these lines can be written.

Not a whole lot of other commands are used until later on in the song that I'm using as an example, so I'll just list off the remaining commands from sound/MPlayDef.s

FINE defines the end of a track. Example:
BEND will bend the pitch of a track. You would use c_v, similarly to the PAN command. Example:
BENDR will affect how much the BEND value bends the pitch. From what I can tell, it looks like it is set to 2 by default in src/m4a.c within the m4aMPlayImmInit function. This BENDR value is multiplied by the BEND value to determine the amount of bend applied to the note. Example:
TIE can replace a note duration. This will make a note last until an EOT command is given. Example:
EOT will end a TIE note. Example:
XCMD basically just announces that an extended command is about to be used. These extended commands take an additional argument that states what type of extended command is being used, which you will see in the examples for the next couple of commands. These commands are based on C code that can be found in src/m4a.c. It is possible to add your own commands via these extended commands, which I have demonstrated in this tutorial of mine that lets you make dynamic music.

xIECV sets the volume for an echo effect. It is at 0 by default, meaning there's no echo. Example:
xIECL sets the length of the echo, or how long the echo lasts. It is at 0 by default, also meaning there's no echo. Example: There are several other extended commands that do not have a declared constant in sound/MPlayDef.s, but can still be used in your songs. For example: These commands set the attack envelope of the track to be 250, the decay envelope to 150, the sustain envelope to 50, and the release envelope to 220, respectively. These commands do not work on voices that use voice_keysplit or voice_keysplit_all, since that voice technically contains multiple sets of voice envelopes. There are a few other extended commands that don't have constants, but I don't fully understand how they work yet, so I won't bother giving you an uneducated explanation. You can see a full table of all of the extended commands at the bottom of src/m4a_tables.c, and you can see what each command does in src/m4a.c. To use any of these commands, you just need to write: If you want, you can also go into sound/MPlayDef.s and add your own constants for these commands. For example, I've added "xDECAY" and "xSUSTAIN" as constants in that file, making them equivalent to 5 and 6, respectively.

There are some commands that need to be seen in action to be understood. Looking back at the song I was using as an example before, you'll see at Track 1 measure 14 (or 014) that there's this line right at the top: This is a label. Labels are used for a few commands:
PEND can be used to make a measure with a label become a pattern. You place this command where you want your pattern to end, hence the name PEND. This technically doesn't only apply to a single measure. You could have an entire track be a measure, as long as there are no labels between the label of the first measure and the PEND command. This is incredibly uncommon and usually risky, so it's generally best to just have a pattern last for one measure. Looking at the bottom of measure 14, you will see this command: PATT will play a pattern, and then proceed through the song. This can be seen in Track 1 measure 15: ".word" is used with some commands almost like an argument for a method. With PATT, .word holds the pattern label that indicates which pattern shall be played.
GOTO will cause the track to jump to a label. It'll look something like this: This is different from PATT in two ways:

1. GOTO doesn't need a pattern to be marked with PEND, whereas PATT does.

2. GOTO causes the track to play from the given label, whereas PATT will play the pattern, and then move on to the next measure. For example, this: Will cause measure 15 to be identical to measure 14, and then the track will move on to measure 16. This, on the other-hand: Would cause the track to move back to measure 14, play measure 14, and then move forward to measure 15, where we would again go back to measure 14, and find ourselves in an infinite loop. GOTO is generally used only to loop the music.

There are other commands within sound/MPlayDef.s, but those that I haven't already explained rarely (if ever) show up, so I don't know much about them. I'm loosely aware of what they may do, like LFOS and LFODL having something to do with how the effects of MOD sound, but it's just surface knowledge.

At the very end of the .s file, you'll see something like this: This needs to be at the end of every .s file, as it kind of wraps up all of the data. You will almost never need to mess with this stuff, but it's important to know it's there.
The first .byte is important, because it denotes how many tracks are in this song.
I don't know what the "NumBlks" .byte means. It always seems to be 0.
The next two .bytes refer to priority and reverb. These just take the values we put at the top of the file and bring them down here, since this is where a lot of critical data is read from.
".word mus_rg_ajito_grp" is basically reminding the file of which voicegroup is being used. This was defined at the top of the file.
The last several .word's represent each track's name. mid2agb names the tracks based off of the song's name, and then places them in numerical order. If some or all of these aren't here, or if there are unnecessary track names added, errors occur. The only reason you should care about this is if you decide to delete a track, in which case you need to lower the number of tracks as well as delete one of the tracks from the list.
And, of course, ".end" marks the end of the file.

Creating a note should be pretty straight-forward if you know how to use a midi editor: place the note, set the duration and volume/velocity, and you're good to go. What some less-experienced midi editing fellows might not know (including myself when I first got into it) is how to get certain commands to show up in the .s file. A lot of this will occur in some sort of area like this:
This is at the bottom of the piano-roll (the visual display of all of the notes), and holds a great many details, including tempo, what instrument each channel uses, and many more little tricks. There are some more obvious ones like "Pitch Bend" relating to BEND and "Tempo Change" relating to TEMPO, and some less obvious ones, like "Program Change" relating to VOICE. There are also multiple commands that fall under "Control Change", including but not limited to MOD, VOL, and PAN, which you pick out from this dropdown:
If you choose a Control Change event that isn't accounted for in the .mid → .s conversion program, it will just generate a wait command in the .s file. To see all of the different Control Change event types that are accounted for in mid2agb, go to tools/mid2agb/agb.cpp and look for a function called PrintControllerOp. It looks like this: The value for each case correlates to the index of the command itself. For example, the Control Change event at index 7 in MidiEditor is the volume change command. As we can see in this switch statement, 0x07 relates to the VOL command. A pretty sensible association. Some of these commands do not have sensible associations with their respective Control Change types. Some may be tied to completely undefined Control Change types. You just have to look at this function to know what relates to what. A full explanation of this function comes later in the Using Voice Envelope XCMD Commands (A Look at the .mid → .s process) section.

- The absolute center value for things like PAN and BEND is 64 in pokeemerald, which is represented as c_v, or "center value". In MidiEditor, this center value is 8192. Assuming your midi editor uses similar values, you can just divide the huge number by 128 and round down to know what value you'll get in the .s file. For bending a note, if you raise or lower the pitch by 4096 (or 32 in the .s file), that is a half-step change in pitch. The most you can bend up or down is 1 whole-step, although you can only go up by 8064 (or 63 in pokeemerald) to a max of 16256 (or 127 in pokeemerald) due to the max value of most commands in the .s file being 127. This means you'll be ever-so flat when trying to bend up a whole-step. You can still bend down a full whole step, going down to 0 in both the midi editor and pokeemerald. This is all assuming BENDR is still at its default value of 2. If you increase that value to 3, for example, bending the pitch by around 2730 will be a half-step, and around 5461 will be a whole step. Just so you know.

- The lowest note displayed in MidiEditor is Cn-1, but that note correlates to Cn-2, or CnM2 in pokeemerald. This means all notes in MidiEditor are one octave above their respective note in pokeemerald. I don't know if this discrepancy also exists in other midi editors. Just so you know.

- How the song sounds in the midi editor is often substantially different from how it sounds in-game, even if you use the pokeemerald samples in your midi editor. If you can manage it, being able to get the pokeemerald samples into your midi editor can help give you a better idea of what the song will sound like in-game. Again, even if you do this, it will not sound exactly the same, due to how the GBA handles sound. You will still need to make your changes, then put it into the game, give it a listen, then make more changes until it's done. Just so you know.

In most midi editors, there are these two things called tracks and channels. Tracks, generally speaking, relate to a particular element of the song, be it the melody, an instrument, or whatever. It's more conceptual than a channel. A channel relates to a particular instrument/voice in the song. The instrument/voice for a given channel can change in the middle of a song via a Program Change, which is a VOICE command in the .s file. Note that a Program Change is not changing the voice of the track in the midi, but the voice of the channel, whereas the generated VOICE command IS changing the voice of the track in the .s file, since there are no channels in the .s file.

Despite how it looks in MidiEditor, the tracks and channels are not actually color-coordinated. You can have one channel appear in multiple tracks, and one track can have multiple channels in it. It is generally advised to minimize the number of channels per track, as it can be confusing to read sometimes. This can become even more apparent when looking at the converted .s file of a midi that has tracks with multiple channels. Sometimes each channel within a single track gets turned into a seperate track within the .s file. If you aren't careful, you could potentially run out of tracks due to frivolous channel-track combinations. If you really need to have a single track use multiple instrument throughout the course of the song (a situation I have run into a few times) and you can't add another track to handle a handful of notes, it's better to just do a Program Change and change the voice of the channel that is being used by the given track to whatever voice you need, rather than incorporating another channel with your desired voice into the track.

TL;DR, try to only have one channel per track.

Having a single, master voicegroup is really handy, since it allows you to avoid needing to make a new voicegroup for each song. It's even handier if you take the time to line up each instrument in your voicegroup with each instrument in your midi editors' voice collection. Looking at MidiEditors selection of sounds, we see that Acoustic Grand Piano is at the top, followed by Bright Acoustic Piano and Electric Grand Piano:
Looking at my master voicegroup, you will see that it starts with the piano keysplit voice, followed by a different piano sample:
At the time of writing this, I don't have an electric grand piano nor a honky-tonk sample setup, so those just have a filler voice. By doing this, if I set a channel to a particular instrument in MidiEditor, I know what sample it will translate to in the .s file.

The percussion can be a bit of a challenge to deal with, though. In MidiEditor, there is no percussion voice, persay. There are melodic-ish percussion instruments, like a taiko drum, timpani, gunshots, you get it. There is no drumkit or anything like that. Instead, for whatever reason, Channel 9 is explicitely set to percussion. Regardless what instrument you set Channel 9 to, it will only be percussion voices, with each note being a different percussion instrument, just like the keysplit percussion voice in pokeemerald. Unfortunately, the different percussion instruments in this percussion voice are not laid out in the same order in MidiEditor as they are in the pokeemerald percussion voice. Some happen to be placed on the same notes in both MidiEditor and pokeemerald, some don't.

Focusing back on the placement of the percussion voice, what I have done is placed the keysplit percussion voice at index 96, or the 97th voice in my voicegroup. That was just a spot that was easy for me to remember. When doing this, I must now be aware that the 97th voice in MidiEditor is not FX 1, and is instead my percussion voice. This means the 98th voice, which is FX 2 in MidiEditor, is FX 1 in pokeemerald, and FX 3 in MidiEditor is FX 2 in pokeemerald, and so on. If I were smarter, I would put my percussion voicegroup in the same spot as a voice that I doubt I will ever use, like telephone ring or gunshot. However, I'm settled in my ways, and there has not been a great enough force to shove me out of this rut. Maybe I'll change it....but then that means I have to change my old songs to look to a different value....I dunno.

Another important detail to consider is that I have effectively removed the last voice in MidiEditor's sound selection, being the gunshot voice. Not a grand loss, but it is something to remember: for each added voice that is not normally in your midi editor's sound selection, you lose access to one of the standard voices in your midi editor, assuming it has the standard 128 voice count. The reason behind this loss is:
1. The VOICE command can only go from 0-127, so any additions would cause the last voice to be at index 128, outside of VOICE's range.
2. Midi editors can't just add a new voice to their collection, or at least MidiEditor can't. So if you add a new voice to the pokeemerald voicegroup, you can't cause it to appear as an option in your midi editor.
A bit of a pain, but the easiest way to go about adding a percussion voice to your master voicegroup would be to replace the last voice in your midi editor's sound selection.

There are some songs where you know you will need several very unique voices for your song. In those cases, it ends up being easier to just create a separate voicegroup for those songs. If you have a ton of songs that use these very unique voices, with each song needing access to different normal instruments in addition to your unique ones, it may be wise to just make another master voicegroup, swapping in those unique voices of yours and keeping whichever normal voices you need. It all depends on whether you think that effort will be worth it for whatever it is you are doing.

Creating a loop is fairly simple. At the point in your midi where the loop begins, add a text event with "[" in it. Looking at the Route 101 theme, we see this "[" show up at the beginning of measure 2:
For the end of your loop, you will add a "]" text event. Again, looking at Route 101, we can see that there is a "]" placed exactly at the end of measure 17 (ignore the fact that it says measure 16. A fun "quirk" about this software is that, if a measure is small enough like measure 1, it ignores the small measure entirely when it is offscreen):
With both of those in place, the .s file that is generated will have a loop established, going from "[" to "]". Looking at the .s file of Route 101, we see this label at the top of measure 2 (labeled as measure 001):
And then we see the GOTO command here at the end of measure 17 (labeled as measure 016):
And that's how loops work. Among the easier things to understand when it comes to midis in pokeemerald.

By this point, you may wonder how one would go about using the extended commands to change the voice envelopes mid-song or apply an echo effect to a particular track. You can still do this through the midi, but it is not intuitive whatsoever.
First, you add a Control Change event that is set to 30, and pass in the value of the extended command that you would like to do. Remember, in sound/MPlayDef.s, the echo-volume command xIECV has the value of 8, and the echo-length command xIECL has a value of 9. So, if we wanted to change the echo volume, the first event that we would add to the midi would look like this:
As you can see, this is the Control Change event marked as 30 in MidiEditor, and I have passed in a value of 8.

Second, you add another Control Change event immediately after the first one, this time choosing the event set at 29 or 31, your choice. For the value, pass in the actual value that you want to set the thing to. In our example, I want to set the echo volume to 100, so I will add this event:
By doing this, we will now see an extended command that sets the echo volume to 100 at the same point as that second Control Change event in the generated .s file:
If you are hoping to be able to do this with the extened commands that change voice enevelopes, we can't do that....at least with what I have told you so far. The explanation for that, as well as the explanation for the weird steps we had to go through to create a normal extended command, is coming up later.

To be able to change any of the voice envelopes mid-song via an extended command requires us to dive into and make some changes to the source code of the mid2agb software, which converts .mid files into .s files. This code can be found in tools/mid2agb. The file that I'm going to be looking at is agb.cpp. If you want to see how certain things are written in the .s file, take a look through this file and midi.cpp. There's plenty that will look really weird and not make much sense, but some of it will be easy enough to understand without too much foreknowledge.

If we go down to a function titled PrintControllerOp, we see this: This function handles converting Control Change events. Here's a quick bit of variable-name vocab for you:

event: an event in the midi. In this context, every event is a Control Change event.
param1: the value of the particular Control Change event type, like 1 for Modulation Wheel or 7 for Channel Volume.
param2: the value passed in to the Value section of the event.

Looking at some of these commands, you may be able to figure out a few of them. For example, 7 relates to a VOL command, and 10 (or 0x0A in hex) relates to a PAN command. People that haven't worked in C or C++ may be a bit thrown off by how these print commands are formatted, but you can look that up on your own time. A decent tutorial on the C fprintf function should suffice. Here's the formal documentation of the function, which may or may not help depending on how programming-literate you are. If we look at what command we get for a value of 0x1D or 0x1F (29 or 31), we see it calls a function named PrintExtendedOp. Immediately above this PrintControllerOp function, we will find this new function: Looking at this function, we see that, based on something called s_extendedCommand, we can either do an echo-volume (xIECV) command, an echo-length (xIECL) command, or just enter a wait command. But what sets this s_extendedCommand? If we go back to PrintControllerOp, we can see that, for the Control Change event that relates to 30 (0x1E), we set s_extendedCommand to the value we passed into the event.

By now, you have the information to understand how we created that echo-volume command in the previous section: We first used the 30 (0x1E) Control Change event to set s_extendedCommand to 8, which, according to PrintExtendedOp, relates to the echo-volume command (this is based on how the echo-volume command is associated with 8 within the pokeemerald code, but it didn't necessarily need to be programmed that way. It was just good association on the programmer's part). Then we used the 29 or 31 (0x1D or 0x1F) Control Change event to pass in 100 as the echo volume value and run PrintExtendedOp. A little weird, but once we look at this code, it starts to make sense. If that doesn't make sense, take another look. What comes next won't make sense if you don't understand this.

So we know how to mess with echo volume and length, but what about the voice envelopes? Well, as this code stands, we can't change those envelopes at all. Thankfully, this code need not stay as it is. To maintain the nice association that the original writer of this code has established between mid2agb and pokeemerald, we should associate the extended commands that change attack, decay, sustain, and release with the numbers 4-7, respectively. To add the attack-change command, we would add case 0x04 to the switch statement in PrintExtendedOp, and then add the text for our XCMD command. It would look something like this: I used "4" in the PrintOp string to access the attack-change command, but if you had added your own constant for it in sound/MPlayDef.s, then feel free to use that instead. With this addition, we can now change the attack envelope of a track in a similar way as we changed the echo volume earlier: 30 Control Change event, this time with a value of 4, then a 29 or 31 Control Change event with whatever value we want to set the attack to. Feel free to add the code for the rest of the voice-envelope commands, so that you have access to them in the future.

Be aware that there is still an issue with this design: these voice envelopes can range anywhere from 0 to 255, but we can only pass in a number in the Value section of the Control Change event within 0-127. What may end up being more useful is creating something that works more along the lines of the next section of this tutorial.

You may eventually come up with some specific effect that you want to be able to use in a song that is not native to mid2agb. While this is more complicated than what we have discussed before, it is not impossible....depending on the effect, of course. For this example, I'll be trying to implement a direct use of the GOTO command, which is normally only used for looping entire songs in mid2agb.

From what I've seen, the easiest way to add a new event type would be through PrintControllerOp. Simply pick a number from 0 to 127 that has not been used yet and you're off to the races. If, due to a miraculous amount of ingenuity or wastefulness, you use all 128 of those numbers, you could start to use some of the numbers relating to PrintExtendedOp or PrintMemAcc. There are plenty of ways to give yourself more room by having certain Control Change events flow into others like the extended commands, but you really shouldn't need that.
1.

2.

3.

We now have the functionality to goto any label we want in the middle of a song! Admittedly this isn't an incredibly useful functionality on its own, but it's a good demonstration of how to utilize a lot of the different elements available to us in mid2agb.

This is the easiest of the methods, since there are less steps involved. It also consumes less memory from the ROM itself.

1. Choose a song that's already in pokeemerald that you are willing to replace. There are a couple of songs that are unused, and many others that are only used in FireRed/LeafGreen, so they're effectively unused in Emerald. If you replace one of these, you aren't losing that much. You can look through sound/song_table.inc to see all of them, as well as short descriptions of where they play in the game.

2. Rename your songs' .mid file to be the exact same name as the files for the song that you're going to replace. (If your version of pokeemerald doesn't have songs.mk, you'll need to create your .s file via mid2agb and rename it to match the file that you're replacing)

3. Place your .mid file into sound/songs/midi, replacing the prior song that had the same name, and delete the .s file for the prior version of the song. Now, you may be wondering: "Why do I need to add my .mid file? You said the game only looks at the .s files, right?" That is true, but when the ROM is being built, if the .mid file isn't there, the build will crash, since it doesn't have a .mid file to create a .s file with. (If your version of pokeemerald doesn't have songs.mk, also place your new .s file into this folder)

4. Build the ROM. Now your .s file should be in sound/songs/midi. (If your version of pokeemerald doesn't have songs.mk, skip this step)

5. Go into your .s file and make sure every label and variable uses the the name of the file. For example, if you look at the file I used in the prior section of this tutorial as an example, you'll see that "mus_rg_ajito" is all over the place. This is the name of the .s and .mid files of that song.
With that, you have now placed your new song in the ROM! Congratulations!

This is a more complex process than the prior method, since there are more steps involved. The only reason I would use this method is if I was using every single song that's in the game already, but wanted to add more music. Otherwise, adding in a new song rather than replacing one that isn't even used would just be wasting space in the ROM.

1. Make sure your filename has no spaces or parenthesis. If you can just stick with letters, numbers, and underscores, then do that, since that's how all of the other songs' names are written.

2. Add your .mid to sound/songs/midi. Now, you may be wondering: "Why do I need to add my .mid file? You said the game only looks at the .s files, right?" That is true, but when the ROM is being built, if the .mid file isn't there, the build will crash, since the .s file has yet to be created. (If you're version of pokeemerald doesn't have songs.mk, you'll need to create your .s file via mid2agb and add it into sound/songs/midi along with your .mid file.)

3. Go into sound/song_tables.inc and go all the way to the bottom of the file. You should see this near the bottom: Right below "ph_nurse_solo", type in your song's filename, following the same format as the other songs. Something like: The first 0 represents which music player you are using. 0 is used for background music, and 1-3 are used for sound effects. Each music player can only be playing one thing at a time, so multiple sound effect players are needed to be able to have multiple sound effects play at once. If you're adding a sound effect, use on of those three sound effect players. The second 0 here has, as of yet, an unknown purpose. It's always the same number as the prior number, so just stick with that.

4. Go into include/constants/songs.h, and go all the way down to the bottom of the file, where you'll see this: Right below "PH_NURSE_SOLO", type in your song's filename, following the same format as the other songs, but have your song's number be 610. Something like: This will allow you to refer to your song in other files, which is necessary to actually play it. The number refers to the position that your song is in sound/song_tables.inc, and since we placed the song just after ph_nurse_solo, your new song's number should be one more than PH_NURSE_SOLO.

5. Go to ld_script.txt and look for the "song_data" section. Once you find it, you should see something like this: Go all the way to the bottom of this list, where you'll see this: Add in your song's filename, following the same pattern as the other songs. Something like:
6. Go to songs.mk, go to the bottom of the file, and add the data for your song. (If your version of pokeemerald doesn't have songs.mk, skip this step) If you wanted your song to have standard reverb, use voicegroup119, have a master volume of 80, and priority of 1, it would look like this: Once you build your ROM, your song will have been successfully added! Congratulations!

Now, say you reeeeally wanted your song's filename to match the name of the song itself, but you still wanted to save space like the first method does. You can do that as well, but it'll take a few extra steps:

1. Choose a song you're willing to replace. You can look through sound/song_table.inc to see all of them, as well as short descriptions of where they play in the game.

2. Make sure your filename has no spaces or parenthesis. If you can just stick with letters, numbers, and underscores, then do that, since that's how all of the other songs' names are written.

3. Go into sound/song_table.inc and look for the name of the song that you want to replace. Change the name to your song's filename.

4. Go into include/constants/songs.h, and look for the name of the song that you want to replace. Change the name to your song's filename in all caps.

5. Go into ld_script.txt and look for "song_data". You should find something like this: Within this list, look for the song that you want to replace. Change the name to your song's filename.

6. Go into songs.mk, find the section that makes the .s file for the song that you're replacing, and rename it to match your .mid file. Change the -G, -R, and any other values you want to match your song. (If you're version of pokeemerald doesn't have songs.mk, skip this step.)

7. Place your .mid file into sound/songs/midi and delete the .mid and .s files of the song that you are replacing.

8. Build your ROM. You should have your .s file in that folder now. (If you're version of pokeemerald doesn't have songs.mk, you just need to make a .s file for your song via mid2agb and place it in sound/songs/midi along with your .mid file.)

9. Go into your .s file and make sure every label and variable uses the the name of the file. For example, if you look at the file I used in the prior section of this tutorial as an example, you'll see that "mus_rg_ajito" is all over the place. This is the name of the .s and .mid files of that song. Once you have done that, your song is ready to be used! Congratulations!

This method takes a few more steps than editing the .s file, but the extra steps don't take that much time. If you don't like editing the .s file and are pretty comfortable with a midi editor, this method is the way for you.

1. Open up the .mid file of your song in a midi editor of your choice. I use MidiEditor, since it's free and simple, but to each their own.

2. Make the changes that you want to make. If we keep following the example I gave, you would look for that one section in the song that had a too-loud instrument and lower it's volume a little bit. Then you would go to that other section and make that track use a french horn instead of a trumpet.

3. Once you've made your changes, save your .mid file into sound/songs/midi, replacing the old version of the song, delete your old .s file, and then build your ROM. Sometimes the song will be unchanged in-game after doing this. This can be avoided by deleting the .o file related to your song in build/emerald/sound/songs/midi before building the ROM. Running make clean before building lets you skip deleting the .s and .o files, but it will take a lot longer to build. If your pokemeerald doesn't have songs.mk, instead of just deleting the .s file, run your midi through mid2agb to get a new .s file and place both your .mid and .s file into sound/songs/midi, replacing the old version of your song.

4. Once you have your new .s file (which will be after you build the ROM if you don't run your midi through mid2agb yourself), double check it to make sure it's using the proper voicegroup and all of the voices are correctly assigned. This can be a rather time consuming step if you're voicegroup doesn't match up with your midi editor's instrument set. All of the VOICE commands will be based on where the instruments are placed within your midi editor, and if those instruments aren't in the same positions as they are in your voicegroup, you'll need to go through all of the VOICE commands and change them. You could just make a large voicegroup that has all of the instruments in the same positions as they are in your midi editor. This will make it so that whatever instruments are being used in the .mid file will be accurately used in your .s file, allowing you to skip most of this step. Just make sure to reassign your voicegroup in your new .s file, since it will be using voicegroup000 again after running through mid2agb, or whatever voicegroup you assigned to it in songs.mk if you have that.

This method takes less steps than editing the .mid file, but you'll need to be pretty comfortable maneuvering through a .s file to use the method. I like this method more than the .mid method, mainly because most of the changes I make are small but numerous. Those sorts of changes are faster to fix in a .s file than a .mid file.

1. You'll need to locate which track has the elements of the song that you want to change. The best way to do this (in my opinion) is to look at the first notes played in each track while also looking at the .mid file of your song through a midi editor. You can then write down which track goes to which section of the song, thus allowing you to more easily navigate the .s file. You may also be able to just see which tracks are which through your midi editor, allowing you to avoid looking at the notes at the start of each track. After you do this once, you won't have to do it again if you want to make more changes to your song later on, since you'll have all of this info written down.

2. Once you know which track to change, go to that track and make the change. Following the example I gave earlier, let's say Track 3 had that too-loud section and that trumpet at measure 012, and measure 012 looked like this: You'd go to that measure and edit the VOL command, lowering that 120 to something like 90. If there isn't a VOL command in that measure, just add one yourself that sets the volume to 90. You could also choose to instead lower the velocity of the notes being played instead of changing the VOL command. This can be better when the volume is fine everywhere else except in this one spot. We can lower the velocity of the first note in this measure from 122 to 90. For changing the instrument, you would make a new VOICE command and enter the index where your french horn voice is in your voicegroup. If there's already a VOICE command there, you can just change the value. Let's assume the french horn voice is at index 10 in your voicegroup. After these changes, this measure would look like this:
3. Once your changes are done, save the .s file.

4. After you build the ROM, sometimes the song will be unchanged in-game. This can be avoided by deleting the .o file related to your song in build/emerald/sound/songs/midi before building the ROM. Running make clean before building lets you skip deleting the .o files, but it will take a lot longer to build. You will also need to edit the MakeFile to make sure it doesn't delete .s files in sound/songs/midi.

First, I rename my .mid and .s files to be "mus_rg_ajito".
Next, I go through my .s file and change every instance of "wind_scene" to "mus_rg_ajito". (This step can be skipped by naming your .mid file "mus_rg_ajito" before sending it through mid2agb)
Then, I stick them into sound/songs/midi, replacing the current mus_rg_ajito.

First, I go into sound/song_table.inc and add in my song at the end of the list: Next, I hop over to include/constants/songs.h and add in my song at the end of the list: After that, I head over to ld_script.txt and add in my song at the end of the song_data list: I double check to make sure my .mid and .s files are named "mus_wind_scene".
I go through my .s file and change every instance of "wind_scene" to "mus_wind_scene". (This step can be skipped by naming your .mid file "mus_wind_scene" before sending it through mid2agb, or by naming your song "wind_scene" instead of "mus_wind_scene" in sound/song_table.inc and include/constants/songs.h. I just add the "mus_" to make it more similar to the other songs already in pokeemerald.)
Finally, I place my .mid and .s files in sound/songs/midi.

First, I go into sound/song_table.inc and look for "MUS_RG_AJITO": (I'm using an older version of pokeemerald, so this song is probably named different for you if you're using a more up-to-date version.)
Once I've found it, I rename it to fit my song: Next, I hop over to inclue/constants/songs.h and look for "mus_rg_ajito": Once found, I change the name to fit my song: After that, I head over to ld_script.txt and look for "mus_rg_ajito" within the song_data list: Once found, I change it to match my song: I double check to make sure my .mid and .s files are named "mus_wind_scene".
I go through my .s file and change every instance of "wind_scene" to "mus_wind_scene". (This step can be skipped by naming your .mid file "mus_wind_scene" before sending it through mid2agb, or by naming your song "wind_scene" instead of "mus_wind_scene" in sound/song_table.inc and include/constants/songs.h. I just add the "mus_" to make it more similar to the other songs already in pokeemerald.)
Nearing the end, I place my .mid and .s files in sound/songs/midi.
Finally, I delete the .mid and .s files of mus_rg_ajito.