Configuration Reference

Complete configuration reference for mtrack

Configuration Reference

Complete reference for all mtrack configuration options.

Top-Level Configuration

songs

Type: String (path)
Required: Yes
Description: Directory containing song definitions and audio files.

1

songs: /mnt/song-storage

playlist

Type: String (path)
Required: Yes
Description: Path to playlist YAML file.

1

playlist: /mnt/playlist.yaml

Audio Configuration

audio.device

Type: String
Required: Yes
Description: Audio device name (use mtrack devices to list).

1
2

audio:
  device: UltraLite-mk5

audio.buffer_size

Type: Integer
Default: 1024
Description: Background read buffer size in samples.

1
2

audio:
  buffer_size: 1024

audio.buffer_threshold

Type: Integer
Default: 256
Description: Threshold for triggering background reads.

1
2

audio:
  buffer_threshold: 256

audio.sample_rate

Type: Integer
Default: 44100
Description: Sample rate in Hz.

1
2

audio:
  sample_rate: 44100

audio.sample_format

Type: String (int or float)
Default: int
Description: Sample format.

1
2

audio:
  sample_format: int

audio.bits_per_sample

Type: Integer
Default: 32
Description: Bit depth.

1
2

audio:
  bits_per_sample: 32

audio.playback_delay

Type: Duration string (e.g., 500ms, 1s)
Default: 500ms
Description: Delay before starting audio playback.

1
2

audio:
  playback_delay: 500ms

MIDI Configuration

midi.device

Type: String
Required: Yes
Description: MIDI device name (use mtrack midi-devices to list).

1
2

midi:
  device: UltraLite-mk5

midi.playback_delay

Type: Duration string
Default: 500ms
Description: Delay before starting MIDI playback.

1
2

midi:
  playback_delay: 500ms

midi.midi_to_dmx

Type: Array of objects
Description: Route live MIDI events to DMX.

1
2
3
4
5
6
7
8

midi:
  midi_to_dmx:
    - midi_channel: 15
      universe: light-show
      transformers:
        - type: note_mapper
          input_note: 0
          convert_to_notes: [0, 1, 2]

DMX Configuration

dmx.dim_speed_modifier

Type: Float
Default: 0.25
Description: Multiplier for dimming speed.

1
2

dmx:
  dim_speed_modifier: 0.25

dmx.playback_delay

Type: Duration string
Default: 500ms
Description: Delay before starting DMX playback.

1
2

dmx:
  playback_delay: 500ms

dmx.universes

Type: Array of objects
Required: Yes
Description: DMX universe mappings.

1
2
3
4

dmx:
  universes:
    - universe: 1
      name: light-show

dmx.lighting

Type: Object
Description: New lighting system configuration.

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

dmx:
  lighting:
    current_venue: "main_stage"
    fixtures:
      emergency_light: "Emergency @ 1:500"
    groups:
      front_wash:
        name: "front_wash"
        constraints:
          - AllOf: ["wash", "front"]
    directories:
      fixture_types: "lighting/fixture_types"
      venues: "lighting/venues"

Controllers

controllers (array)

Type: Array of controller objects
Description: Control interfaces (gRPC, OSC, MIDI).

gRPC Controller

1
2
3

controllers:
  - kind: grpc
    port: 43234  # Optional

OSC Controller

1
2
3
4
5
6
7
8

controllers:
  - kind: osc
    port: 43235  # Optional
    broadcast_addresses:
      - 127.0.0.1:43236
    play: /mtrack/play  # Optional
    prev: /mtrack/prev  # Optional
    # ... other events

MIDI Controller

1
2
3
4
5
6
7
8

controllers:
  - kind: midi
    play:
      type: control_change
      channel: 16
      controller: 100
      value: 0
    # ... other events

Status Events

status_events

Type: Object
Description: MIDI events for controller feedback.

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

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

Track Mappings

track_mappings

Type: Object
Description: Map track names to output channels.

1
2
3
4
5
6

track_mappings:
  click: [1]
  cue: [2]
  backing-track-l: [3]
  backing-track-r: [4]
  keys: [5, 6]  # Multiple channels

Song Configuration

See Song Configuration documentation for song-level configuration options.

Playlist Format

A playlist is a simple YAML file:

1
2
3
4

songs:
  - Song Name 1
  - Song Name 2
  - Song Name 3