SkySongBuilder Tutorial

This article is unfinished. You can help expanding it.

This guide explains how to use SkySongBuilder to add custom music to the game. It currently only explains how to add streamed music (.wav files).

This guide is for Windows use. There may be some issues if you are using macOS or Linux.

WARNING: This guide is under the assumption that you have not applied any other .skypatches aside from the ones listed inside. If you already have applied .skypatches, there may be conflicts that prevent it from working. You may wish to ask someone knowledgable about ASM to adjust the .skypatches required accordingly.

Streamed music

Streamed music refers to any files that contain raw audio data, such as a .wav file. They are inserted as-is into the ROM, which has the disadvantage of increasing the ROM size. However, the process is easier than inserting sequenced music.

Required programs and files

SkySongBuilder: https://github.com/adakite1/skysongbuilder/releases

Armips: https://github.com/Kingcom/armips/releases

Fifohooks: https://github.com/adakite1/Asm-patches

DSLazy: https://www.romhacking.net/utilities/793/

SND Stream: https://discord.com/channels/710190644152369162/799584781225820210/1172750070710534244 (SkyTemple Discord Server)

soundtrack.yml: https://github.com/adakite1/skysongbuilder/blob/master/soundtrack.yml

If any of these are zipped, they must be unzipped before use.

Optional:

PlayMoreBGM: https://github.com/Adex-8x/jam-patches/blob/master/strung-up-by-sketches/PlayMoreBgm.skypatch

If any of these are zipped, they must be unzipped before use.

Make a copy of your .nds before continuing.

Prepwork

Apply ExtraSpace ASM patch in SkyTemple.
Download "Fifohooks." It comes in the form of a .skypatch file.
- To apply, open your .nds in SkyTemple. Go to "ASM" -> "Others" -> "Open Patch Directory..."
- Drag the Fifohooks patch into the folder that opens, then close it.
- Refresh the "Others" page, and the FifoHooks patch should be there. Apply it. The ROM should save and reload.
Downlad "armips" and "SND Stream." The SND stream patch needs to be applied manually with "DSLazy" or a different DS packing program. To do so:
1. MAKE A COPY OF YOUR .NDS JUST IN CASE
2. Unpack your .nds with DSLazy. Click the three dots on the top left, select your .nds, and click "nds unpack."
3. Unpacking may take a minute.
4. A folder should open containing files such as arm7.bin, arm9.bin, banner.bin, etc.
5. Open the folder named "Overlay". Find "overlay_0036.bin." and drag it into the folder with arm7.bin and such.
6. Drag SND Stream into that folder as well. If done correctly, your new folder should contain the following: data (folder), overlay (folder), arm7.bin, arm9.bin, banner.bin, header.bin, y7.bin, y9.bin, overlay_0036.bin, SND_Stream, armips.exe.
7. Now we need the programs to work their magic. On windows, hold shift and right-click anywhere in the folder containing these files. Then click "Open Powershell Window here".
8. Type ./armips.exe snd_stream.asm. If it looks like nothing happened and you got no error messages, then it worked!
9. Lastly, go back into the folder and move "overlay_0036.bin" back into the overlay folder.
10. Close, then go back to DSLazy and hit "nds packer." It will ask where you want to save the new .nds file it will make. If you already started a ROM hack, it would be best to save directly over the .nds you are working on. Again, MAKE SURE YOU HAVE A COPY OF THIS .NDS JUST IN CASE.
11. Once DSLazy overwrites your .nds, the prep work is done! You are now ready to use SkySongBuilder!

Translating music

First, download "SkySongBuilder" and "soundtrack.yml". Create a brand new folder with only those two things, and any songs you want to put into your game.

Now we need to edit "soundtrack.yml." I use notepad which all windows computers should have. Open notepad. Click "open" on the top left.

You should now be looking for a file to open with notepad. On the bottom right, make sure you tell your computer that you are not picky. You want to search for ALL files. Not just .txt files like notepad is bias towards. Otherwise, you may never find the "soundtrack.yml" file we want to open. This is where we will actually be adding music for SkySong to translate into a format SkyTemple and your game can read.

"soundtrack.yml" has many different features. If you only want to play a song, you can ignore 99% of everything.

Scroll down until you find the section labeled songs: under the "Add songs here" comment. For simpliciy sake, delete everything under, but not including, songs:. Then you may add this template block.

	Buried_Oasis:
		i: 194
		raw: Buried_Oasis.wav
		loop_point: 846720
		formats: [Wav4BitAdpcmNDSPlanarStereoLooped]
		dsp:
			adpcm_block_size: 16377
			adpcm_encoder_lookahead: 4
		flags: SND_STREAM

There are only a few things you need to change.

i: is the slot of the song. The game has several unused slots already we can use to add new music. These are slots 194-201 for a total of 7 additional songs. If you want more songs without removing existing songs you must apply Adex's PlayMoreBGM .skypatch which can be found above. The installation process is the same for the fifohooks installation. Each song you add needs it's own slot, starting at 194, just as mine does.

The name of the song above i:

raw: should contain the exact name of your file that is also in the folder with "SkySongBuilder" and "soundtrack.yml".

loop_point: should also be changed if you want your song to loop. If you do not want it to loop, delete the line.
- Loops are measured by the sample rate. The sample rate will be determined by the song you used, but it is very likely to be 44,100hz. This is the amount of time per second. You must make your loop with this in mind.
- Just about every song in Explorers of Sky has a short intro, then loops at a later point in the song. The intro does not loop. To account for this, you must use some sort of music creation program to view when the exact loop point would be in your chosen song, ideally to the milisecond. Once you do that, you can easily do the math to determine where your loop point would be.

Loop Point Examples (again, assuming a sample rate of 44,100 Hz):

2 Seconds = loop_point: 88200

3 Seconds, 520 miliseconds = loop_point: 155232

7 Seconds, 240 miliseconds = loop_point: 319284

Once you have that done, save the file. You can also add multiple songs in the same way and import them all at once! Just make sure that they each have a different "i:" value, starting from 194. You can put each song "block" below the previous.

Last step to translate! Inside the folder you made, you should have "SkySongBuilder", "soundtrack.yml", and the songs you want to include in your game.

Hold shift and right-click anywhere in the file. Open up powershell again.
Type ./skysongbuilder.exe
If everything works, you should see powershell freak out and do a bunch of stuff. Wait until it's done. It could take a minute, especially if you are doing multiple songs at once. After it stops, go check your folder again.
You should now have a folder named "out" in there with "SkySongBuilder", "soundtrack.yml", and your songs. Open it and take a look. It should have "bgm.swd" and then a bunch of files with 194, 195, or whatever value you used for "id" in the name. If you do, then you are good to go!

Importing music

Go back to DSLazy and crack open your .nds again. You could have condensed some steps and only unpacked once, but this guide will go step by step to be as simple as possible.

Open Data/Sound/BGM. This folder contains all the music in the game. Copy all the files in the "out" folder and paste them into "BGM". Repack your .nds as before.

Playing music

Use bgm_Play(194); on a script to play your song! Just change the number to whatever ID you used for each song. You are now streaming music!

Playing your music as a dungeon song requires one more additional process:

Open where your SkyTemple program is located in your files, then open the following file: skytemple-files/_resources/ppmdu-config/pmd2scriptdata.xml
Search for "HeavyWind6". This is the final song in the BGM section of the file. All we need to do is add a few lines.
In between HeavyWind6's line and "BackgroundMusicIDs", add <Bgm loops="true">YourSongHere</Bgm>. If you are adding multiple songs, add one line per song. And obviously, change the title of the song to yours.

To add your song to the list of songs that can be played in dungeons, follow these steps:

Open your .nds in skytemple. Go to Lists -> Dungeon Music.
We need to replace a song. Luckily, there are tons of repeated songs. Scroll to the bottom and you can find a ton of "BossBattle" slots.
Click one, then click the dropdown arrow. Scroll to the bottom and your song should be there! Select it, save, and you are done!

Congratulations! You are now ready to play music in your hack! Keep in mind that streaming music does sometimes freak out on emulators, especially older versions of desmume. Make sure your emulators are up to date!

Sequenced music

This section is unfinished. You can help expanding it.

Sequenced music refers to any files that contain basic information about how music should be played (such as when each instrument note starts and ends), rather than audio data. They take a lot less space than streamed audio files, but creating and editing them is more complicated, and they are subject to engine limitations.

When creating sequenced music, it should be noted that Explorers of Sky cannot play more than a certain number of voices at the same time. The number of voices is roughly equal to the number of instruments playing at any given time. The exact limit is currently unknown, but it's likely between 10 and 16.