SPB Git

Repository Public

events.md 7.2 KB 238 lines markdown

1# Events23So 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.45## `on`67```orixdj8on deck.A.trackEnd {9    deck.B.play()10}11```1213`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.1415Add `once` to handle only the first occurrence. The handler is removed after it has fired.1617```orixdj18on deck.A.trackEnd once {19    deck.B.play()20    stop21}22```2324## Deck events2526Written `on deck.X.<event> { … }`, with `X` one of A, B, C, D, or a variable of type `deck`.2728| Event | Fires when |29| --- | --- |30| `deck.X.trackEnd` | The playhead reached the end of the track. The deck stops; a `pause` event follows. |31| `deck.X.play` | The deck started playing. |32| `deck.X.pause` | The deck paused, including at the end of the track and at the end of a brake. |33| `deck.X.loaded` | A track finished loading on the deck. |34| `deck.X.beat` | The playhead crossed a beat of the track's own beat grid. |3536## Global events3738| Event | Fires when |39| --- | --- |40| `beat` | Every beat of the master clock. |41| `bar` | Every bar line of the master clock (every fourth beat of its counter). |42| `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`. |4344```orixdj45on beat { print("beat") }46on bar { print("bar") }47on trigger(1) { print("pad 1") }48wait 2 bars49stop50```5152`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.5354The trigger number may be an expression; it is evaluated once, when the `on` statement runs.5556## An automation with handlers stays alive5758An 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:5960- a `stop` statement runs (anywhere: in the main sequence, in a scheduled block or in a handler);61- you stop it (the console command `stop`, or the emergency stop);62- all its handlers were declared `once` and have all fired.6364```orixdj65automation "Start B When A Ends" {66    on deck.A.trackEnd once {67        deck.B.play()68    }69    // The main sequence ends here, but the automation waits for the event.70    // After the handler has fired once, nothing is left and the automation finishes.71}72```7374```orixdj75automation "Count Bars" {76    var barCount = 077    on bar {78        barCount = barCount + 179        if barCount == 16 {80            print("sixteen bars")81            stop                 // without this the automation would never end82        }83    }84}85```8687`status` in the console lists running automations; an automation waiting for events shows as running with nothing pending.8889The 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.9091## Where `on` can be written9293- In an automation: at the top level, inside `if`, inside an `at` block, inside another handler.94- Not inside a loop (`repeat`, `for`, `while`, `every`): `E-EVENT`.95- Not inside a function: `E-EVENT`.96- Not inside `over`: `E-OVER`.97- At most 32 handlers per automation (`E-LIMIT`).9899A 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.100101```orixdj102wait 4 bars103on trigger(2) once { deck.A.eq.low = -26dB }      // a trigger fired during the wait was not seen104wait 4 bars105deck.A.eq.low = 0dB106stop107```108109## What a handler can do110111A 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.112113```orixdj114on trigger(1) {115    fx.echo.mix = 0.7116    fx.echo.enable()117    wait 1 beat118    over 1 bar { fx.echo.mix -> 0 }119    fx.echo.disable()120}121wait 8 bars122stop123```124125### Handlers share the automation's variables126127Unlike 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.128129```orixdj130var armed = false131on trigger(1) { armed = true }132on bar {133    if armed {134        armed = false135        deck.A.loop(4 beats)136        wait 1 bar137        deck.A.loopExit()138    }139}140wait 8 bars141stop142```143144Here a pad hit at any moment arms the effect, and the loop starts on the next bar line.145146### If an event fires again while its handler is still running147148Each 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.149150Up 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.151152### Order at the same instant153154When 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.155156## Events and time157158- 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.159- Events are not delivered to a paused automation; they are not kept for later.160- A trigger fired when no automation has a handler for it is ignored.161162## Useful patterns163164### Do something once, on the next bar line165166```orixdj167on bar once {168    deck.A.eq.low = -26dB169    wait 1 bar170    deck.A.eq.low = 0dB171}172```173174### React before the end of a track175176There is no "30 seconds left" event, but a `bar` handler can look at the deck.177178```orixdj179var warned = false180on bar {181    if not warned and deck.A.playing and deck.A.remaining < 30s {182        warned = true183        print("deck A: less than 30 seconds left")184    }185}186wait 16 bars187stop188```189190### A pad that toggles an effect191192```orixdj193on trigger(3) { fx.flanger.toggle() }194wait 16 bars195fx.flanger.disable()196stop197```198199### Chain decks200201```orixdj202automation "Ping Pong Decks" {203    on deck.A.trackEnd { deck.B.play() }204    on deck.B.trackEnd { deck.A.play() }205}206```207208This automation runs until you stop it.209210## Errors211212```orixdj-error213on deck.A.finished { deck.B.play() }214```215216```text217Unknown deck event 'finished'. Events: trackEnd, play, pause, loaded, beat. [E-EVENT]218```219220```orixdj-error221repeat 4 {222    on beat { print("tick") }223}224```225226```text227Event handlers cannot be declared inside a loop. [E-EVENT]228```229230## Related231232- [Automation Scheduling](scheduling.md)233- [MIDI Integration](midi.md)234- [Variables](variables.md)235- [Timing](timing.md)236- [Deck Commands](deck-api.md)237- [Mixer Commands](mixer-api.md)238
Files main
Menu

Theme