This tutorial is for how to add a new music song. As an example, we'll add the [Route 47 theme](https://soundcloud.com/mmmmmmmmmmmmmmmmm-1/route-47-gbc-8-bit) demixed from HGSS by [Mmmmmm](https://soundcloud.com/mmmmmmmmmmmmmmmmm-1).


## Contents

1. [Define a music constant](#1-define-a-music-constant)
2. [Create a file for the song](#2-create-a-file-for-the-song)
3. [Update the music pointers](#3-update-the-music-pointers)
4. [Include the new file in the ROM](#4-include-the-new-file-in-the-rom)


## 1. Define a music constant

Edit [constants/music_constants.asm](../blob/master/constants/music_constants.asm):

```diff
 ; 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

Writing your own music is beyond the scope of this tutorial. If you're interested in doing that, start by reading [docs/music_commands.md](../blob/master/docs/music_commands.md) and the source code of existing music. However, there's already a lot of new music available, demixed and remixed from other games by composers like [FroggestSpirit](https://soundcloud.com/froggestspirit), [Mmmmmm](https://soundcloud.com/mmmmmmmmmmmmmmmmm-1), [ShantyTown](https://soundcloud.com/huderlem), and [Pum](https://www.youtube.com/playlist?list=PLQHiVZUO5so0LHdQzx6iu4Ze0zCkbbm7N).

For now, download the [source code](https://pastebin.com/raw/aSDuVfDW) for Mmmmmm's Route 47 theme and save it as **audio/music/route47.asm**:

```diff
+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](../blob/master/audio/music_pointers.asm):

```diff
 ; 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](../blob/master/audio.asm):

```diff
 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](../blob/master/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 at the [hard-coded logic](Hard-coded-logic#some-high-values-for-maps-music-ids-play-incorrectly) page.