Song Configuration

How to configure songs in your mtrack repository

Song Configuration

Songs in mtrack are defined using YAML (or other config-rs supported formats) and can include multiple audio tracks, MIDI playback, and lighting shows.

Song Structure

A song consists of:

  • One or more audio files
  • An optional MIDI file
  • One or more light shows (using .light DSL files, or legacy MIDI files)
  • A song definition file

Song Definition Format

Here’s a complete example of a song definition:

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51

# The name of the song (used in playlists)
name: The Song Name

# Optional MIDI event to emit when song is selected
midi_event:
  type: program_change
  channel: 16
  program: 3

# Light shows using the new DSL format (.light files)
lighting:
  - file: lighting/main_show.light
  - file: lighting/outro.light

# Legacy MIDI-based light shows (still supported)
# light_shows:
#   - universe_name: light-show
#     dmx_file: DMX Light Show.mid
#     midi_channels:
#       - 15

# Optional MIDI playback configuration
midi_playback:
  file: Song Automation.mid
  exclude_midi_channels:
    - 15  # Exclude lighting data from MIDI playback

# The tracks associated with this song
tracks:
  # Single channel track
  - name: click
    file: click.wav  # Relative to song config file
  
  # Another single channel track
  - name: cue
    file: /mnt/song-storage/cue.wav  # Or absolute path
  
  # Multi-channel file - specify which channel to use
  - name: backing-track-l
    file: Backing Tracks.wav
    file_channel: 1
  
  # Reuse the same file for stereo
  - name: backing-track-r
    file: Backing Tracks.wav
    file_channel: 2
  
  # Keys track
  - name: keys
    file: Keys.wav
    file_channel: 1

Track Configuration

Single Channel Tracks

For audio files with a single channel, just specify the name and file:

1
2
3

tracks:
  - name: click
    file: click.wav

Multi-Channel Tracks

For audio files with multiple channels, specify which channel to use:

1
2
3
4
5
6
7
8

tracks:
  - name: backing-track-l
    file: Backing Tracks.wav
    file_channel: 1  # Use channel 1 (left)
  
  - name: backing-track-r
    file: Backing Tracks.wav
    file_channel: 2  # Use channel 2 (right)

File Paths

File paths can be:

  • Relative: Relative to the song configuration file location
  • Absolute: Full path from the filesystem root

MIDI Events on Selection

You can emit a MIDI event when a song is selected (even if not playing). This is useful for triggering events on remote devices:

1
2
3
4

midi_event:
  type: program_change
  channel: 16
  program: 3

See MIDI Events Reference for all supported event types.

MIDI Playback

Play a MIDI file along with your audio:

1
2
3
4

midi_playback:
  file: Song Automation.mid
  exclude_midi_channels:
    - 15  # Exclude specific MIDI channels

This is useful for automating on-stage gear like synthesizers, effects units, etc.

Lighting Shows

Use .light files with the lighting DSL:

1
2
3

lighting:
  - file: lighting/main_show.light
  - file: lighting/outro.light

See the Light Shows documentation for details.

Legacy MIDI Format

You can still use MIDI files for lighting:

1
2
3
4
5

light_shows:
  - universe_name: light-show
    dmx_file: DMX Light Show.mid
    midi_channels:
      - 15  # Only use MIDI channel 15 for lighting

Requirements

  • All audio files must have the same sample rate
  • Audio files don’t need to be the same length - mtrack plays until the last file completes
  • File formats: WAV is recommended, but other formats supported by your audio backend may work

Generating Song Configurations

You can auto-generate song configurations:

1

mtrack songs --init /path/to/song-repository

This creates a song.yaml in each subdirectory using:

  • Folder name as song name
  • WAV files as tracks (track name from filename)
  • MIDI files for MIDI playback
  • Files starting with dmx_ for light shows

You can then edit these files to refine the configuration.

Testing Songs

View all songs in your repository:

1

mtrack songs /path/to/song-repository

Play a song directly:

1

mtrack play-direct -d audio-device click=1,cue=2 /path/to/songs "Song Name"