Automation Scheduling
Timing explained what the timing statements mean. This chapter explains how ORIX DJ actually runs an automation: when it starts, how its pieces are scheduled, how its commands reach the audio engine on time, and what pausing, stopping and failing do.
The life of an automation
| State | Meaning |
|---|---|
| running | It is being executed, or it is waiting for a position or an event. |
| paused | Its timeline is frozen. |
| finished | It had nothing left to do. |
| stopped | A stop statement ran, or you stopped it. |
| failed | A run-time error cancelled it. |
An automation is finished when all of these are true: its main sequence has ended, every block scheduled with at has ended, every ramp has reached its target, and no event handler is registered.
Several automations can run at the same time. Each has its own timeline, variables, ramps and handlers. They are not aware of each other; if two of them write the same control, each write simply takes effect when it happens.
Start: quantize
Starting an automation fixes its beat 0, the instant called "bar 1, beat 1" in the script.
| Header | Beat 0 |
|---|---|
no quantize, or quantize none |
The position of the master clock when the automation is started |
quantize beat |
The next whole beat of the master clock |
quantize bar |
The next bar line of the master clock |
If the start falls exactly on a line, that line is used. Between the launch and beat 0 the automation exists but does nothing; this is the "nothing happens" that people notice with quantize bar, and it lasts at most one bar.
automation "On The One" quantize bar {
deck.A.eq.low = -26dB
wait 1 bar
deck.A.eq.low = 0dB
}Lines typed in the console are never quantized: they run at once.
Tasks
Inside one automation, several things can be in progress at the same time. Each is a task with its own cursor:
- the main sequence (the body of the automation);
- each block scheduled with
at, from its position until its end; - each run of an event handler.
A task runs until it reaches a statement that takes time (wait, over, the pause between two turns of every), then sleeps until the beat at which it must continue. Tasks never run at literally the same time: at any instant the runtime executes one task until it sleeps or ends, then the next.
at bar 2 { // task 2: starts 4 beats in
over 2 bars { deck.A.eq.high -> -12dB }
deck.A.eq.high = 0dB
}
at bar 3 { deck.A.eq.low = -26dB } // task 3: starts 8 beats in
over 4 bars { deck.A.filter.highpass -> 1kHz } // task 1, the main sequence
deck.A.filter.highpass = 20Hz
deck.A.eq.low = 0dBOrder at the same beat
When several tasks are due at the same beat, they run in the order in which they were created: the main sequence first, then scheduled blocks and handler runs in the order they were scheduled. Within a task, statements run in the order written. Ramps that end at that beat are completed before any of these tasks.
This makes "same beat" situations predictable. If the example above also scheduled an at bar 5 block, that block would run 16 beats in, after the statements of the main sequence that are due at the same beat.
Limits
At most 256 tasks can be pending at once in one automation (E-LIMIT), and at most 128 ramps.
Ramps
A ramp is not a task. Once started by over, it is kept in a list and updated at every scheduler step: the runtime computes where the control should be at that moment and sends the value, asking the engine to glide to it over the length of one step. At the end beat the exact target is written.
- A ramp that ends at a given beat is completed before any task that is due at that beat runs: its exact target is written first, and a
rampEndline is traced. The statement after anoverblock therefore finds the control on its target. - A control has one ramp at most. A new ramp on the same control replaces the old one.
path = valueon a ramping control removes its ramp.- Ramp updates are not counted in the limit of commands per beat.
- When an automation is stopped, its ramps stop where they are. Controls are not put back.
at in detail
When the cursor reaches an at statement:
- The position is computed (
barandbeatcount from 1 at beat 0 of the automation; a duration is an offset from beat 0;nextBeatandnextBarare lines of the master clock). - The current values of the variables are copied for the block.
- A task is created to run the block at that position.
- The cursor continues with the next statement immediately.
If the position is earlier than the cursor, the block runs at once and a warning is logged with the number of beats by which it was late.
var level = -6dB
for position in [2, 3, 4] {
at bar position { deck.A.eq.mid = level } // -6, -9, -12 dB at bars 2, 3, 4
level = level - 3dB
}
wait until bar 5
deck.A.eq.mid = 0dBThe master clock
All positions are beats of the master clock.
- While a deck with a beat grid is playing as master deck, the clock follows it: its tempo is the tempo of that deck (track tempo × playback rate) and its beats and bar lines are locked to the deck's grid.
- The master deck is the one chosen explicitly as master if it is playing; otherwise the current master as long as it plays; otherwise the first playing deck with a beat grid.
- With no such deck, the clock runs free at its own tempo (
master.bpm, writable). - The clock never goes backwards. If the master deck jumps, loops or changes, the clock keeps counting forward and realigns its phase to the new grid.
Consequences for scripts:
- Waiting "8 bars" means eight bars of the master deck's music, even if its tempo changes during the wait.
- If the master deck is paused during an automation (many transitions end with
deck.A.pause()), another playing deck becomes master and the clock continues with it. Sync the incoming deck first so that the handover is seamless. - Looping the master deck does not loop the clock: the automation's timeline keeps advancing.
Live delivery: look-ahead and exact samples
Live, the runtime runs on its own scheduler thread, never on the audio thread.
- Every 4 milliseconds the scheduler asks the engine for the position of the master clock.
- It advances every running automation up to a point slightly ahead of the clock: 15 milliseconds by default. Everything due within that window is executed now.
- Each parameter change and action is sent to the audio engine stamped with the exact sample at which its beat occurs.
- The audio thread applies each command when it reaches that sample.
So the precision of a scripted action does not depend on when the scheduler happened to wake up: a deck.B.play() scheduled for a bar line is applied on the sample of that bar line. The engine measures how many commands arrived after their sample had passed, and by how much; those figures are part of the scheduler statistics (Performance Guidelines).
What look-ahead implies:
- A value read by a script (
deck.A.playing,deck.A.remaining) is the state at the time the scheduler ran, up to the look-ahead (30 ms by default) before the beat for which the statement is scheduled. - A console line or a trigger handler acts as soon as possible: it cannot be earlier than "now".
- An event (track end, trigger) is delivered at the scheduler step after it occurs.
If the engine refuses a parameter write (for example deck.X.bpm on a track without a beat grid, or an effect parameter when the rack is full), the script keeps running and a warning line from the source engine is added to the automation log.
A deck started with play() while sync and quantize are on is additionally aligned to the beat phase of the master deck by the engine.
In the simulator there is no audio; time advances in steps of 1/16 beat, tasks run at their exact beats, and ramps are sampled at each step.
Pause and resume
Pausing an automation freezes its timeline. While paused:
- nothing is executed, and ramps stop moving (controls hold their current value);
- events and triggers are not delivered to it and are not kept;
- the decks, the clock and the audio continue normally.
Resuming shifts everything that was pending (sleeping tasks, ramps, the automation's own beat 0) by the time spent paused. A 4-bar wait paused after 1 bar still has 3 bars to go after the resume.
The shift is the paused time, whatever it was, so a resumed automation is in general no longer aligned to the bar lines. Resume on a bar line if the alignment matters, or let the script realign itself with wait nextBar.
> pause "Eight Bar Transition"
Paused
> resume "Eight Bar Transition"
ResumedStop
An automation stops when:
- a
stopstatement runs in any of its tasks; - you stop it:
stop "Name",stoporstop allin the console; - the emergency stop is used.
Stopping cancels every task, ramp and handler of the automation at once. Nothing is restored: controls stay where they are, effects stay on, decks keep playing. If a transition is stopped halfway, both faders are halfway. Put things back by hand, or run a small "reset" automation of your own.
automation "Reset Channel A" {
deck.A.volume = 0dB
deck.A.eq.low = 0dB
deck.A.eq.mid = 0dB
deck.A.eq.high = 0dB
deck.A.filter.highpass = 20Hz
deck.A.filter.lowpass = 20kHz
}Emergency stop
panic in the console, or a control mapped to "Emergency stop", stops every automation and bypasses every effect in every rack. Decks keep playing, and faders and EQ are not touched. Use it when a script is doing something you do not want and you have no time to find out which one.
Failure
A run-time error (for example an action on an empty deck) cancels the automation: all its tasks, ramps and handlers are removed and its state becomes failed. In addition, every effect that the automation had switched on (with enable(), toggle() or enabled = true) and had not yet switched off is switched off, so that a broken script cannot leave the mix processed. The log shows the error with its line and code, and a warning for each effect bypassed.
Other controls are left as they are, as with a stop. See Error Handling.
Length known in advance
When every duration in an automation is a constant number of beats and it uses no events, the compiler knows its total length, and the scheduler can show progress ("beat 12 of 32"). The length is unknown when the script waits in seconds, uses wait nextBar or wait until, calls a procedure whose length depends on an argument, has branches of different lengths, or registers handlers. That affects only the display.