MTXT - Music Text Format

MTXT is a human-editable, text-based format for representing musical performance data. It stores events with precise timing, pitch, and expression values in a simple line-based structure that's easy to edit without requiring specialized tools.

The format is designed for cases where exact performance details matter - arbitrary timings, micro-tuning, dynamic changes, and other expressive parameters. MTXT avoids binary encoding, making it suitable for manual and AI-assisted editing.

Features

Beat-based: Events are placed on fractional beats using simple decimal notation (e.g., in a 4/4 time signature, 1 beat = 1 quarter note, so 3.25 represents 3 quarter notes plus 1 sixteenth note).
One event per line: Easy to search and modify with any text editor.
Human-friendly: Use of musical note names (C4, D#3, etc.) and custom note aliases (e.g. kick or Cmaj7). Hand-crafted files are practical and expressive.
Transitions: Built-in support for gliding continuous parameters (CC, tempo) with customizable curves and timing.
Real-time ready: Supports streaming musical events and real-time data transfer with transitions and flexible timing.
Microtonal support: Built-in cents notation for notes (e.g. C4+50, D4-25) and global tuning commands for alternate tuning systems and just intonation.
Flexible organization: Events can be written in any order in the file, with the parser handling chronological sorting.
MIDI compatible: Reference implementation includes MIDI to MTXT and MTXT to MIDI conversion.
LLM compatible: Can be easily generated and manipulated by language models.
Future-proof: Supports up to 65535 channels, arbitrary CC parameters with custom string keys and custom metadata.

Quick Example

mtxt 1.0
meta global title Sunrise Melody
meta global author Jane Composer

// Define aliases for drums and chords
alias kick C1
alias Cmaj7 C4,E4,G4,B4

// Global tempo and time signature
0.0 tempo 100
0.0 timesig 4/4

// Set defaults for channel, duration, and velocity
ch=0
dur=1.0
vel=0.8

// Set voice. "John's bright grand" has precedence, but it falls back to a more generic "piano" if not found.
0.0 voice piano, John's bright grand

// Start silently
0.0 cc volume 0.0

// Fade in volume over 3.0 beats, ending at beat 4.0
4.0 cc volume 1.0 transition_time=3.0 transition_curve=0.5

// Play melody (uses default duration and velocity from above, unless overridden)
0.0 note C4
2.0 note G4 vel=0.5
// Notes can be put in arbitrary order, the parser will sort them
1.0 note E4 
2.0 note G4 vel=0.5

// Chords can also be played (defined above as an alias for C4,E4,G4,B4 notes)
1.0 note Cmaj7 dur=2.0 vel=0.2

// Tempo ramp
8.0 tempo 120 transition_time=4.0

// Microtonal note (12TET equal temperament C4 + 50 cents)
3.0 note C4+50

Rust Library and CLI Tool

This repository includes a reference implementation in Rust that provides:

Library (mtxt): Rust crate for parsing and writing MTXT files, with MIDI conversion features.
CLI tool: Command-line utility for converting between MIDI and MTXT formats with built-in transforms. Builds can be downloaded from releases.

Basic Usage

mtxt input.mid output.mtxt # MIDI to MTXT
mtxt input.mtxt output.mid # MTXT to MIDI
mtxt input.mtxt output.mtxt --sort # transform MTXT file and sort events by time

Transform Options

The CLI supports various transforms that can be applied during conversion:

Musical Transforms:

--transpose <SEMITONES> - Transpose all notes by semitones (e.g., --transpose +2 or --transpose -12)
-q, --quantize <GRID> - Quantize timing to a grid (e.g., 4 for quarter notes, 16 for 16th notes)
--offset <BEATS> - Offset all events by beats (e.g., --offset 1.5, --offset -0.5). Events shifted to negative times are removed.
--swing <AMOUNT> - Apply swing feel (0.0 to 1.0)
--humanize <AMOUNT> - Add timing randomization for humanization (0.0 to 1.0)

Channel Filtering:

--include-channels <CHANNELS> - Include only specific channels (comma-separated, e.g., 1,2,10)
--exclude-channels <CHANNELS> - Exclude specific channels (comma-separated, e.g., 1,2,10)

File Organization:

--apply-directives - Apply global directives to events (inline parameters)
--extract-directives - Extract common inline parameters into global directives
--merge-notes - Merge note on / off pairs into note shorthand events with durations
--group-channels - Group events by channel
--sort - Sort events by time
--indent - Enable timestamp padding

MTXT Specification

Versioning

First line must declare version:
```
mtxt 1.0
```

Structure

A file consists of:
1. Version line
2. Global metadata (optional)
3. Events (can be in any timestamp order)

Timing

All times are in beats specified as fractional numbers. e.g. in a 4/4 time signature, 1 beat = 1 quarter note, so 3.25 represents 3 quarter notes plus 1 sixteenth note.
This allows changing the tempo and time signature without affecting the timing of events.
Events may appear in any order in the file; the parser will sort them before playback
Precision is limited to 5 decimal places (5 microseconds at 120 BPM).

Commands

version (mtxt)

mtxt <semver>

Declares the file format version in the major.minor format (e.g., mtxt 1.0).
Must be the first non-comment line.

meta

// global meta (applies to the entire file and all channels)
meta global <type> <value>
// channel meta (applies to a single channel), starting from the specified time
[<time>] meta [ch=<0..65535>] <type> <value>

Adds metadata (e.g., title, author, copyright, trackname, custom types).
Value extends from the type to the end of the line (or until inline comment).
Channel is optional, if not specified it inherits the channel from the previous ch command.
Time is optional, defaults to 0.0.
See Standard Meta Types for a list of standard types.
Newline characters in <value> need to be escaped to avoid breaking the syntax.

Standard Meta Types

| Type | -------------- | title | author | copyright | composer | name | instrument | smpte | keysignature | text | lyric | marker | cue | program | device | key | date | genre | album | url | artist | license | generator | Description | Example | | ---------------- | ----------------------------------------- | | Song title | meta global title My Song | | Composer/author | meta global author John Doe | | Copyright notice | meta global copyright © 2024 Music Corp | | Composer name | meta global composer John Doe | | Channel name | meta ch=1 name Lead Guitar | | Instrument name | meta ch=2 instrument Steinway Grand | | SMPTE offset | meta global smpte 00:00:00:00 | | Key signature | 4.0 meta ch=3 keysignature C major | | General text | meta text Verse 1 | | Lyrics | 5.0 meta lyric Hello world | | Marker/cue point | 6.0 meta marker Chorus | | Cue point | 7.0 meta cue Solo begins | | Program name | meta global program Piano Ballad | | Device name | meta global device OpenPiano 1000 | | Key signature | meta global key C major | | Creation date | meta global date 2024-01-01 | | Musical genre | meta global genre Rock | | Album name | meta global album Greatest Hits | | Related URL | meta global url https://example.com | | Performer name | meta global artist The Band | | Usage license | meta global license CC-BY-4.0 | | Software tool | meta global generator MySequencer v1.0 |

ch (channel directive)

ch=<0..65535>

Sets the default MIDI channel for subsequent events.
Inline ch=<N> on events overrides the default for that event only.
Required before channel-dependent events that omit inline ch.

alias (note naming)

alias <name> <value>

Defines a named alias for a note pitch or a chord.
<name>: Alphanumeric identifier (e.g., snare, Cmaj7).
<value>: Target note(s), comma-separated if multiple.
No timestamp. Applies to all subsequent events in the file until overridden.
Name is case-insensitive.

Example:

alias snare C2
alias Cmaj7 C4,E4,G4,B4  // chord alias
0.0 note snare
1.0 note Cmaj7          // plays all 4 notes

vel (default note-on velocity)

vel=<0.0..1.0>

Sets the default note-on velocity.
Inline vel=<N> on note/on overrides for that event.

offvel (default note-off velocity)

offvel=<0.0..1.0>

Sets the default note-off velocity.
Inline offvel=<N> on note/off overrides for that event.
Defaults to 1.0 if not set.

dur (default note duration)

dur=<float>

Sets the default note duration in beats.
Inline dur=<N> on note overrides for that event.
Defaults to 1.0 if not set.

transition settings

transition_curve=<float>
transition_interval=<float>

Sets default transition parameters for cc and tempo.
transition_time must be specified per event (default 0.0).
See Transitions section for details.
Defaults: curve=0.0, interval=1.0.

note (shorthand)

<time> note <NOTE> [dur=<float>] [vel=<0..1>] [offvel=<0..1>] [ch=<0..65535>]

Emits note-on at <time> and note-off at <time + dur>.
Uses defaults from dur, vel, offvel, and ch unless o

Mtxt

Install / Use

README