Workflow

Workflow — from Windows to the MSX

Current extensions and limits

Updated 2026-10-03: editor 60,000 normalized bytes; MUC input 65,536 bytes; total music DATA 122,880 bytes; one page stream 59,546 bytes. Ordinary songs retain MUB8; extensions/large output use muPb 0100. Read mucomDotNET extensions, limits and specs, and build availability, CPU performance and verification. CPU auto-acceleration and /N are in the separate CPU validation build, not the existing MucoMSX_261003.zip.

🇰🇷 한국어 · 🇯🇵 日本語 · ⬅ Home

This page follows one song from an empty folder to a .MUB playing on real hardware.

---

The shape of it

flowchart LR
  subgraph PC["PC / Windows — MUCOM88 Windows"]
    direction TB
    V["FM tone editor"]
    P["PCM bank tool"]
    M["MML editor"]
  end
  subgraph MSX["MSX"]
    direction TB
    E["MUCEDIT<br>edit the MML"]
    C["MUCPLAY<br>compile · play · export MUB / VGM"]
    B["MUBPLAY<br>play the finished MUB"]
    E --> C --> B
  end
  V -- "VOICE.DAT" --> E
  P -- "PCM .BIN" --> E
  M -- "SONG.MUC" --> E

Loading

You do not have to start on the PC. If you only ever write SSG and FM parts using voices that already exist in a library you were given, you can live entirely on the MSX. The PC becomes necessary the moment you want a voice nobody has made yet, or a sample of your own.

---

Step 1 — Set up a folder per song

Keep one folder per song, on both machines. Everything the song needs lives beside it:

SONG/
  SONG.MUC          the music
  VOICE.DAT         FM voices, if the song uses an external library
  MUCOMPCM.BIN      PCM bank, if the song uses channel K

This is not fussiness. On the MSX, relative filenames in #voice and #pcm are resolved against the current working directory, not against wherever the .MUC happens to sit. Compile from another directory and you can silently pick up a different album's VOICE.DAT — the song compiles, and sounds wrong.

Two albums with a same-named VOICE.DAT is completely normal. Keep them apart.

---

Step 2 — Design the FM voices on the PC

MUCOM88 Windows ships an FM tone editor (FmToneEditor.exe). The part that makes it worth using is that it talks to the player: with the tone-editor link enabled from the menu, your edits are heard in the currently playing MML, so you adjust an operator and hear the result immediately.

Two ways to get a voice out of it:

• Into a library file — save to the voice data file (voice.dat by convention), and reference it from the song's header with #voice.
• Into the MML itself — copy in the editor with Ctrl+C, paste into the MML with Ctrl+V, and you get an @n:{ ... } definition block inline in the source.

Inline is often the better choice for MUCOMSX. A pasted definition travels with the .MUC — one file instead of two, nothing to mismatch. An FM Voices page will cover the formats and when a library still wins; until it is up, see the upstream voice data and tone editor page.

---

Step 3 — Build the PCM bank on the PC

Channel K plays ADPCM samples out of a single bank file. You build that bank once, on the PC, from ordinary audio:

1. Prepare your samples as 16-bit mono WAV files.
2. Write a plain text list file — pcmlist.txt is the usual name — naming the files to include, in order. The audio files must sit in the same folder as the list.
3. In MUCOM88 Windows: F1 → Tool → Create PCM data file.

Out comes one bank, mucompcm.bin by default, or any name you like. Reference it from the song header with #pcm.

Know what the conversion does to your audio. Samples are resampled to 16 kHz during ADPCM conversion. Pitch-critical material and anything with a lot of high end will change character. Audition the converted bank before you build a whole song around it — and keep your original WAVs, because you will want to rebuild.

Existing PC-8801 ADPCM binaries can go into the list too, alongside WAV files.

---

Step 4 — Move the files across

However you get files onto the MSX — SD card, DirAsDisk, floppy image — this is the step that quietly breaks songs. Three rules:

Use 8.3 names, and use them everywhere

Name the files short from the start: SONG.MUC, VOICE.DAT, PCM01.BIN. The compiler reads companion files through DOS FCB paths, which truncate. A header that says

#voice shinobivoice.dat

needs the file on the MSX to be named SHINOBIV.DAT — the first eight characters. It does not find the usual SHINOB~1.DAT short-name alias that Windows would generate. Two different long names can truncate to the same short name, which is its own kind of confusing.

Rename on the PC, before you copy, and fix the tag to match.

Keep the tags in the header

#voice and #pcm are only honoured in the run of header lines at the very top of the file. Put a comment or a blank-ish line above them and they are read as tags outside the header and ignored — with a warning, but the song still compiles, just without your voices.

Don't let the transfer touch the text

Line endings and character encoding both matter if you plan to compare a build byte-for-byte later. Transfer as binary where you can.

---

Step 5 — Work on the MSX

From here the MSX is self-sufficient. In the song's folder:

MUCEDIT SONG.MUC

Then, inside the editor: F1 2 to compile → read the result → F1 3 to play. Ctrl+S saves when you like what you hear.

You do not need to save before compiling — the editor compiles the buffer in memory. But saving and compiling are different actions, and so is playing; see the MUCEdit manual if that distinction is new.

For a whole album at once, MUC2MUB converts one .MUC per run from a DOS batch file, with no session and no playback — and it accepts sources up to 64 KiB, where the editor holds up to 60,000 bytes after newline normalization.

---

Step 6 — Iterating

What you have to redo depends on what you changed:

You changed	Redo
Notes, tempo, expression in the MML	Compile, play
An inline @n:{...} voice	Compile, play — it lives in the .MUC
A voice in the library file	Re-copy VOICE.DAT to the MSX, then compile
A sample in the PCM bank	Rebuild the bank on the PC, re-copy it, then compile
Nothing — you just reopened the file	Compile before playing; Play uses the last compile, not the current text

The last row catches everyone once. Edit, press play, hear the old version, conclude the editor is broken. It isn't — nothing was compiled in between.

---

Common traps, in one place

Symptom	Usually
FM parts sound wrong, no error	Wrong VOICE.DAT picked up — check the working directory, and the 8.3 name
Warning: PCM file not found	The #pcm name doesn't match the real DOS filename, or the tag is outside the header
Song plays but a part is missing	That channel's line is malformed — check the channel letter is uppercase, at column 1, followed by a space or tab
A .MUB exports but has no PCM	The missing-PCM warning was ignored — fix it and export again
Edits don't take effect	Compiled? And if you edited on the PC, did you re-copy the .MUC?

A Troubleshooting page will go through these properly; until it is up, the MUCEdit manual carries the full error and warning reference.