Release v0.1.0

MIDI Markdown Compiler v0.1.0

What's New

Added

• Initial MVP release
• Complete MIDI Markdown parser with Lark-based LALR grammar
• Support for all MIDI 1.0 commands (note on/off, CC, PC, pitch bend, aftertouch, SysEx)
• Four timing paradigms: absolute, musical, relative, simultaneous
• Device library system with 6 device libraries (Quad Cortex, H90, Helix, HX Stomp, HX Effects, HX Stomp XL)
• Alias system for device-specific commands with parameter validation
• Advanced features: loops (@loop), sweeps (@Sweep), variables (@define), expressions
• Generative music support with random() expressions
• Enhanced modulation: Bezier curves, waveforms (LFO), envelopes (ADSR/AR/AD)
• Real-time MIDI playback with TUI (sub-5ms timing precision)
• Multiple output formats: MIDI files, JSON, CSV, table display
• CLI with commands: compile, validate, check, play, inspect, version
• Comprehensive test suite: 1264 tests with 72.53% coverage
• 35 working examples across 7 categories
• Complete documentation: user guides, developer guides, tutorials
• MkDocs documentation site
• GitHub Actions CI/CD workflows
• PyInstaller-based standalone executables for Linux, Windows, macOS

Documentation

• Complete language specification (spec.md)
• Architecture overview (docs/developer-guide/architecture.md)
• Developer guides: parser patterns, timing system, anti-patterns, common tasks
• User guides: quickstart, syntax reference, device libraries, tutorials
• CLAUDE.md for AI-assisted development
• 35 example files with learning paths
• API reference documentation

Developer Experience

• Modern Python 3.12+ with type hints throughout
• UV package manager for fast dependency management
• Ruff for linting and formatting
• MyPy for type checking
• pytest with comprehensive test markers
• Justfile with 50+ development commands
• Pre-commit hooks ready (optional)

Version History

Version Numbering

This project follows Semantic Versioning:

• MAJOR version for incompatible API/syntax changes
• MINOR version for new features (backwards-compatible)
• PATCH version for bug fixes (backwards-compatible)

Release Types

• Stable: Production-ready releases (v1.0.0, v1.1.0, etc.)
• Pre-release: Alpha/beta releases (v0.1.0, v0.2.0-alpha.1, etc.)
• Development: Unreleased changes in main branch

Installation

MMDC Compiler

Download standalone executables (no Python required):

• Linux: mmdc-linux-x86_64.tar.gz
• Windows: mmdc-windows-x86_64.zip
• macOS: mmdc-macos-universal.zip

Extract the archive and run the mmdc executable.

Verify checksums using the .sha256 files to ensure download integrity.

Claude Code Skills (Optional)

For Claude Code users, download the skills package for enhanced MMD development:

• All platforms: claude-skills-mmd-0.1.0.tar.gz or .zip

The skills package includes:

• mmd-writing - Help writing MMD files with correct syntax
• mmdc-cli-usage - Help using the mmdc CLI effectively

See Claude Skills documentation for installation instructions.

Installation via pip/pipx (Python users)

# Using pipx (recommended - isolated environment)
pipx install midi-markdown==0.1.0

# Or using pip
pip install midi-markdown==0.1.0

Platform-Specific Notes

Windows Security Warning: Windows SmartScreen may show a warning for unsigned executables. Click "More info" then "Run anyway" to proceed. This is normal for open-source software without expensive code signing certificates.

macOS Gatekeeper: macOS may block the executable. Right-click the app and select "Open" to bypass Gatekeeper, or run:

xattr -cr mmdc

Quick Start

# Check installation
mmdc --version

# Compile your first MML file
mmdc compile song.mmd -o song.mid

# Play back in real-time (requires MIDI device)
mmdc play song.mmd --port 0

# See all commands
mmdc --help

Documentation

• User Guide: https://github.com/cjgdev/midi-markdown#readme
• Examples: https://github.com/cjgdev/midi-markdown/tree/main/examples
• Language Spec: https://github.com/cjgdev/midi-markdown/blob/main/spec.md

Full Changelog

See below for complete changelog generated by GitHub.

What's Changed

• Review GitHub Workflows Configuration by @cjgdev in #1
• Set up project versioning and release workflow by @cjgdev in #5
• Review and ensure documentation consistency by @cjgdev in #2
• Review and fix skipped tests by @cjgdev in #3
• Review and analyze code examples by @cjgdev in #4
• Fix Windows Unicode encoding error in build by @cjgdev in #8
• Set up documentation publishing process by @cjgdev in #6
• Create Claude skills for MIDI Markdown Compiler by @cjgdev in #7
• Package and release Claude skills with GitHub action by @cjgdev in #9
• Remove unused files from repository by @cjgdev in #10
• Refactor device library files and improve consistency by @cjgdev in #13
• Explore new Claude slash commands for development by @cjgdev in #11
• Enhance mmdc play command functionality by @cjgdev in #12
• Review Anthropic agent skills documentation by @cjgdev in #14
• Create device library skills for Claude by @cjgdev in #15
• Fix broken example links in deployed site by @cjgdev in #16
• Fix timing bug in multi-track MMD files by @cjgdev in #17
• Review and fix skipped tests by @cjgdev in #18
• Implement multi-line sysex support by @cjgdev in #19
• Fix 21 failing tests with grammar and example updates by @cjgdev in #20
• Resolve Build Error by @cjgdev in #22
• Scan documentation directory with subtasks by @cjgdev in #21
• Implement device library command system by @cjgdev in #30
• Fix expansion pipeline integration tests by @cjgdev in #25
• Fix multitrack compilation test failures by @cjgdev in #27
• Fix end-to-end timing assertion failure by @cjgdev in #31
• Fix timing test parsing and edge cases by @cjgdev in #28
• Fix GitHub workflow secrets reference error by @cjgdev in #32
• Fix alias timing test failures by @cjgdev in #29
• Add float range support to MMD parser by @cjgdev in #33
• Add Line6 PowerCab device library support by @cjgdev in #34
• Add specialized tests for functionality by @cjgdev in #35
• Fix failing unit tests by @cjgdev in #36
• Fix and re-enable all failing tests by @cjgdev in #37
• Add Tests for Modulation by @cjgdev in #38
• Fix these tests by @cjgdev in #39
• Add Claude skill for PowerCab device by @cjgdev in #41
• Fix broken documentation links and navigation by @cjgdev in #40
• Fix Linting Errors by @cjgdev in #43
• Improve build and publish process by @cjgdev in #42
• Fix undefined Path import error in CLI by @cjgdev in #44
• Fix failing CLI and scheduler tests by @cjgdev in #45
• Set up pre-commit hooks for code fixes by @cjgdev in #46
• Fix quote style violations in test file by @cjgdev in #48
• Explore Claude AI Capabilities by @cjgdev in #47
• Fix MIDI ALSA sequencer initialization errors in tests by @cjgdev in #49
• Fix missing pip cache folder error by @cjgdev in #50
• Review and enable C permissions in settings by @cjgdev in #51
• Update and rename Claude skills documentation by @cjgdev in #52
• Fix validate-devices macOS shell variable escaping by @cjgdev in #53
• Validate Examples Using Just Command by @cjgdev in #54
• Auto-fill pull request template fields by @cjgdev in #55
• Add Claude agents to project by @cjgdev in #57
• Fix reusable workflow missing trigger by @cjgdev in #58
• Fix release workflow SHA256 hash calculation by @cjgdev in #59
• Review and improve build release GitHub actions by @cjgdev in #60

New Contributors

• @cjgdev made their first contribution in #1

Full Changelog: https://github.com/cjgdev/midi-markdown/commits/v0.1.0