Light Shows

Creating and managing lighting shows with the mtrack DSL

Light Shows

Light shows in mtrack are created using a domain-specific language (DSL) that allows you to define lighting effects, cues, and timing in a readable, maintainable format.

Show Structure

A light show file (.light) has this basic structure:

show "Show Name" {
    @00:00.000
    front_wash: static color: "red", dimmer: 100%
    
    @00:05.000
    movers: cycle color: "red", color: "blue", speed: 2.0
}

Timing

Time-Based Cues

Use absolute time in two formats:

Format 1: Minutes:Seconds.Milliseconds

@00:05.000    # 5 seconds
@01:23.456    # 1 minute, 23.456 seconds

Format 2: Seconds.Milliseconds

@5.000        # 5 seconds
@83.456       # 83.456 seconds

Measure-Based Cues

When a tempo section is defined, use measure/beat notation:

@1/1         # Measure 1, beat 1
@2/3         # Measure 2, beat 3
@4/1.5       # Measure 4, halfway through beat 1

Tempo Sections

Define BPM and time signature:

tempo {
    start: 0.0s
    bpm: 120
    time_signature: 4/4
    changes: [
        @8/1 { bpm: 140 },
        @16/1 { bpm: 160, transition: 4 },
        @24/1 { time_signature: 3/4 }
    ]
}

Effect Types

Static Effect

Sets fixed parameter values:

@00:05.000
front_wash: static color: "red", dimmer: 80%

@00:10.000
back_wash: static red: 100%, green: 50%, blue: 0%, dimmer: 60%, duration: 5s

Color Cycle Effect

Cycles through colors:

@00:10.000
movers: cycle color: "red", color: "blue", color: "green", speed: 2.0, direction: forward, transition: fade

Strobe Effect

Rapid flashing:

@00:15.000
strobes: strobe frequency: 8, duration: 2s

@01:00.000
all_lights: strobe frequency: 1beat, duration: 4measures

Pulse Effect

Smooth dimmer pulsing:

@00:20.000
front_wash: pulse base_level: 50%, pulse_amplitude: 50%, frequency: 1.5, duration: 5s

Chase Effect

Moves effect across fixtures:

@00:25.000
movers: chase pattern: linear, speed: 2.0, direction: left_to_right, transition: fade

Dimmer Effect

Smooth dimmer transition:

@00:30.000
all_lights: dimmer start_level: 100%, end_level: 0%, duration: 3s, curve: sine

Rainbow Effect

Continuous rainbow cycle:

@00:35.000
all_lights: rainbow speed: 1.0, saturation: 100%, brightness: 80%

Common Effect Parameters

All effects support:

  • layer: background, midground, or foreground
  • blend_mode: replace, multiply, add, overlay, screen
  • up_time: Fade-in duration (e.g., 2s, 1beat)
  • hold_time: Duration at full intensity
  • down_time: Fade-out duration

Loops

Inline Loops

Repeat a block of cues:

@00:10.000
loop {
    @0.000
    front_wash: static color: "red", dimmer: 100%
    
    @0.500
    front_wash: static color: "blue", dimmer: 100%
    
    @1.000
    front_wash: static color: "green", dimmer: 100%
} repeats: 4

Sequences

Define reusable cue sequences:

sequence "Verse Pattern" {
    @1/1
    front_wash: static color: "blue", dimmer: 80%
    
    @2/1
    front_wash: static color: "red", dimmer: 100%
    
    @4/1
    front_wash: static color: "blue", dimmer: 80%
}

show "Song" {
    @1/1
    sequence "Verse Pattern"
    
    @17/1
    sequence "Verse Pattern"
    
    @33/1
    sequence "Verse Pattern", loop: 2
}

Measure Offsets

Shift the measure counter:

@8/1
offset 4 measures    # Shift forward by 4 measures

@12/1
reset_measures      # Reset to actual playback time

Useful for aligning with composition tools that use repeats.

Stopping Sequences

Stop a running sequence:

@00:30.000
stop sequence "Verse Pattern"

Color Formats

Colors can be specified as:

  • Named colors: "red", "blue", "green"
  • Hex: #FF0000
  • RGB: rgb(255,0,0)

Duration Formats

Durations can be:

  • Time: 5s, 2.5s, 100ms
  • Tempo-aware: 1beat, 2beats, 1measure, 2measures

Example Show

tempo {
    start: 0.0s
    bpm: 120
    time_signature: 4/4
}

show "Main Show" {
    @00:00.000
    all_lights: static dimmer: 0%
    
    @00:05.000
    front_wash: static color: "blue", dimmer: 100%, up_time: 2s
    
    @00:10.000
    movers: cycle color: "red", color: "blue", color: "green", speed: 2.0
    
    @00:15.000
    strobes: strobe frequency: 8, duration: 2s
    
    @00:20.000
    all_lights: dimmer start_level: 100%, end_level: 0%, duration: 3s, curve: sine
}

Verification

Validate your light show:

1

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

Validate against configuration:

1

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