mmlabc-to-smf-rust

Conversion library from Music Macro Language (MML) to Standard MIDI File (SMF)

Overview

This library converts Music Macro Language (MML) strings into Standard MIDI Files. It is written in Rust.

Usage

It is used as a library by cat-play-mml.

Current Status

Frequent breaking changes are being made.

The README is currently under-maintained. More MML commands are actually implemented than described here. The README will be updated later.

If you want to know which MML features are implemented, please refer to tree-sitter-mml/grammar.js first (note that this will also be subject to breaking changes in the future).

Implemented Features ✅

• Basic Note Conversion: cdefgab → Conversion to MIDI notes
• 4-Pass Architecture: Fully implemented
  • Pass 1: Tokenization of MML strings (using tree-sitter parser)
  • Pass 2: Conversion from tokens to AST (Abstract Syntax Tree)
  • Pass 3: Generation of MIDI events from AST
  • Pass 4: Creation of Standard MIDI File from MIDI events
• tree-sitter Integration: Full tree-sitter parser integration for MML syntax analysis
• Channel Functionality: Multi-channel support using semicolons (;)
• JSON Debug Output: Output intermediate results of each pass in JSON format
• CLI: Basic operations via command-line arguments
• Comprehensive Testing: All 35 test cases pass

Demo / How to Run

# Basic scale conversion
cargo run -- "cdefgab"

# Multi-channel
cargo run -- "c;e;g"

# Custom output file
cargo run -- "cde" -o my_song.mid

Future Outlook

Short-term Goals 🚧

• Repository Setup: Establish formatter, linter, and other configurations
• Error Handling: More detailed error messages

Long-term Goals 🎯

• mmlabc Command Implementation: Full mmlabc format support
  • Note length specification (quarter notes, eighth notes, etc.)
  • Octave specification (>, <)
  • Control commands for tempo, volume, etc.
  • Chord functionality expansion
• Performance Optimization: Fast processing of large MML files

References

• For mmlabc, refer to the mml2abc repository.

Features

• 4-Pass Architecture:
  • Pass 1: Parses MML strings into tokens (using tree-sitter parser)
  • Pass 2: Converts tokens into an Abstract Syntax Tree (AST)
  • Pass 3: Generates MIDI events from the AST
  • Pass 4: Creates the Standard MIDI File
• Multi-channel Support: Separate channels for simultaneous playback using semicolons (;)
• JSON Debug Output: Intermediate results of each pass can be saved and inspected in JSON format
• Comprehensive Testing: A total of 35 unit and integration test cases
• Safe Design: Memory safety through Rust’s type system and ownership model

Requirements

• Rust 1.70.0 or higher
• Cargo

Installation

Development Version (Current State)

git clone https://github.com/cat2151/mmlabc-to-smf-rust
cd mmlabc-to-smf-rust
cargo build --release

Direct Execution (via Cargo)

cargo run -- "cdefgab"

Usage

Basic Usage

# Convert basic scale (automatically played by cat-play-mml by default)
cargo run -- "cdefgab"

# Multi-channel (simultaneous playback)
cargo run -- "c;e;g"  # C major chord

# Custom output file
cargo run -- "cde" -o my_song.mid

# Disable auto-playback
cargo run -- "cde" --no-play

Auto-playback Feature

By default, generated MIDI files are automatically played using the cat-play-mml command. This allows for immediate sound confirmation during MML development.

• To disable auto-playback, use the --no-play option.
• If cat-play-mml is not installed, a warning message will be displayed, but the MIDI file will still be generated correctly.

Custom Player Configuration

You can configure a custom MIDI player by creating a mmlabc-to-smf-rust.toml file in the directory where the tool is executed.

Example configuration file:

# mmlabc-to-smf-rust.toml
external_smf_player = "timidity"

Common configurable MIDI players:

• timidity - TiMidity++ MIDI player
• fluidsynth - FluidSynth software synthesizer
• vlc - VLC media player
• cat-play-mml (default)

If the configuration file does not exist, cat-play-mml will be used by default.

Refer to mmlabc-to-smf-rust.toml.example for a sample configuration file.

Output Files

The following files are generated upon execution:

• pass1_tokens.json - Pass 1 token information (for debugging)
• pass2_ast.json - Pass 2 AST information (for debugging)
• pass3_events.json - Pass 3 MIDI event information (for debugging)
• output.mid - Final MIDI file

Supported MML Notation

Currently supported notation:

• Basic Notes: c, d, e, f, g, a, b (case-insensitive)
• Multi-channel: Channel separation with ; (simultaneous playback)

Examples:

cdefgab     → Continuous playback of C-D-E-F-G-A-B
c;e;g       → Simultaneous playback of C, E, and G notes (C major chord)

Development

Build

cargo build        # Debug build
cargo build --release  # Release build

Test

cargo test         # Run all tests (35 test cases)

Format & Lint

cargo clippy       # Code quality check
cargo fmt --check  # Format check
cargo fmt          # Apply format

tree-sitter Parser Files

The tree-sitter parser files (located under tree-sitter-mml/src/) are tracked in Git following tree-sitter best practices for reliable distribution on crates.io.

Development Workflow:

• The C language source files (parser.c, grammar.json, node-types.json, and the tree_sitter/ directory) are automatically regenerated when grammar.js is modified.
• The build script checks the file modification times and regenerates them only when necessary.
• Prerequisite: If you update the grammar, Node.js and npx must be installed on your system.
• Normal builds (without grammar changes) will use the committed C language files and therefore do not require Node.js.

Why Commit Generated Files This follows the best practices of the tree-sitter ecosystem:

• Users installing from crates.io do not need Node.js or tree-sitter-cli.
• It ensures that the grammar and parser versions precisely match.
• It simplifies CI/CD and cross-platform builds.
• This is a standard practice for all tree-sitter language crates.

Updating the Grammar: If you modify tree-sitter-mml/grammar.js:

1. Run cargo build - the build script will detect changes and regenerate the parser files.
2. Commit both grammar.js and the regenerated C language files together.
3. This ensures the grammar and parser remain synchronized.

To manually regenerate the parser files:

cd tree-sitter-mml
npm install  # if tree-sitter-cli is not yet installed
npx tree-sitter generate

Project Structure

src/
├── main.rs              # CLI entry point
├── lib.rs               # Library root
├── pass1_parser.rs      # Pass 1: Token parsing
├── pass2_ast.rs         # Pass 2: AST conversion
├── pass3_events.rs      # Pass 3: MIDI event generation
├── pass4_midi.rs        # Pass 4: MIDI file creation
├── tree_sitter_mml.rs   # tree-sitter MML integration
└── types.rs             # Common type definitions

tests/
├── integration_test.rs  # Integration tests
├── test_channel.rs      # Channel functionality tests
├── test_pass1.rs        # Pass 1 tests
├── test_pass2.rs        # Pass 2 tests
├── test_pass3.rs        # Pass 3 tests
└── test_pass4.rs        # Pass 4 tests

License

MIT License - See the LICENSE file for details.

Reference

• Original Python implementation: cat2151/mmlabc-to-smf