Performance Guidelines
An automation runs next to live audio. ORIX DJ is built so that a script cannot disturb the sound, and it enforces fixed limits so that a script cannot run away. This chapter lists those limits, explains what happens when one is reached, and gives advice for writing scripts that stay far from them.
Why a script cannot glitch the audio
- The script runtime runs on its own scheduler thread. It never runs on the audio thread.
- The scheduler wakes every 4 milliseconds, advances each running automation up to 15 milliseconds ahead of the master clock, and hands the resulting parameter changes and actions to the audio engine with the exact sample at which each must apply.
- The audio thread only applies those time-stamped commands. It does not wait for the scheduler.
If a script does a lot of work in one step, the scheduler step takes longer; the audio continues. To keep even that under control, the runtime counts the work of every automation and stops one that exceeds its budget.
Limits checked before the script runs
| Limit | Value | Code when exceeded |
|---|---|---|
| Script size | 256 KB | E-LIMIT |
| Statements per script | 20000 | E-LIMIT |
| Nesting of blocks | 20 levels | E-LIMIT |
| Nesting of an expression | 20 levels | E-LIMIT |
Turns of one loop (repeat, for, every) |
10000 | E-LIMIT |
while limit |
a constant from 1 to 10000 | E-UNBOUNDED |
Shortest every period |
1/64 beat | E-LIMIT |
| Array length | 256 elements | E-LIMIT |
| Event handlers per automation | 32 | E-LIMIT |
| Variables per automation or function | 512 | E-LIMIT |
| String literal | 512 characters | E-LIMIT |
| A wait, ramp or position | 100000 beats | E-LIMIT |
| Recursion | not allowed | E-RECURSION |
Limits checked while the script runs
| Limit | Value | Code when exceeded |
|---|---|---|
| Operations in one scheduler step, without a wait | 20000 | E-BUDGET |
| Operations over the whole life of one automation | 5000000 | E-BUDGET |
| Parameter changes and actions within one beat (ramp updates not counted) | 512 | E-RATE |
| Pending tasks (scheduled blocks and handler runs) | 256 | E-LIMIT |
| Active ramps | 128 | E-LIMIT |
| Registered event handlers | 32 | E-LIMIT |
| Handler runs in progress; further events are dropped, not an error | 64 | – |
| Turns of one loop, when the count is computed | 10000 | E-LIMIT |
| Depth of function calls | 16 | E-LIMIT |
| A computed wait, ramp or position | 100000 beats | E-LIMIT |
A string built with + |
2048 characters | E-LIMIT |
Text of one print |
cut at 2048 characters | – |
These are the values of the standard configuration.
What counts as an operation
Roughly: each statement executed, each turn of a loop, each arithmetic, comparison or logical operator evaluated, each read of a live value, and each call of a builtin. A typical transition uses a few dozen operations in total. A bar handler that tests two conditions uses fewer than ten per bar.
What happens when a run-time limit is reached
E-BUDGET, E-RATE and the run-time E-LIMIT are run-time errors like any other:
- The automation is cancelled immediately: all its tasks, ramps and handlers are removed.
- Every effect it had switched on and not switched off is switched off, and the log shows a
bypassed … after the failureline for each. - The error is logged with the line that was executing.
Decks keep playing, other automations keep running, and the controls other than those effects stay where they were. The message for E-RATE says it plainly: the automation was stopped to protect the performance.
var total = 0
for a in 1...200 {
for b in 1...200 {
total = total + a * b
}
}
print(total)More than 20000 operations without a wait. Add a 'wait' inside the loop or reduce its work. [E-BUDGET]Dropped events are different: they do not stop anything. When an event fires while 64 runs of handlers are already in progress in that automation, that occurrence is skipped and counted. See Events.
Emergency stop
If something sounds wrong and you do not know why, use the emergency stop: panic in the console, or the control mapped to automation.panic. It stops every automation and bypasses every effect in every rack. Decks keep playing and faders are not touched.
Guidelines
Let time pass in loops
A loop without a wait does all its turns in one scheduler step. That is fine for small counts (scheduling 16 blocks, summing 8 numbers). For anything that writes controls, each turn should wait.
// Good: 32 steps spread over 2 bars
for step in 1...32 {
deck.A.filter.highpass = hz(100 + step * 50)
wait 1/4beat
}
deck.A.filter.highpass = 20HzPrefer a ramp to many small steps
over is cheaper and smoother than a loop of assignments: the runtime computes the value at each scheduler step, the engine glides between them, and ramp updates are not counted against the commands-per-beat limit.
// Better than the loop above when a continuous sweep is wanted
over 2 bars { deck.A.filter.highpass -> 1700Hz }
deck.A.filter.highpass = 20HzChoose the slowest event that does the job
on bar fires once per bar, on beat four times as often, on deck.X.beat once per beat of each deck. To notice that a track is ending, a bar handler is more than enough.
Keep handlers short
A handler run that lasts longer than the interval between its events overlaps with the next run. Use a flag variable to skip events while busy, or once when the handler is needed a single time.
Schedule what is known, compute what is not
Positions known in advance are best written as at blocks at the start: they cost nothing until they fire. Do not poll for something that has a fixed position.
Do the setup before the bar
Statements at the same instant are sent to the engine for the same sample, in order. Setting eight effect parameters and then calling enable() on the bar is fine. There is no need to spread them out.
Avoid many long-running automations
Each running automation is advanced at every scheduler step. A handful of them costs nothing measurable; dozens of forgotten event-driven automations add up and, more importantly, make it hard to know what is acting on the mix. Check status and stop what you no longer need.
Mind what several automations do to one control
Two automations ramping the same control fight: each writes its own value at every step and the control jitters between them. One automation should own a control at a time.
Use seconds sparingly
Seconds are converted to beats with the tempo of that moment. A script written in beats and bars stays aligned whatever the tempo does.
Measuring
ORIX DJ measures the scheduler while it runs. The figures available are:
| Figure | Meaning |
|---|---|
| Ticks | Number of scheduler steps |
| Last, average and maximum step time | Time spent per step, in microseconds |
| Maximum gap between steps | Scheduler jitter, in milliseconds (the nominal gap is 4 ms) |
| Active automations, pending tasks, active ramps | Current load |
| Started, finished, run-time errors, validation errors | Counters since the last reset |
| Tracked commands | Commands whose arrival time was measured by the audio thread |
| Late commands, maximum and mean lateness | Commands that reached the audio thread after their sample, and by how many samples |
| Dropped control events | Commands that could not be queued to the audio thread |
Per automation, the run statistics give: operations used, writes, ramp updates, actions, clamped values, dropped events, the largest number of tasks and of ramps at once, and the largest lateness in beats between the time a task was due and the time it ran.
Signs that a script should be simplified:
- late commands or dropped control events that appear only while it runs;
- a maximum step time that approaches the 4 ms interval;
- clamped values or dropped events above zero.
The simulator reports the same per-automation statistics without any audio, so the cost of a script can be examined before it is used. The command-line tool orix-dj-bench bench measures the engine and the automation timing on your machine and prints the measured values.
The live log
The log keeps the most recent 2000 lines, and the list of finished runs the most recent 50. A script that prints on every beat fills the log quickly; print on bars, or only when something changes.