SPB Git

Repository Public

events.md 7.2 KB

# Events

So far every statement happened at a position that the script decided. An event handler is the opposite: a block that runs when something happens in the rig. A track reaches its end, a deck starts, the clock crosses a bar line, you hit a pad.

# on

orixdj
on deck.A.trackEnd {
    deck.B.play()
}

on registers a handler and takes no time: the cursor moves on to the next statement. From then on, each time the event occurs, the block runs.

Add once to handle only the first occurrence. The handler is removed after it has fired.

orixdj
on deck.A.trackEnd once {
    deck.B.play()
    stop
}

# Deck events

Written on deck.X.<event> { … }, with X one of A, B, C, D, or a variable of type deck.

Event Fires when
deck.X.trackEnd The playhead reached the end of the track. The deck stops; a pause event follows.
deck.X.play The deck started playing.
deck.X.pause The deck paused, including at the end of the track and at the end of a brake.
deck.X.loaded A track finished loading on the deck.
deck.X.beat The playhead crossed a beat of the track's own beat grid.

# Global events

Event Fires when
beat Every beat of the master clock.
bar Every bar line of the master clock (every fourth beat of its counter).
trigger(n) Automation trigger n was fired, with n from 1 to 16. Triggers are fired from a MIDI mapping, the keyboard, or the console command trigger n.
orixdj
on beat { print("beat") }
on bar { print("bar") }
on trigger(1) { print("pad 1") }
wait 2 bars
stop

deck.X.beat and beat are not the same thing. beat follows the master clock; deck.A.beat follows the grid of the track on deck A, at that deck's own tempo. They coincide when deck A is the master deck or is synced.

The trigger number may be an expression; it is evaluated once, when the on statement runs.

# An automation with handlers stays alive

An automation finishes when it has nothing left to do: no statement to run, no scheduled block, no ramp, and no handler. A registered handler is something left to do, so an automation with handlers keeps running after its last statement, until:

  • a stop statement runs (anywhere: in the main sequence, in a scheduled block or in a handler);
  • you stop it (the console command stop, or the emergency stop);
  • all its handlers were declared once and have all fired.
orixdj
automation "Start B When A Ends" {
    on deck.A.trackEnd once {
        deck.B.play()
    }
    // The main sequence ends here, but the automation waits for the event.
    // After the handler has fired once, nothing is left and the automation finishes.
}
orixdj
automation "Count Bars" {
    var barCount = 0
    on bar {
        barCount = barCount + 1
        if barCount == 16 {
            print("sixteen bars")
            stop                 // without this the automation would never end
        }
    }
}

status in the console lists running automations; an automation waiting for events shows as running with nothing pending.

The simulator stops after a fixed number of beats even if the automation is still alive (256 by default). That is reported as a timeout, not as an error.

# Where on can be written

  • In an automation: at the top level, inside if, inside an at block, inside another handler.
  • Not inside a loop (repeat, for, while, every): E-EVENT.
  • Not inside a function: E-EVENT.
  • Not inside over: E-OVER.
  • At most 32 handlers per automation (E-LIMIT).

A handler exists from the moment its on statement is executed. Events that occurred before are not remembered. If you register a handler after a wait, it only sees what happens after that wait.

orixdj
wait 4 bars
on trigger(2) once { deck.A.eq.low = -26dB }      // a trigger fired during the wait was not seen
wait 4 bars
deck.A.eq.low = 0dB
stop

# What a handler can do

A handler body is an ordinary block with its own cursor. It may wait, ramp, schedule, loop and call functions, without delaying the main sequence or the other handlers.

orixdj
on trigger(1) {
    fx.echo.mix = 0.7
    fx.echo.enable()
    wait 1 beat
    over 1 bar { fx.echo.mix -> 0 }
    fx.echo.disable()
}
wait 8 bars
stop

# Handlers share the automation's variables

Unlike an at block, a handler does not take a snapshot. It reads and writes the automation's variables directly, so handlers can cooperate with each other and with the main sequence.

orixdj
var armed = false
on trigger(1) { armed = true }
on bar {
    if armed {
        armed = false
        deck.A.loop(4 beats)
        wait 1 bar
        deck.A.loopExit()
    }
}
wait 8 bars
stop

Here a pad hit at any moment arms the effect, and the loop starts on the next bar line.

# If an event fires again while its handler is still running

Each occurrence starts a new run of the handler; runs do not wait for each other. A handler that takes two bars, attached to an event that fires every bar, will have two runs in progress at any time.

Up to 64 handler runs can be in progress at once in one automation. Occurrences beyond that are dropped, and counted in the run statistics as dropped events. If you see dropped events, the handlers take longer than the interval between events: shorten them or use a flag variable, as in the example above, to ignore events while busy.

# Order at the same instant

When several things are due at the same beat, the one that was scheduled first runs first. A handler run started by an event at beat 8 therefore runs after the main sequence's statement that is also due at beat 8.

# Events and time

  • Deck events are delivered at the scheduler step after they occur, so a handler runs a few milliseconds after its cause. beat and bar handlers are scheduled at the exact beat.
  • Events are not delivered to a paused automation; they are not kept for later.
  • A trigger fired when no automation has a handler for it is ignored.

# Useful patterns

# Do something once, on the next bar line

orixdj
on bar once {
    deck.A.eq.low = -26dB
    wait 1 bar
    deck.A.eq.low = 0dB
}

# React before the end of a track

There is no "30 seconds left" event, but a bar handler can look at the deck.

orixdj
var warned = false
on bar {
    if not warned and deck.A.playing and deck.A.remaining < 30s {
        warned = true
        print("deck A: less than 30 seconds left")
    }
}
wait 16 bars
stop

# A pad that toggles an effect

orixdj
on trigger(3) { fx.flanger.toggle() }
wait 16 bars
fx.flanger.disable()
stop

# Chain decks

orixdj
automation "Ping Pong Decks" {
    on deck.A.trackEnd { deck.B.play() }
    on deck.B.trackEnd { deck.A.play() }
}

This automation runs until you stop it.

# Errors

orixdj-error
on deck.A.finished { deck.B.play() }
text
Unknown deck event 'finished'. Events: trackEnd, play, pause, loaded, beat. [E-EVENT]
orixdj-error
repeat 4 {
    on beat { print("tick") }
}
text
Event handlers cannot be declared inside a loop. [E-EVENT]
Files main
Menu

Theme