MMDC CLI Usage Skill

Overview

This skill helps you effectively use the MIDI Markdown Compiler (mmdc) command-line interface for compiling, validating, playing, inspecting MMD files, and managing device libraries.

Core Commands

Compile MMD to MIDI

bash

# Basic compilation
mmdc compile input.mmd -o output.mid

# With custom resolution
mmdc compile song.mmd -o song.mid --ppq 960

# Export to different formats
mmdc compile song.mmd --format json -o events.json
mmdc compile song.mmd --format csv -o events.csv
mmdc compile song.mmd --format table  # Display in terminal

Validate Without Compiling

bash

# Full validation (recommended before compilation)
mmdc validate song.mmd

# Verbose output with details
mmdc validate song.mmd --verbose

# Just syntax check (no semantic validation)
mmdc check song.mmd

Real-Time Playback

bash

# Play with TUI (interactive terminal UI)
mmdc play song.mmd --port 0

# List available MIDI ports
mmdc play --list-ports

# Play with specific port by name
mmdc play song.mmd --port "IAC Driver Bus 1"

TUI Controls:

•Spacebar - Pause/Resume
•Q - Quit
•R - Restart from beginning

Inspect Events

bash

# Display event timeline as table
mmdc inspect song.mmd

# With more detail
mmdc inspect song.mmd --verbose

# Filter by event type
mmdc inspect song.mmd --type note_on
mmdc inspect song.mmd --type cc

Device Library Management

bash

# List all installed device libraries
mmdc library list

# Show info about a specific library
mmdc library info quad_cortex
mmdc library info eventide_h90

# Validate a device library file
mmdc library validate devices/my_device.mmd
mmdc library validate custom_library.mmd

# Search for libraries
mmdc library search "eventide"
mmdc library search "helix"
mmdc library search "neural"

# Create a new device library template
mmdc library create my_device
mmdc library create my_synth --manufacturer "Acme" --device "Acme Synth Pro"
mmdc library create my_fx --output my_library.mmd --channel 5

# Install library from repository (planned feature)
# mmdc library install eventide-h90

Library Commands:

•library list - Shows all available device libraries with alias counts
•library info <name> - Displays library metadata and all available aliases
•library validate <file> - Checks library syntax and structure
•library search <query> - Searches libraries by name, manufacturer, or description
•library create <name> - Creates a new device library template
•library install <source> - (Planned) Install from repository or URL

Common Options

Output Formats

•--format midi (default) - Standard MIDI file
•--format json - JSON representation
•--format csv - CSV export (midicsv-compatible)
•--format table - Terminal table display

Resolution/PPQ

•--ppq 480 (default) - High resolution
•--ppq 960 - Very high resolution
•--ppq 192 - Standard resolution

Verbosity

•--verbose - Detailed output
•--quiet - Minimal output
•--debug - Debug information

Workflow Examples

Development Workflow

bash

# 1. Check syntax while writing
mmdc check song.mmd

# 2. Full validation before compilation
mmdc validate song.mmd

# 3. Inspect events to verify
mmdc inspect song.mmd

# 4. Compile to MIDI
mmdc compile song.mmd -o output.mid

# 5. Test playback
mmdc play song.mmd --port 0

Quick Test Loop

bash

# Edit, validate, play cycle
mmdc validate song.mmd && mmdc play song.mmd --port 0

Batch Processing

bash

# Compile all MMD files in directory
for file in *.mmd; do
  mmdc compile "$file" -o "output/$(basename "$file" .mmd).mid"
done

# Validate all examples
mmdc validate examples/**/*.mmd

Troubleshooting

Validation Errors

bash

# Get detailed error information
mmdc validate song.mmd --verbose

# Check just syntax first
mmdc check song.mmd

# Inspect specific section
mmdc inspect song.mmd

Common Errors:

•
Timing going backwards
- •Error: "Time X is before previous event at time Y"
- •Fix: Ensure timing markers increase monotonically
•
Values out of range
- •Error: "Value X exceeds maximum allowed (127)"
- •Fix: Check MIDI value ranges (0-127, channels 1-16)
•
Missing timing marker
- •Error: "No timing marker before first event"
- •Fix: Always start with [00:00.000] or [1.1.0]
•
Invalid syntax
- •Error: "Unexpected token at line X"
- •Fix: Check syntax against REFERENCE.md in mmd-writing skill

Playback Issues

bash

# List all available MIDI ports
mmdc play --list-ports

# Test with different port
mmdc play song.mmd --port 1

# Check events are correct
mmdc inspect song.mmd

Common Issues:

•No MIDI output: Check port number with --list-ports
•Wrong timing: Verify events with inspect command
•Missing events: Check validation output

Compilation Failures

bash

# Validate first to see errors
mmdc validate song.mmd

# Check for import issues
mmdc check song.mmd --verbose

# Export to JSON for debugging
mmdc compile song.mmd --format json -o debug.json

Tips and Best Practices

Always Validate First

Before compiling, always validate to catch errors early:

bash

mmdc validate song.mmd && mmdc compile song.mmd -o output.mid

Use Inspect for Debugging

When timing or values seem wrong, inspect the events:

bash

mmdc inspect song.mmd | grep "note_on"
mmdc inspect song.mmd --type cc

Test with Playback

Real-time playback helps verify timing and automation:

bash

mmdc play song.mmd --port 0
# Use spacebar to pause, Q to quit, R to restart

Export for Analysis

JSON and CSV formats are great for analysis:

bash

# JSON for programmatic access
mmdc compile song.mmd --format json -o events.json

# CSV for spreadsheet analysis
mmdc compile song.mmd --format csv -o events.csv

Integration with Other Tools

Using with UV (Python Package Manager)

bash

# Run from project directory
uv run mmdc compile song.mmd -o output.mid

# Or after installation
mmdc compile song.mmd -o output.mid

Using with Just (Task Runner)

bash

# If project has justfile
just compile input.mmd output.mid
just validate song.mmd
just run play song.mmd

Piping Output

bash

# Validate and capture output
mmdc validate song.mmd 2>&1 | tee validation.log

# Inspect and filter
mmdc inspect song.mmd | grep "00:10"

Error Codes

Common exit codes:

•0 - Success
•1 - Validation error
•2 - File not found
•3 - Compilation error
•4 - Runtime error (playback)

Getting Help

bash

# General help
mmdc --help

# Command-specific help
mmdc compile --help
mmdc validate --help
mmdc play --help
mmdc inspect --help

# Version information
mmdc --version

Quick Reference

Task	Command
Compile to MIDI	`mmdc compile input.mmd -o output.mid`
Validate	`mmdc validate song.mmd`
Syntax check	`mmdc check song.mmd`
Play with TUI	`mmdc play song.mmd --port 0`
List MIDI ports	`mmdc play --list-ports`
Inspect events	`mmdc inspect song.mmd`
Export JSON	`mmdc compile song.mmd --format json -o out.json`
Export CSV	`mmdc compile song.mmd --format csv -o out.csv`
Table display	`mmdc compile song.mmd --format table`
List libraries	`mmdc library list`
Library info	`mmdc library info quad_cortex`
Validate library	`mmdc library validate devices/my_device.mmd`
Search libraries	`mmdc library search "eventide"`
Create library	`mmdc library create my_device`

Complete Examples

Example 1: Basic Compile and Play

bash

# Create a simple MMD file
cat > test.mmd << 'EOF'
---
title: "Test Song"
ppq: 480
tempo: 120
---

[00:00.000]
- tempo 120
- note_on 1.C4 100 1b
- note_on 1.E4 100 1b
- note_on 1.G4 100 1b
EOF

# Validate
mmdc validate test.mmd

# Compile
mmdc compile test.mmd -o test.mid

# Play
mmdc play test.mmd --port 0

Example 2: Debugging Workflow

bash

# Check syntax
mmdc check problematic.mmd

# Full validation with verbose output
mmdc validate problematic.mmd --verbose

# Inspect events to find issues
mmdc inspect problematic.mmd

# Export to JSON for detailed analysis
mmdc compile problematic.mmd --format json -o debug.json

# View specific event types
mmdc inspect problematic.mmd --type cc | less

Example 3: Batch Validation

bash

# Validate all MMD files
find . -name "*.mmd" -exec mmdc validate {} \;

# Or with better output
for file in examples/**/*.mmd; do
  echo "Validating $file..."
  mmdc validate "$file" || echo "FAILED: $file"
done

Example 4: Export and Analyze

bash

# Export to CSV
mmdc compile song.mmd --format csv -o events.csv

# Analyze in spreadsheet or with command-line tools
cut -d',' -f1,3,4 events.csv | grep "note_on"

# Export to JSON for scripting
mmdc compile song.mmd --format json -o events.json
jq '.events[] | select(.type == "note_on")' events.json

Performance Tips

Large Files

For large MMD files (>1000 events):

bash

# Use higher PPQ for better precision
mmdc compile large.mmd -o large.mid --ppq 960

# Validate in chunks by inspecting sections
mmdc inspect large.mmd --from 0 --to 100

Rapid Iteration

bash

# Watch mode (requires entr or similar)
ls *.mmd | entr -c mmdc validate song.mmd

# Quick compile and play
alias mmdp='mmdc validate $1 && mmdc play $1 --port 0'
mmdp song.mmd

Related Skills

•mmd-writing - For help writing MMD files with correct syntax

Additional Resources

•Project Examples: examples/ directory contains 49 working example files
•User Documentation: docs/user-guide/ in project root
•Specification: spec.md - Complete MMD language specification
•Developer Guides: docs/dev-guides/ for implementation details

Common Use Cases

Live Performance

bash

# List MIDI ports to find your device
mmdc play --list-ports

# Play live set automation
mmdc play live-set.mmd --port "Your Device Name"

Studio Production

bash

# Compile automation for DAW
mmdc compile automation.mmd -o automation.mid --ppq 960

# Validate before session
mmdc validate *.mmd

Testing and Development

bash

# Quick validation loop during development
while true; do
  clear
  mmdc validate song.mmd
  sleep 2
done

# Generate test data
mmdc compile test.mmd --format json -o test-data.json

For help writing MMD files, see the mmd-writing skill. For project documentation, see docs/ in project root.