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.

Search AI Tools

Install this agent skill to your Project

SKILL.md

MMDC CLI Usage Skill

Overview

Core Commands

Compile MMD to MIDI

Validate Without Compiling

Real-Time Playback

Inspect Events

Device Library Management

Common Options

Output Formats

Resolution/PPQ

Verbosity

Workflow Examples

Development Workflow

Quick Test Loop

Batch Processing

Troubleshooting

Validation Errors

Playback Issues

Compilation Failures

Tips and Best Practices

Always Validate First

Use Inspect for Debugging

Test with Playback

Export for Analysis

Integration with Other Tools

Using with UV (Python Package Manager)

Using with Just (Task Runner)

Piping Output

Error Codes

Getting Help

Quick Reference

Complete Examples

Example 1: Basic Compile and Play

Example 2: Debugging Workflow

Example 3: Batch Validation

Example 4: Export and Analyze

Performance Tips

Large Files

Rapid Iteration

Related Skills

Additional Resources

Common Use Cases

Live Performance

Studio Production

Testing and Development