Add a new music song

This tutorial is for how to add a new music song. As an example, we'll add the Route 47 theme demixed from HGSS by Mmmmmm.

Contents

1. Define a music constant
2. Create a file for the song
3. Update the music pointers
4. Include the new file in the ROM
5. Composing your own music

1. Define a music constant

Edit constants/music_constants.asm:

 ; song ids
 ; Music indexes (see audio/music_pointers.asm)
 	const_def

 	const MUSIC_NONE                         ; 00
 	...
 	const MUSIC_MOBILE_CENTER                ; 66
+	const MUSIC_ROUTE_47                     ; 67

2. Create a file for the song

If you want to write your own music, skip ahead to step 5, and come back here when you have an ASM file for your song. However, there's already a lot of new music available, demixed and remixed from other games by composers like FroggestSpirit, Mmmmmm, ShantyTown, ShockSlayer, and Pum.

For now, download the source code for Mmmmmm's Route 47 theme and save it as audio/music/route47.asm:

+Music_Route47:
+	musicheader 4, 1, Music_Route47_Ch1
+	musicheader 1, 2, Music_Route47_Ch2
+	musicheader 1, 3, Music_Route47_Ch3
+	musicheader 1, 4, Music_Route47_Ch4
+
+Music_Route47_Ch1:
+	...
+
+Music_Route47_Ch2:
+	...
+
+Music_Route47_Ch3:
+	...
+
+Music_Route47_Ch4:
+	...

Notice the label Music_Route47 before the headers. That's used in the table of music pointers to identify the whole song.

3. Update the music pointers

Edit audio/music_pointers.asm:

 ; See song sections in audio.asm.

 Music:
 ; entries correspond to MUSIC_* constants

 	dba Music_Nothing
 	...
 	dba Music_PostCredits

 ; Crystal adds the following songs:

 	dba Music_Clair
 	...
 	dba Music_MobileCenter
+	dba Music_Route47

4. Include the new file in the ROM

Edit audio.asm:

 SECTION "Extra Songs 2", ROMX

 INCLUDE "audio/music/postcredits.asm"

+SECTION "New Songs", ROMX
+
+INCLUDE "audio/music/route47.asm"

That's it! Now you can use MUSIC_ROUTE_47 like any other music constant—try assigning it to a map in data/maps/maps.asm.

There is one thing to be aware of if you plan to add a lot of new songs. Crystal's music IDs go from $00, MUSIC_NONE, to $66, MUSIC_MOBILE_CENTER. If the IDs reach $80 or above they have their high bit set and start getting interpreted differently by GetMapMusic. There's a full explanation and fix in the design flaws documentation.

5. Composing your own music

In theory, you could write a new song from scratch in a text editor. You'd start by reading docs/music_commands.md and the source code of existing music, then write your own file that defines each of a song's channels note by note.

But that would be quite difficult. It's easier to write a song in the standard MIDI format, supported by many digital audio programs and actual instruments, and then convert the MIDI to a pokecrystal ASM script.

Here are some materials to get started:

• Crystal Tracker: A dedicated pokecrystal-based song editor that reads and writes ASM files.
• Anvil Studio: A free digital audio workstation program for Windows. Includes lots of features for composing your own music.
• MidiEditor: A free program to edit, record, and play MIDI files. More limited than Anvil Studio, but easier to learn if you just want to edit an existing MIDI file.
• VGMusic.com: A source for many MIDIs sequenced or demixed from video games, including most of the Pokémon series.
• MIDI2GSC: An old tool by FroggestSpirit that converts a set of one to four MIDIs, one for each channel, into a single ASM file. It was made back when ROMs were hacked right in a hex editor, so it comes with the now-obsolete GSCImport tool to patch the music right into a GBC file. This tutorial describes what that process used to be like.
• gs2c.py: A Python script by Rangi that converts the output of MIDI2GSC into the up-to-date pokecrystal's music macros. You'll still have to define the headers yourself, and check for any comments of "WARNING: unconverted".
• GB Note: Another tool by FroggestSpirit that can directly open and edit ASM files as well as MIDI files.
• Midi2ASM Converter: A tool by TriteHexagon to convert MIDI files into up-to-date pokecrystal ASM files. Inspired by GB Note.
• Muse2pokecrystal: A script by nephitejnf that converts MusicXML into pokecrystal ASM files. MusicXML is exported by programs such as Musescore and Finale Notepad.

Composing music may be harder to get into than simply editing graphics or text, but it's not at all impossible. Creators like Pigu, coraldev, Mmmmmm, Monstarules, and TriteHexagon have all made original music for pokecrystal-based games.