Usage Guide

This guide covers the basic usage of mtrack, including playing songs, managing playlists, and controlling playback.

Player Behavior

mtrack follows a specific behavior loop:

Startup: mtrack starts on the first item in your playlist. The item is selected, but not playing.
Navigation: While no song is playing, you can navigate the playlist using next and previous events. These are inactive when a song is playing.
Playback: Use the play event to start a song, and stop to stop a currently playing song. While a song is playing, play does nothing; while stopped, stop does nothing.
Playlist Switching: Use all_songs to switch to a playlist of all songs in your repository, or playlist to return to your defined playlist.

Starting the Player

Start mtrack with your configuration file:

1

mtrack start /path/to/mtrack.yaml

The player will start and wait for control events.

Playing Songs Directly

You can play a song directly without starting the full player:

1

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

Options:

-d, --device: Audio device name
-m, --midi-device: MIDI device name (optional)
-s, --dmx-dim-speed: DMX dimming speed modifier
--dmx-universe-config: DMX universe configuration

Controlling Playback

Via MIDI

Configure MIDI control events in your configuration file, then send the appropriate MIDI messages from your foot controller.

Via gRPC

Use the mtrack command-line interface:

1
2
3
4
5
6
7
8


mtrack play
mtrack play --from "1:23.456"  # Start from specific time
mtrack previous
mtrack next
mtrack stop
mtrack switch-to-playlist all_songs
mtrack switch-to-playlist playlist
mtrack status

Via OSC

Send OSC messages to the configured OSC port. Default addresses:

/mtrack/play - Start playback
/mtrack/prev - Previous song
/mtrack/next - Next song
/mtrack/stop - Stop playback
/mtrack/all_songs - Switch to all songs playlist
/mtrack/playlist - Switch to defined playlist

Playlists

Playlist Format

A playlist is a simple YAML file:

1
2
3
4
5
6
7


songs:
  - Sound check
  - A really cool song
  - Another cool song
  - The slow one
  - A really fast one
  - Outro tape

Songs are played in the order listed, but you must trigger each song manually.

Viewing Songs

List all songs in your repository:

1

mtrack songs /path/to/song-repository

This shows:

Song names
Duration
Number of channels
Sample rate
MIDI message (if configured)
MIDI file (if configured)
Track names

Generating Song Configurations

Generate default song configurations from your audio files:

1

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

This creates a song.yaml file in each subdirectory, using:

Folder name as song name
WAV files as tracks
MIDI files for MIDI playback
Files starting with dmx_ for light shows

Status Information

Player Status

Check the current player status:

1

mtrack status

Active Effects

View active lighting effects:

1

mtrack active-effects

Cues

List all cues in the current song’s lighting timeline:

1

mtrack cues

Device Discovery

Audio Devices

List available audio devices:

1

mtrack devices

Output format:

Devices:
- DeviceName (Channels=22) (Alsa)

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

MIDI Devices

List available MIDI devices:

1

mtrack midi-devices