View on GitHub

mmlabc-to-smf-rust

mmlabc-to-smf-rust

mmlabc-to-smf-rust

Japanese English

A library for converting Music Macro Language (MML) to Standard MIDI File (SMF).

Overview

This library converts a Music Macro Language (MML) format string into a Standard MIDI File. It is written in Rust.

Usage

Used as a library by cat-play-mml.

Status

Frequent breaking changes are being made.

The README is outdated. Many more MML commands are actually implemented. The README will be updated later.

To understand the implemented MML, please refer to tree-sitter-mml/grammar.js first (though this will also be subject to breaking changes in the future).

Implemented Features ✅

Verification

# 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 🚧

Long-term Goals 🎯

References

Features

Requirements

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 (concurrent notes)
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, after generating a MIDI file, it will be automatically played using the cat-play-mml command. This allows you to immediately check the sound during MML development.

Configuring a Custom Player

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

Example configuration file:

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

Common configurable MIDI players:

If no configuration file exists, cat-play-mml will be used by default.

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

Output Files

Running the command will generate the following files:

Supported MML Notation

Currently supported notation:

Examples:

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

Development

Build

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

Tests

cargo test         # Run all tests (35 test cases)

Format & Lint

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

tree-sitter Parser Files

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

Development Workflow:

Why commit generated files? This follows best practices in the tree-sitter ecosystem:

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

  1. Run cargo build - the build script will detect the change and regenerate the parser files.
  2. Commit both grammar.js and the regenerated C files together.
  3. This keeps the grammar and parser 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 Transformation
├── 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 Feature 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