Repository Public
1# Automation Scheduling23[Timing](timing.md) 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.45## The life of an automation67| State | Meaning |8| --- | --- |9| running | It is being executed, or it is waiting for a position or an event. |10| paused | Its timeline is frozen. |11| finished | It had nothing left to do. |12| stopped | A `stop` statement ran, or you stopped it. |13| failed | A run-time error cancelled it. |1415An 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.1617Several 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.1819## Start: `quantize`2021Starting an automation fixes its beat 0, the instant called "bar 1, beat 1" in the script.2223| Header | Beat 0 |24| --- | --- |25| no `quantize`, or `quantize none` | The position of the master clock when the automation is started |26| `quantize beat` | The next whole beat of the master clock |27| `quantize bar` | The next bar line of the master clock |2829If 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.3031```orixdj32automation "On The One" quantize bar {33 deck.A.eq.low = -26dB34 wait 1 bar35 deck.A.eq.low = 0dB36}37```3839Lines typed in the console are never quantized: they run at once.4041## Tasks4243Inside one automation, several things can be in progress at the same time. Each is a **task** with its own cursor:4445- the main sequence (the body of the automation);46- each block scheduled with `at`, from its position until its end;47- each run of an event handler.4849A 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.5051```orixdj52at bar 2 { // task 2: starts 4 beats in53 over 2 bars { deck.A.eq.high -> -12dB }54 deck.A.eq.high = 0dB55}56at bar 3 { deck.A.eq.low = -26dB } // task 3: starts 8 beats in57over 4 bars { deck.A.filter.highpass -> 1kHz } // task 1, the main sequence58deck.A.filter.highpass = 20Hz59deck.A.eq.low = 0dB60```6162### Order at the same beat6364When 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.6566This 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.6768### Limits6970At most 256 tasks can be pending at once in one automation (`E-LIMIT`), and at most 128 ramps.7172## Ramps7374A 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.7576- 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 `rampEnd` line is traced. The statement after an `over` block therefore finds the control on its target.77- A control has one ramp at most. A new ramp on the same control replaces the old one.78- `path = value` on a ramping control removes its ramp.79- Ramp updates are not counted in the limit of commands per beat.80- When an automation is stopped, its ramps stop where they are. Controls are not put back.8182## `at` in detail8384When the cursor reaches an `at` statement:85861. The position is computed (`bar` and `beat` count from 1 at beat 0 of the automation; a duration is an offset from beat 0; `nextBeat` and `nextBar` are lines of the master clock).872. The current values of the variables are copied for the block.883. A task is created to run the block at that position.894. The cursor continues with the next statement immediately.9091If 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.9293```orixdj94var level = -6dB95for position in [2, 3, 4] {96 at bar position { deck.A.eq.mid = level } // -6, -9, -12 dB at bars 2, 3, 497 level = level - 3dB98}99wait until bar 5100deck.A.eq.mid = 0dB101```102103## The master clock104105All positions are beats of the master clock.106107- 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.108- 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.109- With no such deck, the clock runs free at its own tempo (`master.bpm`, writable).110- 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.111112Consequences for scripts:113114- Waiting "8 bars" means eight bars of the master deck's music, even if its tempo changes during the wait.115- 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.116- Looping the master deck does not loop the clock: the automation's timeline keeps advancing.117118## Live delivery: look-ahead and exact samples119120Live, the runtime runs on its own scheduler thread, never on the audio thread.1211221. Every 4 milliseconds the scheduler asks the engine for the position of the master clock.1232. 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.1243. Each parameter change and action is sent to the audio engine stamped with the exact sample at which its beat occurs.1254. The audio thread applies each command when it reaches that sample.126127So 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](performance.md)).128129What look-ahead implies:130131- 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.132- A console line or a trigger handler acts as soon as possible: it cannot be earlier than "now".133- An event (track end, trigger) is delivered at the scheduler step after it occurs.134135If 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.136137A deck started with `play()` while `sync` and `quantize` are on is additionally aligned to the beat phase of the master deck by the engine.138139In 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.140141## Pause and resume142143Pausing an automation freezes its timeline. While paused:144145- nothing is executed, and ramps stop moving (controls hold their current value);146- events and triggers are not delivered to it and are not kept;147- the decks, the clock and the audio continue normally.148149Resuming 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.150151The 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`.152153```console154> pause "Eight Bar Transition"155Paused156> resume "Eight Bar Transition"157Resumed158```159160## Stop161162An automation stops when:163164- a `stop` statement runs in any of its tasks;165- you stop it: `stop "Name"`, `stop` or `stop all` in the console;166- the emergency stop is used.167168Stopping 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.169170```orixdj171automation "Reset Channel A" {172 deck.A.volume = 0dB173 deck.A.eq.low = 0dB174 deck.A.eq.mid = 0dB175 deck.A.eq.high = 0dB176 deck.A.filter.highpass = 20Hz177 deck.A.filter.lowpass = 20kHz178}179```180181## Emergency stop182183`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.184185## Failure186187A 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.188189Other controls are left as they are, as with a stop. See [Error Handling](errors.md).190191## Length known in advance192193When 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.194195## Related196197- [Timing](timing.md)198- [Beats and Bars](beats-and-bars.md)199- [Events](events.md)200- [Console Usage](console.md)201- [Performance Guidelines](performance.md)202- [Error Handling](errors.md)203