SPB Git

Repository Public

performance.md 8.5 KB

# 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:

  1. The automation is cancelled immediately: all its tasks, ramps and handlers are removed.
  2. Every effect it had switched on and not switched off is switched off, and the log shows a bypassed … after the failure line for each.
  3. 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.

orixdj-error
var total = 0
for a in 1...200 {
    for b in 1...200 {
        total = total + a * b
    }
}
print(total)
text
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.

orixdj
// 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 = 20Hz

# Prefer 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.

orixdj
// Better than the loop above when a continuous sweep is wanted
over 2 bars { deck.A.filter.highpass -> 1700Hz }
deck.A.filter.highpass = 20Hz

# Choose 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.

Files main
Menu

Theme