MIDI Control

Controlling mtrack via MIDI foot controllers

MIDI Control

mtrack can be controlled via MIDI foot controllers, making it perfect for hands-free operation during live performance.

MIDI Controller Configuration

Configure MIDI control in your mtrack.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

controllers:
  - kind: midi
    play:
      type: control_change
      channel: 16
      controller: 100
      value: 0
    
    prev:
      type: control_change
      channel: 16
      controller: 100
      value: 1
    
    next:
      type: control_change
      channel: 16
      controller: 100
      value: 2
    
    stop:
      type: control_change
      channel: 16
      controller: 100
      value: 3
    
    all_songs:
      type: control_change
      channel: 16
      controller: 100
      value: 4
    
    playlist:
      type: control_change
      channel: 16
      controller: 100
      value: 5

Supported MIDI Events

You can use various MIDI event types for control:

Control Change

Most common for foot controllers:

1
2
3
4
5

play:
  type: control_change
  channel: 16
  controller: 100
  value: 0

Note On/Off

1
2
3
4
5

play:
  type: note_on
  channel: 16
  note: 60
  velocity: 127

Program Change

1
2
3
4

play:
  type: program_change
  channel: 16
  program: 1

See MIDI Events Reference for all supported event types.

Control Actions

Play

Starts the currently selected song (if no song is playing):

1
2
3
4
5

play:
  type: control_change
  channel: 16
  controller: 100
  value: 0

Stop

Stops the currently playing song:

1
2
3
4
5

stop:
  type: control_change
  channel: 16
  controller: 100
  value: 3

Previous

Navigate to the previous song in the playlist (only works when stopped):

1
2
3
4
5

prev:
  type: control_change
  channel: 16
  controller: 100
  value: 1

Next

Navigate to the next song in the playlist (only works when stopped):

1
2
3
4
5

next:
  type: control_change
  channel: 16
  controller: 100
  value: 2

All Songs

Switch to a playlist containing all songs in your repository:

1
2
3
4
5

all_songs:
  type: control_change
  channel: 16
  controller: 100
  value: 4

Playlist

Switch back to your defined playlist:

1
2
3
4
5

playlist:
  type: control_change
  channel: 16
  controller: 100
  value: 5

Status Feedback

Configure status events so your controller receives feedback about player state:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

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

Status events are emitted periodically:

  • Off (1 second) - Normal state indicator off
  • On (250ms) - Either idling or playing indicator
  • Off (1 second) - Repeat cycle

Song Selection Events

Songs can emit MIDI events when selected:

1
2
3
4
5

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

This is useful for:

  • Changing presets on remote devices
  • Triggering scene changes
  • Providing visual feedback

Live MIDI to DMX

Route live MIDI events into the DMX engine:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

midi:
  midi_to_dmx:
    - midi_channel: 15
      universe: light-show
      transformers:
        - type: note_mapper
          input_note: 0
          convert_to_notes: [0, 1, 2, 4, 5, 6]
        - type: control_change_mapper
          input_controller: 0
          convert_to_controllers: [0, 1, 2, 4, 5, 6]

Transformers

Note Mapper: Maps one note to multiple notes with the same velocity:

1
2
3

- type: note_mapper
  input_note: 0
  convert_to_notes: [0, 1, 2, 4, 5, 6]

Control Change Mapper: Maps one controller to multiple controllers with the same value:

1
2
3

- type: control_change_mapper
  input_controller: 0
  convert_to_controllers: [0, 1, 2, 4, 5, 6]

Finding Your MIDI Device

List available MIDI devices:

1

mtrack midi-devices

Use the device name (before the colon) in your configuration.

Common Foot Controller Setups

Single Button Per Action

Map each action to a different button:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

controllers:
  - kind: midi
    play:
      type: note_on
      channel: 1
      note: 60
    stop:
      type: note_on
      channel: 1
      note: 61
    next:
      type: note_on
      channel: 1
      note: 62
    prev:
      type: note_on
      channel: 1
      note: 63

Single Button with Values

Use one button/controller with different values:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

controllers:
  - kind: midi
    play:
      type: control_change
      channel: 1
      controller: 1
      value: 0
    stop:
      type: control_change
      channel: 1
      controller: 1
      value: 127