MIDI Markdown Documentation¶
Welcome to the MIDI Markdown (MMD) documentation. MMD is a human-readable, text-based format for creating MIDI sequences, designed for live performance automation and compositional workflows.
Quick Start¶
- Getting Started - Create your first MIDI file in 5 minutes
- Installation Guide - Detailed setup instructions for all platforms
- Claude Code Skills - Optional AI assistant skills for enhanced development (Claude Code users)
User Guides¶
Learn how to use MMD effectively:
- Basic Syntax - Fundamentals: frontmatter, timing, commands
- Timing Systems - Absolute, musical, relative, and simultaneous timing
- Alias System - Create reusable command shortcuts
- Device Libraries - Control MIDI hardware with high-level commands
- Real-time Playback - Live MIDI playback with interactive Terminal UI
- Computed Values - Variables, expressions, and computed parameters
- Modulation - Curves, waveforms, and envelopes
- Generative Music - Random values and algorithmic composition
Reference Documentation¶
Complete API and command references:
- Language Specification - Complete MMD specification (1,600+ lines)
- CLI Commands - Command-line interface reference
- Alias API - Alias definition and parameter syntax
- MIDI Commands - Quick MIDI command reference
- Modulation Reference - Curves, waveforms, and envelopes
- Random Expressions - Random value generation
- FAQ - Frequently asked questions
- Troubleshooting - Common issues and solutions
Examples¶
Progressive learning path with 16 examples:
- Examples Guide - Complete guide with learning path and feature matrix
Quick Links: - 01_hello_world.mmd - Simplest possible MMD file - 01_multi_channel_basic.mmd - Multiple MIDI channels - 10_comprehensive_song.mmd - All features combined - 01_device_import.mmd - Device library imports - 01_random_humanization.mmd - Random values for humanization - 03_generative_ambient.mmd - Generative music techniques
Developer Documentation¶
Architecture and implementation details:
- Architecture Overview - System architecture and compilation pipeline
- Parser Design - Parser architecture and Lark grammar
- Parser Design - Parser and lexer implementation details
- IR Specification - Intermediate representation format
- Contributing Guide - How to contribute to the project
Device Libraries¶
Pre-built libraries for controlling MIDI hardware:
- Neural DSP Quad Cortex - 86 aliases for Quad Cortex control
- Eventide H90 - 61 aliases for H90 harmonizer/effects
- Line 6 Helix - 49 aliases for Helix control
- HX Stomp - HX Stomp control
- HX Effects - HX Effects control
- HX Stomp XL - HX Stomp XL control
See the Device Library Guide to learn more.
Additional Resources¶
- specification.md - Authoritative language specification
- CLAUDE.md - Developer context and architecture (for AI assistants)
- README.md - Project overview and quick start
- Tests - Test suite with 1264+ tests
Documentation Status¶
✅ = Complete | 🚧 = Coming Soon
| Document | Status |
|---|---|
| Getting Started | ✅ Complete |
| Installation | ✅ Complete |
| Basic Syntax Guide | ✅ Complete |
| Timing Systems Guide | ✅ Complete |
| Alias System Guide | ✅ Complete |
| Device Libraries Guide | ✅ Complete |
| Real-time Playback Guide | ✅ Complete |
| Computed Values Guide | ✅ Complete |
| Modulation Guide | ✅ Complete |
| Generative Music Guide | ✅ Complete |
| CLI Reference | ✅ Complete |
| Alias API Reference | ✅ Complete |
| MIDI Commands Reference | ✅ Complete |
| Architecture Overview | ✅ Complete |
| IR Specification | ✅ Complete |
| Parser Design | ✅ Complete |
| Lexer Design | ✅ Complete |
| Contributing Guide | ✅ Complete |
Need Help?¶
- Examples: Start with getting-started/examples-guide.md
- CLI Help: Run
uv run mmdc --help - Issues: Report bugs on GitHub
- Specification: See specification.md for complete reference
Version: 0.1.0 Last Updated: 2025-11-05