snarfblam.com

So I made this thing to edit Metroid (NES) music data, and I named it “Metroid Tuner,” because I didn’t feel like trying very hard to come up with a good name. Download the alpha version and it will probably work. Or it might blow up your computer. Metroid Tuner dumps and inserts music using a relatively simple text-based format. It can not currently be used from the command line, and it will probably stay that way unless somebody requests the feature (they wont). So here’s how it works:

Dumper

When you first open the dumper, you’ll get a window with a bunch of confusing check-boxes and hexadecimals. It’s cool, though, you only need to worry about the two things highlighted in red (unless you’re doing something tricky).

Click the button next to the “Rom File” input to browse for a ROM to dump (or just type in the full path). Then select what you want to dump from the “Presets” list. If you want to get tricky, you can select individual songs, or even individual tracks from songs, in the tree to the left (be warned, only one track specifies how long the song should be, and if this track isn’t dumped, the dumper will have a hard time figuring out when to stop dumping music data). There are also a couple of other song-related bits of data you can dump.

The input boxes below the presets are mostly there in case you’ve moved around important data that you’ll probably never move around. Once you’ve picked your ROM and what you want to dump, click “Dump” in the lower-left corner.

Song dump

Editor

When you dump the ROM, the dump is displayed in a text editor in a new tab. There’s lots of confusing stuff in there, which warrants some explanation. The good news is that you can freely ignore a lot of it. Skip down to “<Track> Section” if you don’t like reading. One thing I’ll point out is that comments begin with a double slash, // Like so.

<Context> Section

The <Context> section simply contains all the pointers you were instructed to ignore in the “Dumper” tab (in the form of [Fancy: Tags]). Continue ignoring these. The only tag worth mentioning is the [Bank] tag, which says which ROM bank we are dealing with.

Each level’s data resides in a separate, self-contained bank, and for some songs, there is a separate copy in each bank (for example, the item room music). Each dump file only deals with one bank (you can dump separate banks to separate tabs, however). Changing music data in one bank will never affect music in another bank.

<Song> Section

The <Song> section(s) are optional. They specify properties of the song. [Song] specifies the index of the song we are dealing with (look at the “Dumper” tab to see the list of songs and indecies). [Repeat] specifies whether the song loops.

As a form of compression, the game stores a few lists of pre-defined note lengths that you can use. [NoteLengthTable] specifies which note length table to use (00, 0B, and 17 identify the note length tables used in the game).

[TriangleLength] affects how long notes play on the Triangle song track. 00, 0F, and F0 are the only meaningful values here. I wish I could tell you exactly what they mean. [Sq1VolumeTable] and [Sq2VolumeTable] specify which “volume table” each of the Square song tracks use. This affects the sound of the track’s “instrument.”

<Track> Section

The <Track> section is the good stuff. This is where the music data is actually stored. The [Song] and [Track] tags identify which track of which song the data pertains to. [MaxSize] specifies the largest data size we want to insert. You know, cause we don’t want to overflow into the game’s program and ruin everything. If you need more space for music data, find a large enough unused space for the data, and update [Address] and [MaxSize] accordingly. As far as the actual music data, well, we’ll cover that below.

Other Sections

<NoteTable> defines the pitch of each note. If you change this, the notes shown in Metroid Tuner wont match those heard in the game. <NoteLengthTable> specifies the pre-defined note lengths used in the songs. If you change the note length table, be careful. Some tables affect multiple songs. Each <VolumeTable> helps define one of the game’s instruments. (The other aspect of the instruments is the game’s “duty-cycle and volume” data. If you want to change these values, you’ll need to dig around in Dirty McDingus’ Metroid disassembly.)

Music Data Format

Music data is represented as a list of notes, using the note’s letter, followed by a # for sharp or lowercase “B” for flat, followed by the octave. For example, a middle C would be written as “C4.” The next half-note up would be “C#4” or “Db4”. Before any notes are listed, a note length must be specified.

Note lengths are specified by the number of frames a note will play. Since the game runs at sixty frames per second, a note length of 60 will play for one second, a note length of 30 will play for half a second, and so on. A note length is written as a colon, followed by a hexadecimal number. For example, “:40” specifies a note length of 64 frames ($40 in hex = 64 in decimal), or roughly one second. After a note length is specified, all following notes will have that length until a different note length is specified. A dash (“-“) represents a rest (the duration of a rest is specified the same way as any other note).

// Example: first four notes of "When the Saints Go Marching In"
:20   // 0.5 second notes
  C3 E3 F3
:60   // 1.5 second note
  G3

For the “Noise” track, instead of dealing with notes, we deal with sound effects identified by a number in the hex format “$XX”. These numbers are preceded by a dollar sign. $01 is a rest. $02-$05 are meant to be used as drum sounds. Values $06 and up are not meant to be used, but they certainly do seem to produce some sounds. $00 should not be used, but if you insist on using it, it will behave like a song terminator.

Loops are enclosed in {curly braces}, with the number of times the loop will run before the braces. Nested loops are not supported.

// Example: first eight notes of "When the Saints Go Marching In"
2 { // Play these notes twice
    :20   // 0.5 second notes
      C3 E3 F3
    :60   // 1.5 second note
      G3
}

Note that the layout of the music data is completely up to you. The above listing could also be written as the more compact and harder-to-read 2{:20 C3 E3 F3 :60 G3}.

At least one track should have a “song terminator” at the end. This is represented by a double-zero (“00”), without a dollar sign. As the game plays the music, if a song terminator is encountered, all tracks will stop, and playback will begin at the beginning of the song if song is set to repeat. If you forget to include the terminator when you insert, and you try to re-dump the song, the dumper wont know where the end of the song is, and you’ll end up with extra garbage.

One important thing to know is that you are restricted in what note lengths you can use (see <Song> Section). If you want to know which note lengths are allowed, check the check-box labelled “Note Length Table” in the dumper tab (you may have to scroll down). At the end of the dump there will be a list of note lengths.

Inserting

In the toolbar in the text editor window, there is a button with a green arrow. If you hover your mouse over it, a tool-tip appears with the text “Insert”. Click this button. Beware: this is when Metroid Tuner is most prone to violence toward domesticated animals. If everything goes well, it will appear as though nothing has happened. Play the ROM and you’ll find, however, that something has indeed happened. If there are errors, they will be listed at the bottom of the text editor. Right-click the error list to hide it.

Tip: if you want to insert into a ROM without dumping anything first, using the “Dumper” tab, select your ROM, and use the “None” preset. It will bring up a text editor for the ROM with a blank slate where you can paste in your data-to-be-inserted.