Solar Soundtrack
A browser-based AddmusicK 1.0.11 music editor. It has live music previewing capabilities thanks to the in-browser SPC engine.
Installing AddmusicK is not needed, nor is a ROM. The tool is a static site and works entirely client-side in any modern-day browser.
Try it → ·
Porter's manual → — what it does, and every control in it.
Why this exists
AddmusicK is the custom music tool that SMW Central uses. Porting music with Addmusic has always
been one of my favourite things to do in this hobby. What was never fun was the loop around it:
to actually hear a port, you had to insert it into the ROM, open an emulator, and go to the level
that plays it. When you change around notes, you have to repeat this process. Nowadays, AddmusicK
has a "porter mode" that makes this process easier, but still requires switching windows.
So the idea was to make a single tool for everything custom music-related. Write it, hear
it, edit it, even export it, without leaving this one window. I hope to make custom music
more accessible to people, this way.
AddmusicK, in my opinion, also has room to grow past SMW: the same engine has potential for other
games, and even for homebrew. A huge library of music is available at SMW Central.
Features
- An AddmusicK-compatible MML compiler, ported from C++ to TypeScript. It reads
these target markers:
#amk 1, #amk 2, #amk 4, #am4, #amm. (#amk 3 is unsupported, the same as in AddmusicK itself.)
- SPC700 emulation using Blargg's
snes_spc as a WebAssembly module.
- Compile as you type, with a Hot Reload mode that reloads the song at the position it
was already playing. You can keep editing and the music never stops.
- Seek, loop and volume, and per-channel mute and solo controls.
- A layout in FL Studio's mould — transport and ARAM meter in the top bar, an inspector-first
sidebar, a status bar, and a tablet drawer; the theme picker recolours any of it.
- A sample browser where you can import
.brr files or whole .bnk banks, see what each sample
costs in ARAM, and mark them as important for use in global songs or sound effects.
- An ARAM budget that tells you how your work fits within the ARAM.
- Error reporting that mentions the erroneous lines with a proper error message.
- A command inspector that explains whatever the cursor is sitting on:
t54 as a tempo in BPM,
@2 as the sample it actually plays, $F1 as a delay in milliseconds and a buffer size in KiB,
and any other hex command as its name with its arguments decoded.
- An echo FIR filter designer. The eight coefficients of
$F5 are the least readable thing in
the language, so put the cursor on one and you get a frequency-response plot, named presets
(including Super Mario World's own filter, verbatim), a dark-to-bright tone control, and
FIRcon-style draw-a-curve-and-fit. It plots the echo tail repeat by repeat, since the filter is
inside the feedback loop and each pass is filtered again; it shades the region below ~2 kHz where
eight taps at 32 kHz have no real say; and it warns when the feedback and the filter together
make an echo that builds up instead of dying away. Edits go straight back into the MML, so with
Hot Reload on you hear the change on the running song.
- Syntax highlighting, and a live playhead that follows the driver rather than estimating —
so the highlighted note is the note you are hearing, in every channel.
- A hex dump of the compiled song data, just because.
- Export a finished
.spc, or the raw song-data .bin.
- Your draft and your sample library are kept locally, so closing the tab does not lose
your work.
- A changelog in the top bar, listing what each day of work added. It is a plain hand-edited
list in
web/src/app/changelog/changelog-data.ts — add a block at the top when you add a feature.
See the GitHub Issues for a list of
ideas, planned features and known issues.
Running it locally
An npm workspace: four framework-free packages and the Angular editor that imports them. Every
command runs from the repository root.
npm install
npm start # dev server on http://localhost:4200/
Node 24 is what CI uses.
npm scripts
| Command | What it does |
|---|
npm start | Dev server on http://localhost:4200/. |
npm run build | Production build, output in web/dist/. |
npm run watch | Dev-configuration build with --watch, no server. |
npm run lint | ESLint over every workspace. |
npm run format | Prettier over the workspace. |
npm run check | The merge gate: formatting, three typechecks, fourteen harnesses. |
npm run check is what CI runs. The fourteen harnesses pin the compiler, the scanner, SPC assembly,
the headless MML → SPC → PCM chain, the worklet, BRR decoding, the echo FIR and the envelope maths
against known-good byte output. scripts/README.md says what each one actually proves.
Three things run automatically before the commands above (via pre* npm hooks), so you never need
to invoke them yourself: the audio worklet is bundled with esbuild, the SPC package's driver and
emulator assets are mirrored into web/public/, and the current commit SHA is written to a
gitignored file that powers the top bar's commit link. The SHA is captured once when the dev server
starts, so it goes stale if you commit while npm start keeps running — restart to refresh it.
How it works
The premise the whole project rests on is that producing a playable SPC file is mostly
data assembly. The driver, the SPC header and the sample set are all static bytes,
already supplied by AddmusicK. The song data is the only thing that has to be compiled
at runtime.
Four packages, and an editor that imports them. Each has a README.md of its own.
| Path | What lives there |
|---|
packages/core/ | Types, AddmusicK's constant tables, hex formatting |
packages/mml-compiler/ | The MML compiler — preprocessor, parser, linker |
packages/mml-tokens/ | The scanner behind highlighting and the command inspector |
packages/spc/ | SPC assembly, BRR, the echo FIR, the emulator host and the worklet |
web/ | The Angular editor |
Nothing in packages/ touches a framework or the DOM beyond three fetch calls, which is what lets
the same modules run in Node under the test harnesses, on the main thread, and inside an audio
worklet.
On testing: npm run check runs fourteen byte-level harnesses — see scripts/README.md. Separately,
scripts/Compare-Spc.ps1 and Compare-SongBin.ps1 diff this compiler's output against a native
AddmusicK build, byte for byte.
Contributing
Contributions are very welcome, but please read this part first, because I would rather
be honest than get you halfway into a pull request before you find out.
Effectively all of the code in this repository was written by AI. It works, it is
tested, and I have read and steered it to the best of my abilities, but it has not had the kind of human
touch that a codebase deserves before people build on it. Expect inconsistencies, over-engineering in some
places and cut corners in others, and expect to spend longer than usual working out why something is
the way it is.
For now, I'd rather you test the application functionally, and report bugs, submit ideas or feature requests,
than try to contribute code, until the codebase is more... maintainable. I will be working on that, but it is a
slow process.
Practical bits: npm run check should pass before you open a PR. If you are planning
something large, please talk to me first, partly so we do not duplicate work, and partly
because there are certain directions I want to take the project to.
Credits
This project stands on other people's work:
- Blargg -
snes_spc, the SPC700 emulator core that makes any of this audible.
- Telinc1 and SMW Central - the
WebAssembly SPC player built on
it, which this project uses.
- The AddmusicK maintainers from its changelog: Kipernal, KungFuFurby, KevinM, Medic, HertzDevil, Atari 2.0, nyanpasu64, JUMP Team, SimFan96, Anas, HuFlungDu, lx5, Pinci, 6646, Akaginite, Aikku, Sinc-X, Lui, Vitor, Barrels O' Fun,
License
MIT - see LICENSE.
The bundled third-party material keeps its own terms. The emulator core is LGPL 2.1, and
the driver bundle under packages/spc/assets/driver/ is AddmusicK output whose #default samples
originate from Super Mario World; LICENSE spells both out.
Contact
I am Ersanio - GitHub · SMW Central.
The best way to reach me is a Discord DM, I am in the SnesLab and SMW Central Discord
servers. Failing that, a private message on SMW Central works too.
I might also request a project channel on the SnesLab server, if there is enough interest.
