mml2m64 is an experimental .mml importer that produces custom music in the Mario 64
and Zelda 64 sequence format. The main importer module is built from Addmusic's (revX)
MML parser, so big thanks to whoever wrote that program. You can download Addmusic
binaries, source code and documentation at http://www.smwcentral.net.

The importer is to be used along a MIDI -> MML conversion tool, such as tinymm or
mid2mml, both of which can be download at SMW Central. Afterwards, you can insert the
custom music using the sequence inserter tool included in this package, which replaces
the original Mario 64 sequences files with your custom music.

This package also includes a few more music-related tools, such as sequence rippers
for Mario and Zelda 64 as well as parsing utilities that can display all the sequence
content. A description of all the tools included and their usage can be found below in
this document. All sources are in the src folder except mml2m64, because it will be
cleared and partly rewritten for a next release.

Here is a sample of mml2m64's output (first release):

mml2m64 sample

What is the .mml format?
Music Macro Language (MML) is a text-based format suitable for simple sequenced music.
The basic format is very simple and consist of the following fundamental syntax:

This is the syntax adopted by Addmusic and followed by mml2m64. There are also some
custom commands which will be covered briefly. You can good overviews of the MML format
in Wikipedia (http://en.wikipedia.org/wiki/Music_Macro_Language) and in the "Documents"
section of SMW Central (look for custom music tutorials).

I strongly recommend associating the .mml extension with Notepad/Worpad so you can
edit the .mml files just by double clicking them.

What are .m64 and .zseq files?
Both .m64 and .zseq are arbritarly file extensions I came up with to designate
sequence files which follow the specifications used by Mario 64 and Zelda 64. The idea
is to have a portable format which can be easily shared and inserted in any suitable
ROM. This package only includes a Sequence Inserter for Mario 64, but eventually I
may also release one for the Zelda Debug ROM.

You can find the most recent specification of the Mario 64 format at my site:
http://sites.google.com/site/messiaen64/mario-64-sequenced-music-specification

Custom commands guide
Besides the basic mml syntax, mml2m64 support a few custom commands, most of them
based on Addmusic's implementation.

You can use ';' for comments. Everything after the ; until the newline will be ignored.
If no tempo and volume are specified, default settings will be used. By default, songs
will loop.

Channel commands:
----------------

# = Begin channel data -> Only use once for each channel. In theory, you can use
up to 16 channels, but some channels are reserved for Mario sounds, so it's better
to leave some of them free. After the '#', follows the channel number. Channels
are numbered starting from 0 up to 15. Channel #9 (10) is usually used for drums,
like MIDI.

v = Track volume -> Volume for this channel (min: 1, max: 255)

@ = Instrument number -> Instrument index for this channel. There isn't a master
index of instruments, but a index specific to the sequence you are replacing. For now,
the only way to know what instrument will be used is to experiment. You can try
values between 01 and 20. If you want it to be a drums/percussion channel, use
instrument number 127. If none is specified, a random value is used (from 1 to 8).

k = Gate Time -> This is a custom command specific to mml2m64. In MIDI, gate time is
the distance between NoteOn and NoteOff events. Use higher values for non-legato and
staccato and lower values for legato. If none is specified, a default value of 80
will be used, which usually produces a 'non-legato', but that depends on the instrument
you're using.

Here is an example of channel commands used between blocks of track data (musical
events) in a .mml file that follows mml2m64 commands:

Now to turn this into a .m64 file, just run "mml2m64 victory.mml" (or drag
and drop a .mml file into mml2m64 if you are using Windows) and a file called
"victory.mml.m64" will be created. To insert it in the ROM, you'll need to use
the Mario 64 Sequence Inserter. To produce a .zseq file, include the -zelda
argument: "C:\my_mml2m64_dir\mml2m64 victory.mml -zelda".

You can find a guide showing the usual steps from MIDI to a proper .mml
file in the tutorial.txt file.

Mario 64 Sequence Inserter (insert_seq.exe)
After the .m64 is ready, the custom sequence must be inserted in the ROM.
The Sequence Inserter replaces any of the original sequences in an extended
Super Mario 64 ROM with custom music (.m64 files). The new sequence files are
copied after the original ones, which are keep intact in case you want to revert
(using the m64seq_clean tool).
The Sequence Inserter is a console program, so you must run it from the
command prompt.

Replacing all sequences at once is very useful so you can test how the same
sequence sounds in different instrument sets.
The custom sequences are saved from 0x7cc6c0 to 0x800000 in the ROM, after
the original sequence bank end and before the first uncompressed MIO0 segment
(in an extended ROM). If you have run out of space, rom m64_seq_clean to clear
all the area between 0x7cc6c0 to 0x800000 and revert the pointers to the original
ones.

Tutorial: from MIDI to .m64
This simple tutorial will guide you through the steps required to make an .m64 file
from a MIDI file. First, you'll need an external program that converts from MIDI to MML.
For this tutorial, I will use tinymm, which can be downloaded at SMW Central Tools
section.
The MIDI file victory.mid will be used in this example. Just run victory.mid through
tinymm (either using the console or dragging and drop a file there) and you shall get this
output in a file called victory.mid.mml:

At this point, the .mml file is already compatible with mml2m64, so if you drag and
drop the text file above a valid .m64 will be produced. However, there are still some things
you'll have to do to make it sound better. First, let me remind you that channel 10 in MIDI
is used for drums/percussion, so remember to assign instrument @127 (drums) to channel #9.
In the following step, I also assigned random instruments and volume settings:

After inserting the sequence in the ROM with the Sequence Inserter, you can hear that
this sequence is not to be looped, and that the first channel is on the wrong octave. After
correcting this, here is the final version of it:

There might be another adjustments you want to do for even better results, but these are
the basic steps to use a MIDI file.

Troubleshooting
So you did everything right but found out there are missing channels,
instruments out of range and other problems? This section will guide you through
a few possible workarounds. Let me remind you that this is the very first (working)
release of this program, so not everything will work greatly.

1 - One/some of the channels doesn't work.

Try changing the channel number (# command) or the instrument (@ command). Some
channels are reserved for Mario sounds, so there might be conflicts. If you replace
one sequence which is played at the same time as another (ie, Toad's music from
Inside Castle or the Piranha Plant lullaby) you'll have to make sure they don't use
the same channels. Also, when you first convert your .mml file, try using the first
5 instruments (@1 to @5), as sometimes higher values can result in invalid instrument
settings depeding on the sequence you are replacing.
I recommend also using the "-all" option of the sequence inserter to find out if
the problem isn't specific to the sequence you are replacing. Alternatively, you can
run m64parser on the original Mario 64 sequences to know which channels each original
sequence is using.

2 - The notes of a specific channel are too low/too high.

There are two workarounds for this. If you are importing from a MIDI file, you can
use some notation program (such as Finale Notepad) to lower the octaves until you find
an ideal range. Alternatively, you may also work directly with the .mml file. A good way
is to avoid this is to change the initial octave setting. For instance:

<<c16^8 d16 e1 --> to avoid this getting too low, just remove one of the
octave lowerews ("<") from the beggining and everything
will sound one octave higher.

Some instruments have more limited ranges than others, so even if mml2m64 doesn't
wary you that the note is too high, it might not work with that specific instrument. Be
sure to experiment many different instruments to get optimum results.

3 - My Super Mario World .mml file doesn't work very well in mml2m64.

Although this program is based on Addmusic, there are some differences in the .mml
implementation. Commands such as loops ('[' and ']') aren't supported yet and channels
are handled a bit differently. Most unsupported commands will be ignored, so there is a
good chance that with some work you can port your SMW .mml to mml2m64. During the initial
development stages of this program, I used .mml files from the Custom Music section of SMW
entral with varying degrees of success, so you might want to experiment with that also if
you are already familiar with the .mml format

4 - The sequence Inserter will open a window and then close it right away.

Seq_insert is a console program, meaning it should run from the command prompt. In
Windows XP, you can reach the command prompt by doing Start Menu -> Run - "cmd". Afterwards,
just go the mml2m64 directory you unpacked mml2m64 and run insert_seq from there.

5 - The Sequence Inserter won't save the music in the ROM.

Most likely, you have run out of space. Try running m64seq_clean.exe (just drag and drop
your ROM there) to erase all the custom sequences. Remember the inserter only works with an
extended Super Mario 64 ROM. Make sure you typed the arguments (sequence file, ROM file and
sequence to replace) in the right order.

6 - I produced a .zseq file. How do I insert it in the Zelda 64 Master Quest Debug ROM?

There isn't any program to insert it for you, so you'll have to replace an existing
sequence manually. The sequence files (all enclosed within the 'audioseq' file) start at 0x44DF0, and the pointer table is located at 0xBCC6A0. The first 0x10 bytes is just the
sequence count (a halfworld), which should be 0x6E, followed by seq_count * 0x10 bytes of
entries (see struct below).

Here you can find a list of all sequences in the Debug ROM:
http://web.archive.org/web/20080213144845/http://zso.krahs-emag.com/codes/codeinfo.html#musicmod

********************************************************************************************
DO NOT ASK ME TO INSERT ZELDA 64 MUSIC FOR YOU. DO NOT ASK ME WHERE TO DOWNLOAD A DEBUG ROM.********************************************************************************************

This program corrects tinymm's (MIDI->MML converter) octave raisers/lowerers
output. It's not required if you are using another program to generate the MML.
A later version shall fix also the channel headers.

Usage: fix_mml [mml_file] (or just drag and drop a .mml file into mml_fix)