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

# 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

# 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

# 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

# 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

# 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

# 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

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

Batch Processing

# 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

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

1. Timing going backwards

   • Error: "Time X is before previous event at time Y"
   • Fix: Ensure timing markers increase monotonically

2. Values out of range

   • Error: "Value X exceeds maximum allowed (127)"
   • Fix: Check MIDI value ranges (0-127, channels 1-16)

3. Missing timing marker

   • Error: "No timing marker before first event"
   • Fix: Always start with [00:00.000] or [1.1.0]

4. Invalid syntax

   • Error: "Unexpected token at line X"
   • Fix: Check syntax against REFERENCE.md in mmd-writing skill

Playback Issues

# 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

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

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

Use Inspect for Debugging

When timing or values seem wrong, inspect the events:

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

Test with Playback

Real-time playback helps verify timing and automation:

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:

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

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

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

Piping Output

# 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

# 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

# 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

# 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

# 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

# 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):

# 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

# 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

# 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

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

# Validate before session
mmdc validate *.mmd

Testing and Development

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