MIDI Events Reference

Complete reference of supported MIDI event types

MIDI Events Reference

mtrack supports various MIDI event types for control and automation. This reference covers all supported events.

Event Types

Note Off

Acts as if a note was released:

1
2
3
4
5

midi_event:
  type: note_off
  channel: 5  # Channels are 1-16
  note: 5
  velocity: 127

Note On

Acts as if a note was pressed:

1
2
3
4
5

midi_event:
  type: note_on
  channel: 5
  note: 5
  velocity: 127

Aftertouch (Polyphonic)

Polyphonic aftertouch for a specific note:

1
2
3
4
5

midi_event:
  type: aftertouch
  channel: 5
  note: 5
  velocity: 127

Control Change

Changes a controller value:

1
2
3
4
5

midi_event:
  type: control_change
  channel: 5
  controller: 12
  value: 27

Program Change

Changes banks and instruments:

1
2
3
4

midi_event:
  type: program_change
  channel: 5
  program: 20

Channel Aftertouch

Channel-wide aftertouch:

1
2
3
4

midi_event:
  type: channel_aftertouch
  channel: 5
  velocity: 127

Pitch Bend

Pitch bend event:

1
2
3

midi_event:
  type: pitch_bend
  bend: 1234

Usage Contexts

Controller Events

Use in controller configuration for player control:

1
2
3
4
5
6
7

controllers:
  - kind: midi
    play:
      type: control_change
      channel: 16
      controller: 100
      value: 0

Song Selection Events

Emit when a song is selected:

1
2
3
4
5

# In song.yaml
midi_event:
  type: program_change
  channel: 16
  program: 3

Status Events

For controller feedback:

1
2
3
4
5
6

status_events:
  off_events:
    - type: control_change
      channel: 16
      controller: 3
      value: 2

Channel Numbers

MIDI channels in mtrack are specified as 1-16, not 0-15. This matches common MIDI controller conventions.

Value Ranges

  • Velocity: 0-127
  • Controller Value: 0-127
  • Program: 0-127
  • Note: 0-127 (MIDI note numbers)
  • Pitch Bend: -8192 to 8191 (typically represented as 0-16383)