Tool: RBY Music Importer (for .FTMs)

Sonic65 · Sep 5, 2010

Figured I should probably register and post this here too, since this thread here was a big help to me...even if this entire post is basically just a copypaste from the Pokecommunity one (well, will be as soon as it gets approved anyway)

Anyway, I've been researching R/B/Y ROM hacking for a short while now, and I found that there was little real documentation or tools on the music side of the game (well actually in general, compared to 2nd/3rd gen). So I made this program to import music into an R/B/Y ROM - more specifically, import .ftm songs made with the program Famitracker, a music tracker for the NES.

Example of what this program can output (in-game sound recording)

What does it support?

Importing of all 4 basic sound channels (square 1/2, triangle, noise)
Both .ASM and .BIN export
Quick ROM inject feature for .BINs
Famitracker note fade-outs (using the volume column) and duty cycle changes (by changing instruments)

What doesn't it support?

MIDI import or any other file format other than .ftm
Any Famitracker effects

Link to download

Files in zip:

rbyImport.exe - The actual RBY Music Importer program.
blitz3d_gui_dll.dll - A DLL the program uses.
readme.txt - Derp. Doesn't have anything this post doesn't anyway.
route202.ftm - Sample FTM file to import (used in tutorial below). A NES/GB demake of the Route 202 theme for Pokemon Diamond/Pearl.
noiseChannelDoc.txt - Documentation on the music format Pokemon R/B/Y uses for noise channels (this didn't seem to be documented anywhere, so I investigated it myself - it's different from the regular music channels, and uses drum presets)
pkms.asm - Macros and equates for ASM files created with RBY Music Importer. (PKMS is what I call the Pokemon RBY music format, standing for Pokemon Music System)
rgbasm.exe - GB compiler, part of RGBDS suite
xlink.exe - GB linker, part of RGBDS suite

How to Use: A Tutorial

To illustrate how to use RBY Music Importer, we're going to import the sample song (route202.ftm) and replace Pallet Town's music with it. Here's a step-by-step guide (I suck at writing tutorials but hopefully you'll understand this):

Open up RBY Music Importer and go to the FTM->ASM section. Load route202.ftm using the Load FTM button.
Using the DataCrystal ROM map of Pokemon Red, you'll find that Pallet Town's music data starts at $A7C5, so put in $A7C5 as the start offset.
Check the "Import noise channel" box. You don't need to change the tempo for this particular song, but you might need to for other songs (more on that later).
Click the "Make ASM File" button. RBY Music Importer will generate an .asm file called route202.asm. At this point you have one of two options: either you can go and tweak the ASM file (changing notes, adding effects like vibrato and modulation, etc.), or just proceed straight to .BIN conversion. Let's go straight to .BIN conversion and injecting, for the purposes of this tutorial.
Go to the ASM->BIN section and load the route202.asm file we just created.
Click the "Inject music into ROM" checkbox.
Set $A7C5 (the same offset as above) as the injection offset. (If you changed the start offset in the ASM file, you'd put that value here instead.) Using the same ROM map as above, you'll find that Pallet Town's song pointers start at $822E, so input that for the pointer offset.
Click the "Compile BIN File" button.
Done! If you did everything right, when you load your RBY ROM, Pallet Town's music should be replaced with Route 202!

Special Notes

There doesn't appear to be any hard-set formula for converting Famitracker song tempo into PKMS song tempo, but here are a few tempo matchups which might be useful to you:

Code:

$E0 - speed 6, tempo 85
$D0 - speed 6, tempo 90
$C0 - speed 6, tempo 100
$B0 - speed 6, tempo 110
$A0 - speed 6, tempo 120
$90 - speed 6, tempo 140
$80 - speed 6, tempo 160
$70 - speed 6, tempo 180
$60 - speed 6, tempo 200
$50 - speed 6, tempo 220
$40 - speed 6, tempo 260
$30 - speed 6, tempo 340

Finally, I'd like to thank:

Coolboyman and Melash, for creating the document I linked
Data Crystal, for their Pokemon ROM map

So yeah, that's all. Hopefully this utility will be useful to somebody other than me.

~Teh Panda~ · Sep 6, 2010

Well this looks certainly interesting, but do you think you could post how this would be more beneficial then using Sappy, or if it's different as a whole. Because I haven't tried it and don't see reason to until I know exactly what it can do better than what we have.

Thanks :)

EDIT: Wow, this is for Red, Blue, Yellow. I am stupid... XD...

Well this should be nice for GB/GBC era hackers...

Sonic65 · Sep 6, 2010

Team Fail said:
EDIT: Can you get this to work with .nsf files as well?

An NSF file is literally just a modified NES ROM, with only music code and data - since the format of music data and how it's played differs from game to game, there's no standard format and it can't really be done (although VirtuaNSF has a keyboard player thing for NSFs, I might look and see how that's done). You'll have to do with manually recreating songs in Famitracker (or composing new original ones).

I might be able to put in MIDI support later down the line, but that's just a pipe dream for now.

Chaos Rush · Sep 9, 2010

Would this work for Pokémon Gold? Also, how would I port R/B/Y music over to Gold?

Sonic65 · Sep 12, 2010

Updated OP with new bugfixed version, which should hopefully fix some of the bugs people are having. (Thanks to Team Fail for his help with this, even though we could never get it completely working on his computer :()

Would this work for Pokémon Gold? Also, how would I port R/B/Y music over to Gold?

If you changed the equates/macros in the pkms.asm file it could probably work, at least with the first three channels (noise channel values are hardcoded as of now, so you'd need to change those manually in the .asm file that RBY Music Importer outputs before compiling the .bin). This document is a pretty good resource for the G/S/C and R/B/Y music format (though I had to find the RBY coordination flags myself, but those are already documented in pkms.asm).

As for porting music from R/B/Y, that's not something this tool allows you to do (unless you resequence the entire thing in Famitracker, LOL) - you'd have to do that manually in a hex editor (changing pointers and all).

Heart's Soul · Sep 22, 2010

Interesting, considering most of the Red ROM map was made by Coolboyman.

Chaos Rush · Jan 1, 2011

I'm having trouble getting this to work with G/S/C. This is what I've changed the pkms file to:

Code:

    ; ===========================================================================
    ; PKMS equates and macros
    ;
    ; ===========================================================================

    ; equs
    MUSIC            EQU 0
    SFX            EQU 4
    CH1            EQU 0
    CH2            EQU 1
    CH3            EQU 2
    CH4            EQU 3

    ; notes
    ntC            EQU $00
    ntC#          EQU $10
    ntD            EQU $20
    ntD#          EQU $30
    ntE            EQU $40
    ntF            EQU $50
    ntF#          EQU $60
    ntG            EQU $70
    ntG#          EQU $80
    ntA            EQU $90
    ntA#          EQU $A0
    ntB            EQU $C0
    ntRst          EQU $B0

    ; special drum EQUs
    dNote          EQU $C0
    dRst            EQU $B0
    dNormSpd     EQU $DC
    d4d3Spd       EQU $D8
    d5d3Spd       EQU $D4
    d2Spd          EQU $D0

    ; octaves
    oct0            EQU $D7
    oct1            EQU $D6
    oct2            EQU $D5
    oct3            EQU $D4
    oct4            EQU $D3
    oct5            EQU $D2
    oct6            EQU $D1
    oct7            EQU $D0

               
    ; header stuff
    pkmsHeader:    MACRO
                db    ((\1 - 1) * $40) | (\2 + \3)
            ENDM
                   
    pkmsChannel:    MACRO
                    dw    \1
                       
                    IF \2 != 0
                        db    \2
                    ENDC
                ENDM

    ; coordination flags

    ; set velocity/note fade (\1 is velocity, \2 is note length, both 0-15)
    ; format:    pkmsSetVel        vel, length
    pkmsSetVel:        MACRO
                    db    $DC
                    db    ((\1 << 4) | \2)
                ENDM
    ; stop sound
    ; format:    pkmsEndSound
    pkmsEndSound:    MACRO
                    db     $FF
                ENDM
               
    ; $E8 (unknown)
    ; format:    pkmsE8
    pkmsE8:        MACRO
                    db    $E8

                ENDM
               
    ; set modulation (\1 is delay, \2 is depth, \3 is rate)
    ; format:    pkmsModSet        delay, depth, rate
    pkmsModSet:        MACRO
                    db    $E1
                    db    \1
                    db    ((\2 << 4) | \3)
                ENDM

    ; set duty cycle (\1: 0 = 12.5%, 1 = 25%, 2 = 50%, 3 = 75%)
    ; format:    pkmsSetDuty        duty
    pkmsSetDuty:    MACRO
                    db    $DB
                    db    \1
                ENDM
               
    ; set music tempo (\1 is divider, \2 is modifier)
    ; format:    pkmsSetTempo    divider, modifier
    pkmsSetTempo:    MACRO
                    db    $DA
                    db    \1
                    db    \2
                ENDM
               
    ; set volume (\1 is volume)
    ; format: pkmsSetVolume        volume
    ; (may actually be panning?)
    pkmsSetVolume:    MACRO
                    db    $F0
                    db    \1
                ENDM

    ; call offset \1
    ; format:    pkmsCall    offset
    pkmsCall:        MACRO
                    db    $FE
                    dw    ((\1 % $4000) + ((\1 >= $4000) * $4000))
                ENDM
                           
    ; jump to offset \1
    ; format:    pkmsJump    offset
    pkmsJump:        MACRO
                    db    $FD
                    db    $00
                    dw    ((\1 % $4000) + ((\1 >= $4000) * $4000))
                ENDM

All I've managed to do so far is to replace New Bark Town music with silence. I looked at the Gold Music Hacking Resource document, and changed the bytes accordingly, but all I get is blank music.

WrathOfArceus · Jul 13, 2011

I did it write,But when i click compile BIN File to insert it, it says memory access violation,And Pallet town's music is still playing.Help!!!!

Cheesewig · Jul 15, 2011

Every time I insert an FTM the game freezes when I go to the location.

YORAMRW · Mar 1, 2013

Too bad, this program has no Apreggio and ''4XX'' support.
PS: The ''4XX'' effect is a feature which is used in Game Boy games like Tetris, Name Entry.
I hope you will make a new version with support for that.

YORAMRW · Apr 12, 2013

That "4XX"-effect is called LFO.

Airikita · Oct 20, 2013

I can't download your tool, I get a message on that site that prevents me from downloading....

spartanreptile13 · May 21, 2015

I need help trying to change the RBY Trainer Battle to XY Trainer Battle

1. What is the tempo hex for Speed 2, 150 bpm?
2. What is the injector hex for Trainer Battle theme?

rinGallows · Dec 7, 2016

when i loaded the game when it went to pallet town it froze is there anyway to fix this?

E-cat420 · Mar 17, 2018

I noticed the that the download link for RBYImport doesn't work any more. Is there any alternate download, and, if not, can anyone provide me with a copy of the program?

Please, this would be so much easier than using pokemid or editing the asm, both of which are nearly impossible for someone of my low skill level.

Tyranitar_Best · Feb 26, 2020

It would be great if someone of you had a link for the music editor, because as E-cat420 already said the old link is dead. I need this because I want to change some of the music in my own hack which I am currently working on. If someone has a NEW working link then please put in the comment section, because I can't find it anywhere

Tool: RBY Music Importer (for .FTMs)

More options

Sonic65

welp

~Teh Panda~

Back in hacktion

Sonic65

welp

Chaos Rush

Sonic65

welp

Heart's Soul

Hey, look, I was gone.

Chaos Rush

WrathOfArceus

Arceus Tamer

Cheesewig

Hi!

YORAMRW

8-bit producer & Pokémon GB music hacker

YORAMRW

8-bit producer & Pokémon GB music hacker

Airikita

spartanreptile13

rinGallows

E-cat420

Mystery, Hiding In Ruins of Thought

Tyranitar_Best