SPB Git

Repository Public

debugger.md 9.1 KB 183 lines markdown

1# Debugging23Debugging 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.45The 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.67## The simulator89The 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.1011### The simulated rig1213| Setting | Default |14| --- | --- |15| Clock tempo when no deck plays | 128 BPM |16| Deck A | Loaded, playing, 128 BPM, 512 beats long, title "Track A", key "8A" |17| Deck B | Loaded, paused, 128 BPM, 512 beats long, title "Track B", key "9A" |18| Decks C and D | Empty |19| Run length | Stops after 256 beats |20| Time step | 1/16 beat |21| Triggers | None (a list of "fire trigger n at beat b" can be given) |22| Library, for `load("…")` | "Track A", "Track B", "Night Drive", "Solar Wind", "Deep Current" |2324Each 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.2526The 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.2728### What a simulated run gives you2930- **The trace**: every event of the run in order, with its beat and source line (see below).31- **Parameter curves**: for every control the script wrote or ramped, its value over time, sampled at each step.32- **Play spans**: for each deck, the ranges of beats during which it was playing.33- **The final state**: finished, stopped, failed (with the error), or still running at the end of the run.34- **Statistics**: operations used, writes, ramp updates, actions, clamped values, dropped events, the largest number of tasks and ramps at once.35- **The final values of the variables.**3637### The end of a simulated run3839The 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.4041## The trace4243Each line of the trace has a beat (relative to the automation's beat 0), a kind, the source line and a text.4445| Kind | Recorded when | Example text |46| --- | --- | --- |47| `start` | The run begins | `start "Fade" at 128 BPM` |48| `write` | A control is set with `=` | `deck.A.volume = -6 dB` |49| `action` | An action is performed | `deck.B.play()` |50| `wait` | A `wait` with a duration begins | `wait 4 beats` |51| `spawn` | An `at` block is scheduled | `scheduled block at beat 29` |52| `ramp` | A ramp begins | `deck.A.volume -> -inf dB over 32 beats` |53| `rampEnd` | A ramp reaches its target | `deck.A.volume reached -60` |54| `handler` | An event starts a handler run | `on trigger(1)` |55| `print` | `print(…)` | the printed text |56| `warning` | Something suspicious happened | `line 4: 'at' names a position 4 beats in the past; running it now` |57| `error` | The automation failed | `Deck C has no track loaded. [E-ACTION]` |58| `finish` | The automation ended | `finished` or `stopped` |59| `breakpoint` | The debugger paused | `paused at line 12` |6061A trace kind named `event` is reserved and not produced by this version.6263Take this script:6465```orixdj66automation "Traced" {67    at bar 2 { deck.B.play() }68    over 2 bars { deck.A.volume -> -60dB }69    deck.A.pause()70    deck.A.volume = 0dB71}72```7374Its trace in the default rig:7576```text77 beat  kind     line  text78 0.00  start       0  start "Traced" at 128 BPM79 0.00  spawn       2  scheduled block at beat 580 0.00  ramp        3  deck.A.volume -> -inf dB over 8 beats81 4.00  action      2  deck.B.play()82 8.00  rampEnd     3  deck.A.volume reached -6083 8.00  action      4  deck.A.pause()84 8.00  write       5  deck.A.volume = 0 dB85 8.00  finish      0  finished86```8788Reading 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).8990`print` is the simplest probe. Print a value where you doubt it:9192```orixdj93let left = deck.A.remaining94print("remaining:", left, "tempo:", master.bpm, "master:", master.deck)95```9697## The debugger9899The debugger is the simulator run under your control.100101### Breakpoints102103A 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.104105### While paused you can inspect106107| What | Details |108| --- | --- |109| The line where the run is paused | |110| The current beat | Position of the simulated clock |111| Variables | The automation's variables that have a value, by name. Variables local to a function call are not listed. |112| 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 |113| Ramps | Every active ramp: the control, the start and target values, the start and end beats, the curve |114| Handlers | The registered event handlers, e.g. `on deck.A.trackEnd once` |115| The rig | The simulated decks and every value written so far |116117### Continue and step118119- **Continue** runs until the next breakpoint or the end.120- **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.121122A typical session with this script:123124```orixdj125automation "Stepping" {126    var x = 1127    wait 2 beats128    x = x + 1129    deck.A.pause()130    x = x + 1131}132```1331341. 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.1352. Step. The run pauses on line 5; `x` is now 2.1363. Continue. The run ends; the final value of `x` is 3.137138### Breakpoints live139140A 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.141142## The live log143144Every 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.145146`print` output from a line typed in the console is shown directly under that line.147148`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](console.md).149150## Checking a file from the command line151152The repository includes a command-line tool that compiles a script and runs each of its automations in the default simulated rig.153154```text155swift run orix-dj-bench check MyScript.orixdj156```157158For a correct script it prints one line per automation:159160```text161automation "Traced": decks ["A", "B"], 8.0 beats, simulated 8.0 beats, 3 actions, state finished162```163164For 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`.165166## A method for finding a timing bug1671681. **State what you expected**, in beats: "deck B should start 28 beats in".1692. **Run the simulator and find the line in the trace.** Is the action there? At which beat?1703. **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.1714. **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.1725. **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.1736. **Check the warnings.** "Position in the past" and clamped values almost always point at the mistake.174175## Related176177- [Troubleshooting](troubleshooting.md)178- [Error Handling](errors.md)179- [Automation Scheduling](scheduling.md)180- [Console Usage](console.md)181- [Timing](timing.md)182- [Performance Guidelines](performance.md)183
Files main
Menu

Theme