Lighting System

mtrack supports advanced lighting control through DMX (Digital Multiplex) using the Open Lighting Architecture (OLA). The system supports both a modern tag-based venue-agnostic approach and legacy MIDI-based DMX.

Overview

mtrack’s lighting system provides:

• Venue-Agnostic Songs: Songs use logical groups instead of specific fixture names
• Tag-Based Group Resolution: Fixtures are tagged with capabilities and roles
• Intelligent Selection: System automatically chooses optimal fixtures based on constraints
• Venue Portability: Same lighting show works across different venues
• Performance Optimization: Cached group resolutions for fast lookups

Architecture

The lighting system uses a three-layer architecture:

1. Configuration Layer: Define logical groups with constraints in mtrack.yaml
2. Venue Layer: Tag physical fixtures with capabilities in DSL files
3. Song Layer: Reference .light DSL files in song YAML files, which use logical groups

Prerequisites

OLA Setup

mtrack requires OLA (Open Lighting Architecture) to be installed and running:

1
2
3
4
5

# Install OLA (example for Debian/Ubuntu)
sudo apt-get install ola ola-python

# Start OLA
sudo systemctl start olad

Follow the OLA tutorial to configure your DMX interfaces.

Configuration

Main Configuration (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
38
39
40
41
42
43
44

dmx:
  dim_speed_modifier: 0.25
  playback_delay: 500ms
  
  # Lighting system configuration
  lighting:
    current_venue: "main_stage"
    
    # Simple inline fixture definitions
    fixtures:
      emergency_light: "Emergency @ 1:500"
    
    # Logical groups with role-based constraints
    groups:
      front_wash:
        name: "front_wash"
        constraints:
          - AllOf: ["wash", "front"]
          - MinCount: 4
          - MaxCount: 8
      
      movers:
        name: "movers"
        constraints:
          - AnyOf: ["moving_head", "spot"]
          - Prefer: ["premium"]
          - MinCount: 2
          - MaxCount: 4
      
      all_lights:
        name: "all_lights"
        constraints:
          - AnyOf: ["wash", "moving_head", "spot", "strobe", "beam"]
          - MinCount: 1
    
    # Directory configuration
    directories:
      fixture_types: "lighting/fixture_types"
      venues: "lighting/venues"
  
  # Universe mappings
  universes:
    - universe: 1
      name: light-show

Fixture Type Definitions

Create fixture type definitions in lighting/fixture_types/:

fixture_type "RGBW_Par" {
  channels: 4
  channel_map: {
    "dimmer": 1,
    "red": 2,
    "green": 3,
    "blue": 4
  }
  special_cases: ["RGB", "Dimmer"]
}

fixture_type "MovingHead" {
  channels: 16
  channel_map: {
    "dimmer": 1,
    "pan": 2,
    "pan_fine": 3,
    "tilt": 4,
    "tilt_fine": 5,
    "color_wheel": 6,
    "gobo_wheel": 7,
    # ... more channels
  }
  special_cases: ["MovingHead", "Spot", "Dimmer", "Strobe"]
}

Venue Definitions

Create venue definitions in lighting/venues/:

venue "main_stage" {
  fixture "Wash1" RGBW_Par @ 1:1 tags ["wash", "front", "rgb", "premium"]
  fixture "Wash2" RGBW_Par @ 1:7 tags ["wash", "front", "rgb", "premium"]
  fixture "Mover1" MovingHead @ 1:37 tags ["moving_head", "spot", "premium"]
  fixture "Strobe1" Strobe @ 1:85 tags ["strobe", "front"]
}

Constraint Types

AllOf

All specified tags must be present:

1
2

constraints:
  - AllOf: ["wash", "front"]

AnyOf

Any of the specified tags must be present:

1
2

constraints:
  - AnyOf: ["moving_head", "spot"]

Prefer

Prefer fixtures with these tags:

1
2

constraints:
  - Prefer: ["premium"]

MinCount / MaxCount

Specify minimum and maximum fixture counts:

1
2
3

constraints:
  - MinCount: 4
  - MaxCount: 8

FallbackTo

Fallback to another group if primary fails:

1
2

constraints:
  - FallbackTo: "all_lights"

AllowEmpty

Allow group to be empty if no fixtures match:

1
2

constraints:
  - AllowEmpty: true

Light Shows

Light shows are defined in .light files using the DSL format. Songs reference these files:

1
2
3
4

# In song.yaml
lighting:
  - file: lighting/main_show.light
  - file: lighting/outro.light

See the Light Shows documentation for details on creating shows.

Legacy MIDI-Based DMX

For existing MIDI-based lighting shows, you can still use the legacy format:

1
2
3
4
5
6

# In song.yaml
light_shows:
  - universe_name: light-show
    dmx_file: DMX Light Show.mid
    midi_channels:
      - 15

MIDI to DMX Conversion

MIDI events are converted to DMX as follows:

Dimming Engine

The dimming engine is controlled by Program Change (PC) commands:

• PC value × dimming speed modifier = dimming duration
• PC 0 = instantaneous changes
• Subsequent note on/off events transition over the dimming duration
• Each channel dims independently

Verifying Light Shows

Validate your light show syntax:

1

mtrack verify-light-show path/to/show.light

Validate against your configuration:

1

mtrack verify-light-show path/to/show.light --config /path/to/mtrack.yaml

This checks:

• Light show syntax validity
• All referenced fixture groups exist
• All referenced fixtures exist

Related Documentation

• Light Shows - Creating lighting shows
• Configuration - Complete configuration reference
• MIDI Control - MIDI integration