miditrack Manual

Opening Files from Finder

miditrack.app can open .miditrack, .mid, .midi, .nsf, .nsfe, .spc, .spc2, .vgm, .vgz, and .zip directly from Finder or by dropping files on its Dock icon. Opening a .miditrack project restores it; a single MIDI file opens as MIDI; the other formats open as source files. When a current session would be replaced, the app asks for confirmation.

miditrack is the default handler for .miditrack projects. For other formats it is an alternate handler so it does not replace your existing player or DAW. In Finder, choose Get Info → Open with → miditrack → Change All if you want to make it the default for one of those formats. Existing installations created by install.sh are intentionally not overwritten; move the old app aside, then reinstall to refresh Finder's file associations.

File Selection

Click Open in the header to reach this dialog — it also opens automatically before any file is loaded.

Upload area — Drag a file onto the dashed area, or click to open a file picker. Accepted: .mid, .midi, .nsf, .nsfe, .spc, .spc2, .vgm, .vgz, .zip, .m3u. Drop multiple source files, a ZIP rip pack, or a source file together with an .m3u playlist at once. ZIP uploads allow up to 200 files and 512 MiB extracted. ZIPs can contain .spc and .spc2; a ZIP containing only unsupported files (including .rsn) reports that no supported source file was found.

File and song picker — When the upload contains multiple convertible sources a file dropdown appears. If the format provides multiple songs (NSF, SPC rip packs) a song picker appears below it.

Conversion settings — Appear after format detection and vary by format:

• VGM/VGZ — Loop count or duration (mutually exclusive). Original game sound by default pre-selects noise/DAC/rhythm tracks for chip rendering; any track can be changed after conversion. OPN Ch3 Special to GM drums maps YM2203/YM2608/YM2612 Ch3 Special operators to kick, snare, hi-hat, cymbal, and tom.
• NSF/NSFE — Duration in seconds and optional PAL timing.
• SPC/SPC2 — Loop count.

Click Convert to MIDI to start. The dialog also offers Open project and Save project. After conversion it closes and the main screen below shows the result.

Main Screen

The track panel and the piano roll stay visible side-by-side at all times. Reopen the file dialog above from the header's Open button whenever you want to load or convert another file.

Track panel (left) — Each row shows a colour swatch, track name, MIDI channel (CH), source toggle, instrument selector, mute, solo, and volume slider. Click Track ▲ to sort alphabetically; click again to reverse. MIDI channel 10 (percussion) and multi-channel tracks cannot have their instrument changed.

SF / Original toggle — SF plays the track through the selected General MIDI SoundFont and honours instrument assignments. Original uses a game-derived SoundFont for SPC, or hardware/chip rendering for NSF and VGM. Volume is still adjustable in Original mode. VGM rows sharing a physical hardware channel switch together; ambiguous shared channels are not set to Original automatically. Cmd-click (Ctrl-click on Windows/Linux) applies the same choice to every other track that offers the same option.

Instrument selector — Choose any GM instrument. The star icon saves it as a favourite for quick access. Cmd-click (Ctrl-click) applies that selector's current value to every other editable track (a track left on "Keep unchanged" is unaffected).

Mute / Solo — Both affect the rendered preview. Cmd-click (Ctrl-click) the mute button to bring every other track to the same mute state (muted or unmuted) at once. Unmuting restores each track's own previously remembered volume rather than a single shared value.

Ensemble presets — Save the current combination of instruments and source settings as a named preset. While a preset is active the instrument column switches to a role selector. Presets are stored locally in the browser.

SoundFont — Select a .sf2/.sf3 from those found in the standard search directories. Fast (22.05 kHz) renders quickly for auditioning; Quality (44.1 kHz) matches the WAV download.

Transport (right, top) — ◀◀ and ▶▶ step by 5 s per click, ⏮ returns to the start, and ▶/⏸ plays or pauses. Keyboard shortcuts are also available: Space toggles play/pause; Left/Right arrows seek ±1 s; Shift + Left/Right arrows seek ±5 s; Page Up/Page Down seek ±10 s; Home jumps to the start; End jumps to the end; and Cmd+← jumps to the start. The timer shows the current position over the total duration.

Speed — Playback rate from 0.1× to 10×. Applies to all subsequent renders and the WAV download.

Pitch — Shifts by −24 to +24 semitones. Percussion is never transposed; notes that fall outside MIDI range 0–127 are omitted.

Volume — Master level for the session.

Piano roll (right) — Displays all tracks as coloured note bars on a vertical keyboard. Scroll to navigate; pinch or use the scroll wheel to zoom. Click to seek.

Pitch bend lane — Shows pitch bend data for each track below the note area.

Rendering starts automatically after edits and completed renders are cached for the session. A short delay after the last change updates the preview. If you begin playback while a fresh render is still needed, miditrack can first play a short segment around the current position, then crossfade to the exact full-length WAV when it is ready. Original chip-audio tracks are prepared in the background after conversion so they can join that short preview once ready; the spinner remains visible while the full WAV is still being finished.

Download MIDI / WAV (bottom) — Download MIDI saves the edited file with current instrument assignments. Download WAV produces a 44.1 kHz stereo WAV using the current track settings, speed, and pitch. Edit the filename field before downloading to set the base name.

Generate variations in bulk — Enter comma-separated speed multipliers and semitone values, then click Download variations as ZIP. Check Include MIDI in ZIP to add the corresponding MIDI file for each combination. Accepts up to 6 speeds, 8 transposes, and 15 total combinations. The audition speed and pitch settings are not changed.

Export per track — Download per track as ZIP produces one WAV per audible track. Check Combine original-sound tracks to merge all original-sound channels into one file, avoiding a full re-render per hardware channel. File names include _midi or _orig to indicate the render source.

Changing a SoundFont, a track setting, or the filename invalidates previously generated variation and per-track ZIPs; regenerate them after the change.

Preferences

Open the preferences panel from the header's gear icon. Changes take effect immediately and are preserved across restarts. Fields are grouped into Display settings (appearance only) and Behaviour settings (how rendering runs).

Display settings

Appearance sets the colour scheme: follow the system setting, light, or dark.

Display language switches the Web UI between Japanese and English, or follows the system setting. Changing it reloads the page. Error messages caused by an environment problem (a missing binary, a render timeout) stay in Japanese regardless of this setting. On the app version, the native menu bar picks up the language on the next launch, not immediately.

Piano roll

• *Round note corners*, *Add note outline*, *Show grid lines*, *Show keyboard* — toggle each element individually.
• *Height* — Sets the piano roll height. On the app version the roll always fills the window height regardless of this setting.
• *Background colour* / *Grid line colour* — Pick a custom colour or reset to the theme default.
• *Track colour scheme* — Controls the saturation of the per-track note colours.
• *Vertical grid divisions* — Number of subdivisions per beat.

Track list — *Hide tracks with zero notes* removes empty tracks from the list.

Behaviour settings

Concurrent render jobs controls how many render jobs (FluidSynth track splits, chip/hardware channels, and bulk-variation combinations) run at once. Auto picks a conservative value from the machine's CPU count; choose a fixed number (1/2/4/8) to override it.

Limits and behaviour

• MIDI channel 10 is not available for instrument remapping, and multi-channel tracks (including format-0 MIDI) are not editable.
• Auditioning renders then plays audio; it is not a live software synthesizer. Completed renders are cached for the current session.
• .m3u title matching is best-effort. A stale or mismatched playlist leaves song titles unchanged instead of failing.

Command-line options

Run it directly from the app bundle, or create a miditrack command once:

ln -s ~/Applications/miditrack.app/Contents/Resources/project/miditrack/miditrack.sh /opt/homebrew/bin/miditrack

miditrack [MIDI_FILE] [--soundfont FILE] [--port PORT] [--no-token] [--no-browser]

Option	Description
MIDI_FILE	Optional .mid/.midi file to preload. Upload source files in the browser.
-s, --soundfont FILE	Default SoundFont at startup. The browser can replace it at any time.
-p, --port PORT	Fixed port for the Web UI. Omit it (or pass 0) to pick a free port automatically on every launch.
--no-token	Disable launch-token authentication. By default a fresh token is issued on every launch and the browser strips it from the URL, so a bookmarked link stops working the next time you start miditrack. Combined with a fixed --port, this lets you bookmark the plain URL and reopen it every time — but it also means any other process on this Mac can reach the Web UI over 127.0.0.1, so only use it in a trusted environment.
--no-browser	Do not open a browser tab automatically.
--version	Show the version and exit.

Saving miditrack as a browser "app"

This is an independent way to run miditrack — it doesn't interact with the Dock app. miditrack can be saved as a PWA (Chrome's "Install app," Safari's "Add to Dock," and similar). A saved app icon always opens http://127.0.0.1:<port>/ with no token, so combine these three options for that workflow:

• --port — pins the port so the app icon opens the same URL every time.
• --no-token — a saved app icon has no way to carry a token in its URL, so this disables token authentication entirely (only use this in a trusted environment).
• --no-browser — skips the automatic browser tab, since opening from the app icon makes it redundant.

miditrack --port 51888 --no-token --no-browser

Start the server with this command, then open it from the saved app icon. If you save it with Safari's "Add to Dock," give it a name other than "miditrack" — Safari places saved apps directly under ~/Applications/, the same folder as the Dock app above.

nsf2midi

nsf2midi song.nsf song.mid
nsf2midi -l song.nsf

See nsf2midi/README.md for MDF instrument definitions, PAL timing, and chip-audio rendering.

spc2midi

spc2midi song.spc song.mid
spc2midi --sf2 song.spc song.mid

See spc2midi/README.md for SoundFont/DLS export and loop handling.

vgm2midi

vgm2midi song.vgz
vgm2midi song.vgz --loops 3

See vgm2midi/README.md for supported chips and advanced options.

midi2wav.sh

./miditrack/midi2wav.sh song.mid
./miditrack/midi2wav.sh -S song.mid
./miditrack/midi2wav.sh -s MySound.sf2 -f song.mid

midi2wav.sh uses FluidSynth's dynamic SoundFont sample loading by default to avoid loading unused samples before a render. Use --no-dynamic-sample-loading only when comparing output with FluidSynth's eager-loading behaviour.