SPB Git

Repository Public

debugger.md 9.1 KB

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

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

text
 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  finished

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

orixdj
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 wait therefore lands on whatever happens next in time, not necessarily on the following line.

A typical session with this script:

orixdj
automation "Stepping" {
    var x = 1
    wait 2 beats
    x = x + 1
    deck.A.pause()
    x = x + 1
}
  1. Set a breakpoint on line 4 (x = x + 1) and run. The run pauses at beat 2 with x equal to 1: the line has not run yet.
  2. Step. The run pauses on line 5; x is now 2.
  3. Continue. The run ends; the final value of x is 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.

text
swift run orix-dj-bench check MyScript.orixdj

For a correct script it prints one line per automation:

text
automation "Traced": decks ["A", "B"], 8.0 beats, simulated 8.0 beats, 3 actions, state finished

For 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

  1. State what you expected, in beats: "deck B should start 28 beats in".
  2. Run the simulator and find the line in the trace. Is the action there? At which beat?
  3. 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.
  4. If it is at the wrong beat, find what moved the cursor: add up the wait and over durations before it. Remember that at counts from the start of the automation and from 1.
  5. If a control ends at the wrong value, look at its curve and at the write and ramp lines for that control: a later = cancels a ramp, a later ramp replaces an earlier one.
  6. Check the warnings. "Position in the past" and clamped values almost always point at the mistake.
Files main
Menu

Theme