MIDI Markdown

A Visual Studio Code extension that provides syntax highlighting and language support for MIDI Markdown (MMD) files.

What is MIDI Markdown?

MIDI Markdown is a human-readable, markdown-style language for creating MIDI music. It allows you to compose MIDI sequences using an intuitive text format with powerful features for musical expression.

Features

• Syntax Highlighting: Full syntax highlighting for all MMD language constructs
• Code Snippets: 40+ snippets for rapid composition and common patterns
• Auto-closing Pairs: Automatic closing of brackets, parentheses, and quotes
• Comment Support: Line comments (//, #) and block comments (/* */)
• Bracket Matching: Automatic matching for {}, [], and () pairs

Language Support

The extension provides syntax highlighting for the following MMD features:

Core Features

• YAML Frontmatter: Metadata and configuration using standard YAML syntax
• Comments: Single-line (//, #) and multi-line (/* */) comments
• Section Headers: Markdown-style headers for organizing your composition
• Imports: Import and reuse code from other MMD files
• Defines: Define constants and variables
• Aliases: Create reusable macros with parameters

Musical Elements

• Tracks: Define and organize MIDI tracks with channel assignments
• Sections: Named musical sections with timing
• Groups: Logical grouping of commands
• Loops: Repeat musical patterns with precise timing control
• Sweeps: Gradual parameter changes over time
• Conditionals: Dynamic music generation based on conditions

Timing Notation

• Absolute Time: [00:00.000] (minutes:seconds.milliseconds)
• Musical Time: [1.1.1] (bar.beat.tick)
• Relative Time: [+500ms], [+2b], [+1.2.0]
• Simultaneous: [@] for events at the same time

MIDI Commands

• Note Commands: note_on, note_off with note names (C4, D#5) or numbers
• Control Change: cc, control_change with controller numbers
• Program Change: pc, program_change for instrument selection
• Pitch Bend: pb, pitch_bend for pitch modulation
• Pressure: channel_pressure, poly_pressure (aftertouch)
• System Messages: SysEx, MTC, song position, and more
• Meta Events: tempo, time_signature, key_signature, text events

Advanced Features

• Parameter Types: note, channel, bool, percent, velocity, numeric ranges
• Modulation Functions:
  • ramp(start, end, curve) - Linear or curved value transitions
  • random(min, max) - Random value generation
  • curve(start, end, type) - Bezier and easing curves
  • wave(type, freq, ...) - Sine, triangle, square, sawtooth oscillators
  • envelope(type, ...) - ADSR, AR, AD envelopes
• Variable References: ${variableName} for dynamic values
• Computed Values: {var = expression} for inline calculations
• Expressions: Full arithmetic support with +, -, *, /, %

File Extension

The extension activates for files with the .mmd extension.

Example

---
title: "My First MIDI Composition"
tempo: 120
---

## Track Drums
@track drums channel=9

[0.1.0]
- note_on 9.C1 100 1b
- note_on 9.E1 80 1b

[0.2.0]
- note_on 9.C1 100 1b
- note_on 9.G1 70 1b

## Track Melody
@track melody channel=0

[1.1.0]
- program_change 0.0

@alias melody_note {note:note} {vel:velocity=80}
  - note_on 0.{note} {vel} 2b
@end

[1.1.0]
- melody_note C4 100
[1.3.0]
- melody_note E4 90
[2.1.0]
- melody_note G4 95

Requirements

• Visual Studio Code version 1.105.0 or higher

Installation

1. Download the .vsix file or install from the VS Code marketplace
2. In VS Code, go to Extensions
3. Click "..." menu and select "Install from VSIX..." (if installing locally)
4. Open any .mmd file to activate the extension

Snippets

The extension includes 40+ code snippets to speed up composition. Type the prefix and press Tab to expand. Some useful snippets include:

Document & Structure

• frontmatter - YAML frontmatter with title and tempo
• track - Track definition with header
• trackfull - Complete track template with program change
• import - Import another MMD file
• define - Define a constant

Musical Elements

• noteon / noteoff - Note commands
• cc - Control change
• pc - Program change
• pb - Pitch bend
• tempo / timesig / keysig - Meta events

Control Structures

• alias / aliasm - Create aliases and macros
• loop - Loop with timing
• sweep - Parameter sweep
• if / ifelse - Conditionals

Timing

• tab - Absolute time (MM:SS.mmm)
• tmus - Musical time (bar.beat.tick)
• trel - Relative time
• tsim - Simultaneous time

Modulation

• ramp - Ramp function with curve types
• random - Random value generation
• curve - Curve modulation
• wave - Wave oscillator
• adsr / ar - Envelope functions

Templates

• drums - Complete drum pattern template
• notealias - Reusable note alias with velocity
• velsweep - Velocity sweep pattern

For a complete list of snippets, see the snippets file.

Language Configuration

The extension provides:

• Line comment characters: // and #
• Block comment delimiters: /* */
• Auto-closing pairs for brackets, parentheses, and quotes
• Bracket matching and surrounding pair support

Contributing

Issues and contributions are welcome! Please visit the repository to report bugs or suggest features.

Release Notes

0.2.0

Added snippets support:

• 40+ code snippets for rapid composition
• Snippets for all major MMD language constructs
• Complete templates for tracks, drums, and common patterns
• Modulation function snippets (ramp, curve, wave, envelope)

0.1.1

Maintenance release with bug fixes and improvements.

0.1.0

Initial release of MIDI Markdown language support:

• Complete syntax highlighting for MMD language
• Support for all MIDI commands and meta events
• Advanced modulation and expression syntax
• Comprehensive language configuration

License

See LICENSE file for details.