Debugging
Debugging means finding out what a script really does, as opposed to what you meant it to do. ORIX DJ gives you three tools for that: the simulator, which runs a script against a simulated rig and records everything; the debugger, which runs the simulation step by step; and the live log, which records what running automations do.
The rule to remember: breakpoints and stepping happen in the simulator. They never pause live audio. You cannot freeze a deck on stage by debugging a script.
The simulator
The simulator runs an automation with the same runtime as the live engine, against a simulated rig: four decks, a mixer, effect racks and a beat clock, with no audio. A simulated run of 64 bars takes a fraction of a second.
The simulated rig
| Setting | Default |
|---|---|
| Clock tempo when no deck plays | 128 BPM |
| Deck A | Loaded, playing, 128 BPM, 512 beats long, title "Track A", key "8A" |
| Deck B | Loaded, paused, 128 BPM, 512 beats long, title "Track B", key "9A" |
| Decks C and D | Empty |
| Run length | Stops after 256 beats |
| Time step | 1/16 beat |
| Triggers | None (a list of "fire trigger n at beat b" can be given) |
Library, for load("…") |
"Track A", "Track B", "Night Drive", "Solar Wind", "Deep Current" |
Each deck can be configured: loaded or empty, playing or paused, tempo, length in beats, start position, title and key. Use this to rehearse the bad cases: deck B empty, deck A already paused, a track that ends during the transition.
The simulated rig behaves like the real one for what scripts can observe: the master clock follows the first playing deck, sync matches tempo, loops wrap, a brake ends in a pause, a track that reaches its end fires trackEnd then pause, actions fail with the same kind of message (Deck C has no track loaded.). It does not model sound: deck.X.level and mixer.master.level are rough stand-ins, not measurements.
What a simulated run gives you
- The trace: every event of the run in order, with its beat and source line (see below).
- Parameter curves: for every control the script wrote or ramped, its value over time, sampled at each step.
- Play spans: for each deck, the ranges of beats during which it was playing.
- The final state: finished, stopped, failed (with the error), or still running at the end of the run.
- Statistics: operations used, writes, ramp updates, actions, clamped values, dropped events, the largest number of tasks and ramps at once.
- The final values of the variables.
The end of a simulated run
The simulation ends when the automation ends, or after the configured number of beats, whichever comes first. An automation that is still alive at that point is reported as timed out. That is not an error: it is what happens to any automation that waits for events, and to any automation longer than the run length. If your 80-bar script "stops at 256 beats in the simulator", raise the run length.
The trace
Each line of the trace has a beat (relative to the automation's beat 0), a kind, the source line and a text.
| Kind | Recorded when | Example text |
|---|---|---|
start |
The run begins | start "Fade" at 128 BPM |
write |
A control is set with = |
deck.A.volume = -6 dB |
action |
An action is performed | deck.B.play() |
wait |
A wait with a duration begins |
wait 4 beats |
spawn |
An at block is scheduled |
scheduled block at beat 29 |
ramp |
A ramp begins | deck.A.volume -> -inf dB over 32 beats |
rampEnd |
A ramp reaches its target | deck.A.volume reached -60 |
handler |
An event starts a handler run | on trigger(1) |
print |
print(…) |
the printed text |
warning |
Something suspicious happened | line 4: 'at' names a position 4 beats in the past; running it now |
error |
The automation failed | Deck C has no track loaded. [E-ACTION] |
finish |
The automation ended | finished or stopped |
breakpoint |
The debugger paused | paused at line 12 |
A trace kind named event is reserved and not produced by this version.
Take this script:
automation "Traced" {
at bar 2 { deck.B.play() }
over 2 bars { deck.A.volume -> -60dB }
deck.A.pause()
deck.A.volume = 0dB
}Its trace in the default rig:
beat kind line text
0.00 start 0 start "Traced" at 128 BPM
0.00 spawn 2 scheduled block at beat 5
0.00 ramp 3 deck.A.volume -> -inf dB over 8 beats
4.00 action 2 deck.B.play()
8.00 rampEnd 3 deck.A.volume reached -60
8.00 action 4 deck.A.pause()
8.00 write 5 deck.A.volume = 0 dB
8.00 finish 0 finishedReading it answers most timing questions directly: the block scheduled "at beat 5" (counted from 1) ran 4 beats in, under the ramp; the pause came at 8 beats, just after the ramp had reached its target (the rampEnd line comes first).
print is the simplest probe. Print a value where you doubt it:
let left = deck.A.remaining
print("remaining:", left, "tempo:", master.bpm, "master:", master.deck)The debugger
The debugger is the simulator run under your control.
Breakpoints
A breakpoint is set on a source line. The run pauses before the first statement of that line is executed, in whichever task reaches it. Simulated time stops with it.
While paused you can inspect
| What | Details |
|---|---|
| The line where the run is paused | |
| The current beat | Position of the simulated clock |
| Variables | The automation's variables that have a value, by name. Variables local to a function call are not listed. |
| Tasks | Every pending task: its number, the beat at which it will continue, the line it is on, and whether it is a handler run |
| Ramps | Every active ramp: the control, the start and target values, the start and end beats, the curve |
| Handlers | The registered event handlers, e.g. on deck.A.trackEnd once |
| The rig | The simulated decks and every value written so far |
Continue and step
- Continue runs until the next breakpoint or the end.
- Step executes one statement and pauses before the next statement that runs, which may be in another task if one is due first. Stepping over a
waittherefore lands on whatever happens next in time, not necessarily on the following line.
A typical session with this script:
automation "Stepping" {
var x = 1
wait 2 beats
x = x + 1
deck.A.pause()
x = x + 1
}- Set a breakpoint on line 4 (
x = x + 1) and run. The run pauses at beat 2 withxequal to 1: the line has not run yet. - Step. The run pauses on line 5;
xis now 2. - Continue. The run ends; the final value of
xis 3.
Breakpoints live
A live automation is never paused by a breakpoint. To examine a problem that only happens live, reproduce the situation in the simulator by configuring the simulated decks the same way, or read the live log.
The live log
Every running automation writes to the automation log: starts, writes, actions, scheduled blocks, ramp starts, handler runs, prints, warnings, errors and the end. wait lines and ramp ends are left out to keep the log readable. Each line carries the run number, the name of the automation, the beat of the master clock, and the source line. The log keeps the most recent 2000 lines.
print output from a line typed in the console is shown directly under that line.
status in the console shows, for each running automation, its run number, its state, its position, the number of pending tasks and the number of active ramps. See Console Usage.
Checking a file from the command line
The repository includes a command-line tool that compiles a script and runs each of its automations in the default simulated rig.
swift run orix-dj-bench check MyScript.orixdjFor a correct script it prints one line per automation:
automation "Traced": decks ["A", "B"], 8.0 beats, simulated 8.0 beats, 3 actions, state finishedFor an incorrect one it prints the diagnostics as file:line:column: severity: message [CODE] and exits with a non-zero status. An automation whose length is not known in advance is shown as open-ended.
A method for finding a timing bug
- State what you expected, in beats: "deck B should start 28 beats in".
- Run the simulator and find the line in the trace. Is the action there? At which beat?
- If it is missing, the script never reached it: look for a
stop, a condition that was false, an error, or a run that timed out first. - If it is at the wrong beat, find what moved the cursor: add up the
waitandoverdurations before it. Remember thatatcounts from the start of the automation and from 1. - If a control ends at the wrong value, look at its curve and at the
writeandramplines for that control: a later=cancels a ramp, a later ramp replaces an earlier one. - Check the warnings. "Position in the past" and clamped values almost always point at the mistake.