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
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.
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. |
on beat { print("beat") }
on bar { print("bar") }
on trigger(1) { print("pad 1") }
wait 2 bars
stopdeck.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
stopstatement 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
onceand have all fired.
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.
}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 anatblock, 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.
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
stopWhat 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.
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
stopHandlers 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.
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
stopHere 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.
beatandbarhandlers 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
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.
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
stopA pad that toggles an effect
on trigger(3) { fx.flanger.toggle() }
wait 16 bars
fx.flanger.disable()
stopChain decks
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
on deck.A.finished { deck.B.play() }Unknown deck event 'finished'. Events: trackEnd, play, pause, loaded, beat. [E-EVENT]repeat 4 {
on beat { print("tick") }
}Event handlers cannot be declared inside a loop. [E-EVENT]