AddmusicK

AddmusicK (AMK) replaces Super Mario World's music and sound effects. It compiles songs written in its MML dialect, bundles them with BRR samples and its own SPC700 sound engine, and inserts all of it into the ROM with Asar, together with a SNES-side patch that uploads songs to the sound CPU. This page describes the HertzDevil fork of AMK 1.0.5. Later releases (1.0.9, 1.0.10, 1.1) add hex commands and options that are not covered here.

The facts come from two places, and each section says which. Some come from AMK's own documentation, restated in plain words: doc/readme_files/ holds syntax_reference.html, hex_command_reference.html, general_basic_use.html, general_advanced_use.html and sound_effects.html. The rest were measured by running AMK as a black box. That means compiling songs with it, then reading the bytes, the ARAM image and the .spc it produces, and running its engine in an SPC700 interpreter while logging every DSP register write. None of it was read from AMK's source. AMK's repository declares no licence (GitHub reports none, and the readme credits only Asar), so no code of AMK's is reproduced here.

A clean-room MIT reimplementation of AMK's compiler and engine exists in Pipe Dream.

Files and folders

File or folderWhat it holds
music/Songs, as .txt or .mml MML files
samples/BRR samples, and .bnk sample banks
1DF9/, 1DFC/Sound-effect sources, one file per effect
Addmusic_list.txtThe song list: song numbers, global and local
Addmusic_sample groups.txtNamed sample groups (#default, #optimized, user groups)
Addmusic_sound effects.txtThe 1DF9 and 1DFC effect lists
Addmusic_options.txtCommand-line arguments read from a file instead
test/1DF9/, test/1DFC/93 small shipped effect sources
test/music/16 shipped test songs. ww, ww2 and ww3 name a sample the folder lacks, so they do not compile as shipped

AMK prefers asar.dll over asar.exe, and expects either in its own program directory. Before writing, it backs the ROM up as ROMNAME~.

The Lunar Magic handoff: <ROMNAME>.msc

AMK writes <ROMNAME>.msc beside the ROM. Lunar Magic reads it to list song names in its music pickers. The file has one line per song for each of its 0/1 variants. Any tool that manages music on an LM-edited ROM has to read or write this file.

What AMK puts in the ROM

From the documentation:

Measured:

The SMW side: ports and RAM

SMW talks to the sound CPU through four RAM bytes, each mirrored to an APU port.

RAMRole under AMK
$1DF9Sound-effect bank 1. The effect plays on SPC channel 6
$1DFAEcho control for sound effects. #$06 turns sound-effect echo on, and #$05 turns it off. It is off by default
$1DFBSong change. A song not in ARAM is uploaded first
$1DFCSound-effect bank 2. The effect plays on SPC channel 7

According to AMK's docs, the only difference between the two effect banks is the SPC channel they use (6 or 7).

Behaviour, measured against AMK and against SMW's own engine:

Songs, samples and sound effects

All from the documentation.

Global and local songs

Addmusic_list.txt divides songs into global and local. Global songs never transfer: they stay in ARAM from power-on and use that space permanently. Local songs are uploaded on a song change, along with their samples, unless whoever writes $1DFB keeps the previous sample set.

Samples

Measured: a group's sample that is not marked important, and that nothing in the song names (an instrument definition or use, or $F3), is not uploaded with that song. Important samples stay in ARAM from power-on.

Sound effects

What the shipped effects show:

The MML language

From the documentation.

Conversion of older formats

How MML compiles

Measured against AMK's output. AMK's documentation describes none of this.

ARAM: the binding constraint

ARAM (64 KB) limits everything in AMK. Its regions are the engine, the global songs, the sample directory (aligned to $100), the samples, the sound effects, the local song and the echo buffer.

The engine, as measured

These findings come from running AMK's own engine in an SPC700 interpreter and logging every DSP register write. The interpreter's instruction and timer timing match blargg's snes_spc (libgme) cycle for cycle.

Where AMK's engine misbehaves

Timing

Notes

Volume

Effects

Echo

Not yet measured

These commands have no measured behaviour here:

Quirks