mmlx-lsp
Write MML. Hear it come alive—instantly.
MML (Music Macro Language) support for VS Code and Helix.
Currently supports the MDX (MXDRV) dialect and .mml files.
Features
- Syntax highlighting for notes, commands, track labels, voice and macro definitions, and comments.
- Error diagnostics for parsing, compilation, and playback checks.
- Voice-definition formatting with aligned YM2151 operator parameters.
- Command and macro completion with argument snippets, FM voice and macro-definition guides, and macro expansions.
- Macro references displayed on definitions and navigable in the editor.
- Parameter hints while entering command arguments.
- Japanese and English command descriptions and parameter hints.
- FM voice outlines labeled with the voice number and adjacent semicolon name, when present.
- Built-in VS Code build tasks for MML to MDX and MML/MDX to VGM.
- FM Voice panel with cursor-linked operator envelopes and two-way parameter editing.
- MML playback with editor highlighting that follows the playback position.
- Playback timeline for moving the playhead and navigating the MML editor cursor.
- Real-chip playback with NanoDrive8—bring your MML to life on authentic hardware.
Usage
This extension needs a trusted workspace to work. If VS Code is in Restricted Mode,
select "Manage Workspace Trust" and trust this folder. Learn more about Workspace Trust.
The extension automatically associates .mml files with MML(mdx).
If the file opens in another language mode, click the language mode in the
status bar and select MML(mdx), or add this to your VS Code settings:
{
"files.associations": {
"*.mml": "mmlx"
}
}
mmlx Panel
Dedicated bottom panel opened with mmlx: Show mmlx Panel.
Get Started
- Get Started opens A Little Prelude, an editable sample
.mml in a new, unsaved editor. Explore its melody, harmonies, and bass, then make it your own.
FM Voice
- FM Voice editing for parameters, algorithms, and envelopes directly in the source by placing the cursor in an
@ definition.
- Operator parameter copy/paste: Right-click an operator envelope to copy its parameters, then paste them to all other operators or an individual operator.
- Emulation output: Select Emulation under Keyboard > Output to play up to eight notes with the on-screen keyboard or MIDI-IN.
- NanoDrive8 output: Connect NanoDrive8 in Settings, then select NanoDrive8 and connect under Keyboard > Output.
- Chip State MML: Test short MML phrases with the displayed voice using Enter or Play/Stop.
Input is saved; the default is
MH0,200,64,0,5,0,1 ; PMS LFO. Hardware LFO, pan and operator settings remain for keyboard notes; software LFOs apply only during MML playback.
- Selection playback: Play a selected
.mml passage with the displayed voice and highlight notes and rests during playback. Tempo, octave, default length, volume, gate, and pan state carry over from earlier MML or previously played selections.
- Reset sound chip: Use the icon left of the Keyboard Output connection button to clear chip and inherited MML state, then restore the displayed voice without disconnecting. Subsequent selection playback rebuilds MML state from the played commands.
Available on Emulation and NanoDrive8 when connected and hardware Playback is idle.
- MIDI-IN connection and note reception, with pressed-key feedback in the FM Voice keyboard.
- Pitch bend: Drag the left-hand wheel with a mouse or touch, or hold arrow keys while focused. It returns to center when released. Both outputs use a fixed +/-2-semitone range; MIDI RPN range changes are not supported.
Playback
- Outputs: Emulation mixes YM2151 FM and OKIM6258 ADPCM with clock, divider and pan control. Both outputs use the configured PDX file or discover it beside the MML, and apply the ADPCM processing setting. NanoDrive8 uses FM bursts for FM-only songs and ADPCM streaming for songs with PCM notes.
- Playback: Plays the active MML, including unsaved edits. Switching files stops playback without affecting FM Voice or MIDI-IN.
- Editor playback highlights: Follow FM and PCM notes and rests on both outputs, including loops and muted tracks, without moving the cursor or selection. Pause holds highlights; Stop, completion or source edits clear them. Tracking failures show a warning without stopping audio.
- Controls: Play, stop and volume on both outputs; pause and elapsed time on Emulation only. Both support optional MML loop points.
- Channel keyboards: Eight 88-key FM keyboards (A0-C8) show playback activity on both outputs, including muted channels. Narrow panels keep active keys visible. Pause holds the display; Stop clears it. ADPCM is not displayed.
- Channel mute and solo: MUTE silences individual FM channels or mixed ADPCM on both outputs. SOLO plays only the selected channels, supports multiple selections and overrides MUTE without changing its saved selections. Both selections persist across stops, restarts and output changes.
- NanoDrive8 volume: Controls the device's main FM/PCM output, including keyboard audition. Requires firmware supporting
SET_OUTPUT_VOLUME; older firmware may reject volume changes without stopping playback.
- Play from cursor: Emulation starts at the current command or the next command on the same line. Repeats start at the first occurrence; seeking may take a moment.
- NanoDrive8 diagnostics: Output > mmlx NanoDrive8 logs playback failures, engine timing, buffer depth and serial status to help diagnose underruns. No MML or PDX contents are logged.
Utilities
- Create PDX JSON: Open an example manifest for mapping WAV samples to PDX banks and voice slots.
- Build PDX: Convert the saved manifest and its WAV files into a PDX sample bank.
- Build MDX: Build the active MML file using the selected output format: MDX, VGM, or both.
Settings
- Connections:
[Connected] and the badge show active connections. Hiding the panel stops on-screen notes, not connections. Disconnect manually; connections are not restored after a reload.
Build
Open an MML file in a trusted workspace and run mmlx: Build from the
command palette, or select it via Tasks: Run Build Task (Ctrl+Shift+B,
or Cmd+Shift+B on macOS). By default, it creates both MDX and VGM files in
the workspace folder's build/ directory.
No Rust or external CLI is required.
Use mmlx: Build MDX or mmlx: Build VGM to build one format.
These commands override the configured output format. MDX input is converted to VGM only.
Errors appear in the Problems view and task terminal. Ctrl-click an error
location (Cmd-click on macOS, depending on your terminal settings) to jump to
the source. Stop the task to cancel.
Change the options below in VS Code settings or in Utilities > MDX Build in the
mmlx panel. The panel saves changes to the
workspace folder's .vscode/settings.json; they apply to the next build without
restarting the language server.
| Setting |
Purpose |
mmlx.build.format |
Output formats used by mmlx: Build: both, mdx, or vgm. |
mmlx.build.onSave |
Automatically build MML when saved in a trusted workspace. |
mmlx.build.outputDirectory |
Output directory: a relative workspace path or an absolute path. |
mmlx.build.pdx |
PDX file path for VGM builds and NanoDrive8 Playback, relative to the workspace folder or absolute. When empty, look for the referenced PDX beside the input, accepting case-insensitive filenames. |
mmlx.build.adpcmMode |
ADPCM processing for VGM builds and NanoDrive8 Playback: through, resample (default), or lpf. |
mmlx.build.loopCount |
0 preserves native VGM loop points; positive values produce finite playback without a loop point. |
mmlx.build.maxTicks |
Positive playback tick limit for VGM conversion. |
MDX output checks parsing and compilation without loading PDX samples.
VGM conversion requires any referenced PDX and reports playback errors or
tick-limit failures before saving the output. When building both formats,
neither output is saved until both conversions succeed. Loop points for per-track
MDX F1 loops are estimates.
Other Settings
mmlx.dialect: mdx is the default and currently the only supported dialect.
mmlx.language: auto follows the editor language, falling back to Japanese.
Use ja or en to select the language of completion descriptions and parameter hints.
mmlx.serial.connection: empty by default. Use Settings > Connection > NanoDrive8
in the mmlx panel to select a serial port such as /dev/ttyUSB0 or COM3.
Selection is saved to workspace settings but does not connect automatically. Put NanoDrive8
in serial mode and click Connect (firmware 1.0, including betas). Once connected,
NanoDrive8 is available for Keyboard Output and Playback. In remote workspaces, the list
shows ports on the remote extension host.
mmlx.midi.input: empty by default. Select a port under Settings > Connection > MIDI-IN
and use the connection button to connect or disconnect. Incoming notes highlight
the FM Voice keyboard. The selected port is saved; connections are not restored
automatically.
After changing the dialect or language, run mmlx: Restart Language Server from the
command palette. Diagnostic messages are not translated.
Manual Installation in VS Code
For manual installation from a VSIX file, use desktop VS Code 1.100 or later
on Windows, macOS, or Linux. Node.js and Rust are not required.
- Download the
.vsix file from the latest GitHub release.
- In the Extensions view, open the
... menu and select Install from VSIX....
- Open a
.mml file.
VS Code automatically installs the required ms-vscode.wasm-wasi-core extension.
If it cannot be downloaded automatically, such as in an offline environment,
install that dependency separately.
Build From Source
Requires Rust, Node.js, curl, and tar. Example for Linux x86_64:
git clone https://github.com/h1romas4/mmlx-lsp.git
cd mmlx-lsp
curl --fail --location --retry 3 -o wasi-sdk.tar.gz https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-33/wasi-sdk-33.0-x86_64-linux.tar.gz
echo "0ba8b5bfaeb2adf3f29bab5841d76cf5318ab8e1642ea195f88baba1abd47bce wasi-sdk.tar.gz" | sha256sum --check
mkdir -p toolchains/wasi-sdk/build/install
tar -xzf wasi-sdk.tar.gz -C toolchains/wasi-sdk/build/install --strip-components=1
rustup target add wasm32-wasip1-threads wasm32-wasip1
npm ci
npx --no-install vsce package --out mmlx-lsp.vsix
On Windows x64, replace the SDK download and extraction commands with:
Invoke-WebRequest https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-33/wasi-sdk-33.0-x86_64-windows.tar.gz -OutFile wasi-sdk.tar.gz
New-Item -ItemType Directory -Force toolchains/wasi-sdk/build/install | Out-Null
tar -xzf wasi-sdk.tar.gz -C toolchains/wasi-sdk/build/install --strip-components=1
For other platforms, use the matching SDK 33 release archive.
The output is mmlx-lsp/mmlx-lsp.vsix. No SDK environment variable is needed.
Install in Helix
Use the native installation guide for the file installation
commands. The same guide is included in each native archive.
- Download and extract the native archive for your OS and architecture from
the latest GitHub release:
macos-x64, macos-arm64, windows-x64, or linux-x64.
- Install the included language server, Tree-sitter library, and highlight queries
using the guide above.
- Add the configuration below to your Helix configuration, or merge the included
language configuration with your existing entries.
- Restart Helix and run
hx --health mmlx-mdx to check the installation.
Node.js, Rust, and a C compiler are not required.
Add or update these entries in your Helix languages.toml:
[language-server.mmlx]
command = "mmlx-lsp-server"
config = { dialect = "mdx", language = "ja" }
[[language]]
name = "mmlx-mdx"
scope = "source.mmlx.mdx"
file-types = ["mml"]
comment-token = ";"
language-servers = ["mmlx"]
grammar = "mmlx-mdx"
Ensure the server is on your PATH, or replace command with its absolute path
(mmlx-lsp-server.exe on Windows). Set language = "en" for English completion
and hints. The prebuilt parser does not need a [[grammar]] source entry.
Linux archives are built on Ubuntu 26.04 and require a compatible glibc-based
system. Older distributions may not run these binaries. Native binaries are
not code-signed or notarized.
Dependencies
License
BSD-3-Clause
The audio backend includes third-party components listed in THIRD_PARTY_NOTICES.md.