Automation: the ORIX Script implementation
This document describes how ORIX Script is implemented: the compiler, the plan it produces, the runtime that executes the plan in beat time, the live scheduler that turns the runtime's output into sample-stamped control events, the console, the simulator and debugger, and the two built-in producers of scripts (presets and Auto DJ). It is written from the source; file names and constants are quoted as they appear in the code.
The language itself is documented for users in docs/orix-script/. Related engineering documents: overview, audio engine, deck engine, mixer, AI integration, persistence, security report, performance, testing.
Source layout
| File | Role |
|---|---|
Packages/ORIXDJCore/Sources/ORIXScript/Lexer.swift |
Source text to tokens, including unit literals (-12dB, 20Hz, 4bars, 1/4beat, 50%). Also produces highlight spans for text that does not parse. |
ORIXScript/Parser.swift, AST.swift |
Recursive-descent parser with error recovery; block and expression nesting limited to 20 levels (maxNesting). |
ORIXScript/Schema.swift |
The single table of everything a script can name: deck, mixer, master and effect parameters, actions, events, builtins, keywords. |
ORIXScript/Compiler.swift |
Semantic analysis and lowering: ScriptCompiler, Capabilities, CompileLimits. |
ORIXScript/Plan.swift |
The plan (Program, CompiledAutomation, PStmt, PExpr), ScriptRuntimeError, and the pure Evaluator shared by constant folding and the runtime. |
ORIXScript/Runtime.swift |
AutomationInstance, AutomationTarget, RuntimeLimits, trace and statistics types. |
ORIXScript/Simulator.swift |
SimulatedRig, DebugSession, Simulator. |
ORIXScript/Tools.swift |
ScriptFormatter, ConsoleParser, Autocomplete. |
ORIXScript/Presets.swift |
PresetLibrary (24 presets). |
ORIXScript/Reference.swift |
ReferenceGenerator: generated reference chapters and the language brief sent to Claude. |
ORIXDJEngine/AutomationHost.swift |
Live binding to DJEngine: scheduler thread, look-ahead, console execution, statistics. |
ORIXDJEngine/AutoDJ.swift, Session.swift |
Auto DJ planner and the session code that runs its generated scripts. |
The ORIXScript module imports only Foundation and ORIXDSP (for the EffectKind catalogue). It has no dependency on the engine: the runtime talks to an AutomationTarget protocol with four members (read, write, perform, clockBPM), implemented by AutomationHost for the live engine and by SimulatedRig for the simulator.
Why an interpreter of our own
The code does not contain a comment comparing this design with embedding an existing scripting engine, so no such comparison is claimed here. What the code does state, and what the design follows from, is:
Runtime.swiftheader: the runtime "never runs on the audio render thread: it only emits timestamped parameter writes and actions".Compiler.swift:Capabilitiesis "what the host can run. Scripts that need more are rejected before execution"; recursion is rejected because "automations must be bounded".Reference.swift(completeReference): "Every path listed here is accepted by the compiler; nothing else is"; (languageBrief): "No file, network, shell or system access exists in the language."ScriptAssistant.swiftheader: "Nothing a model writes reaches the engine without passing the same validation as a hand-written script."
A language whose whole vocabulary is one schema table makes these properties checkable at compile time, and lets time be a first-class notion (beats, bars, over, at, every) instead of a library on top of a general-purpose language.
Compiler pipeline
flowchart TD
SRC["Source text (max 256 KB)"] --> LEX["Lexer: tokens and unit literals"]
LEX --> PAR["Parser: recursive descent with recovery"]
PAR --> AST["AST: ScriptFile with constants, functions, automations"]
AST --> SEM["Semantic analysis: names, types, units, ranges"]
SEM --> CAP["Capability validation: deck count and effect set"]
CAP --> BND["Bound checks: loop limits, recursion, handler and statement counts"]
BND --> PLAN["Plan: Program of CompiledAutomation and PFunction"]
PLAN --> RT["Runtime tasks: AutomationInstance"]
RT --> SCH["Scheduler: AutomationHost tick with look-ahead"]
SCH --> EVT["Timestamped control events in the RenderCore queue"]
SEM -. "any error" .-> DIAG["Diagnostics with code, line, column; no Program"]
CAP -. "any error" .-> DIAG
BND -. "any error" .-> DIAG
ScriptCompiler.compile(_:capabilities:) returns a CompileResult. program is non-nil only when there is no diagnostic of severity .error; warnings (W-SHADOW, W-UNREACHABLE, W-OVER, W-RAMP, W-UNUSED, W-AT) do not block. Diagnostics are sorted by line and column. A script with no automation is rejected with E-EMPTY.
What the semantic pass (Compilation) does, in the order of the code:
- Top-level constants must fold to a value (
E-CONSTotherwise). - Functions are declared first so they can call each other in any order, then compiled. A function with a return type is a pure function (
BodyContext.pureFunction): no timing statements, no writes, no actions, no reads of live values, noprint, norandom()(E-PURE), and it must return on every path (E-RETURN). A function without a return type is a timed procedure. - Recursion detection walks the call graph depth-first and reports
E-RECURSIONfor any cycle, direct or indirect. - Automations: each body is lowered to
PStmtvalues. Paths are resolved againstScriptSchemabyresolveParam,deckPrefixandeffectKind; an unknown name isE-PATH,E-DECK,E-EFFECTorE-UNDECLARED, with a "Did you mean" hint computed by Levenshtein distance (suggestion(for:in:)). - Type and unit checks:
Evaluator.binaryTypedecides which operand types combine; gains, frequencies, durations and plain numbers never mix (E-TYPE, with a hint such as "Add the unit: 3dB"). The one implicit conversion is a plain number assigned to a gain parameter, treated as a linear level in 0…4 and converted by the internallinearToGainbuiltin. - Range checks on constants against the parameter definition (
E-RANGE); read-only properties (E-READONLY); only rampable parameters insideover(E-RAMP). - Capability validation: a deck index at or beyond
capabilities.deckCount, or an effect outsidecapabilities.effects, isE-CAPABILITY. The defaults are four decks and everyEffectKind. - Constant folding (
fold) uses the sameEvaluatoras the runtime. Mixed beat/second arithmetic andrandom,toBeats,toSecondsare left for run time because they depend on the tempo or on state. - Requirements are collected per automation (
AutomationRequirements): decks addressed by a constant path, effects addressed,usesEvents,usesAbsoluteTime, andlengthBeatswhenCompilation.extentcan determine the length statically (nil when it depends on run-time values or the automation has event handlers).
ScriptCompiler.compileConsole parses in console mode and wraps loose statements into one anonymous automation named console with quantize none.
The runtime
An AutomationInstance is one running automation. It is single-threaded by contract ("create, advance and inspect it from one queue") and is driven by one call: advance(to: beat), which runs everything due up to that beat of the master clock.
- Tasks. The main body is task 0.
atblocks (.spawn) and event handler runs become additionalScriptTaskvalues, each with a wake beat and a stack ofActivationrecords (body, program counter, frame, loop kind).advancerepeatedly picks the task with the smallest(wake, id)that is due, runs it until it waits or ends, and removes it when finished. Tasks are cooperative: a statement returns the beat at which the task must resume (wait,over,every). - Start quantisation.
quantize beatorquantize barmovesstartBeatto the next boundary (nextBoundary, four beats per bar fromORIXScriptLanguage.beatsPerBar). - Ramps.
overreads the current value through the target, registers anActiveRampper parameter and suspends the task for the duration.updateRampswrites an interpolated value at eachadvance(curve fromRampCurve.shape; frequencies are interpolated geometrically when both ends are positive) withrampBeatsequal to the step, so the engine glides between scheduler steps.finishRamps(upTo:)writes the exact target at the ramp's end beat before the statements that follow it run. A direct write to a ramped parameter cancels its ramp. - Events.
onregisters aHandlerkeyed byEventKey.post(_:atBeat:)spawns a handler task; beat and bar events are generated insideadvance(at most 64 beats per call). - Values written pass through
conform, which clamps to the parameter's range and counts the clamp inAutomationStats.clampedValues; a non-finite number becomes the parameter's minimum. - Determinism.
random()is a xorshift generator with a fixed seed (0x2545F4914F6CDD1D) per instance;RuntimeTests.randomIsDeterministicchecks that two runs print the same values. - Trace. Every write, action, wait, spawn, ramp, handler run, print, warning, error and finish is reported through
onTraceas aTraceEvent. The live log, the console, the simulator and the debugger all consume this one stream.
Live scheduling
AutomationHost (ORIXDJEngine/AutomationHost.swift) owns the running instances and a dedicated scheduler thread.
| Property | Value in the code |
|---|---|
| Thread name | ai.spboucher.orix.dj.automation, QoS .userInteractive |
| Scheduling class | Mach THREAD_TIME_CONSTRAINT_POLICY: period 4 ms, computation 0.4 ms, constraint 2 ms, preemptible |
| Period | 4 ms (ticks(4_000_000)), waited with mach_wait_until; when a tick overruns, the next wake is a quarter period after now |
| Look-ahead | lookaheadSeconds = 0.03 (30 ms) by default; adjustable from 5 to 50 ms in Settings |
| Horizon | clock.beat + lookaheadSeconds * clock.bpm / 60 |
| Control queue | SPSCQueue<ControlEvent>(minimumCapacity: 4096) in RenderCore; a failed push increments droppedControlEvents |
| Pending list on the render thread | 512 events (pendingCapacity), kept sorted by time |
| Live log | last 2000 lines; finished runs: last 50 |
Note on the look-ahead value: one sentence of the user documentation (scheduling, "up to 15 ms before the beat") and the heading printed by the benchmark say 15 ms, but the default in AutomationHost is 30 ms and the benchmark does not override it. The application stores the Settings value in UserDefaults (key automation.lookahead, default 30) and applies it at start-up, clamped to 5 to 50 ms (AppModel.swift, AppSettings.swift, as read on 2026-11-21; this part of the application was being edited while this document was written). Only the test scriptActionsLandOnExactSamples sets it explicitly (to 20 ms). The measurements below were therefore taken with 30 ms (benchmark, offline mixes) and 20 ms (test).
flowchart TD
T["Scheduler thread wakes every 4 ms"] --> S["engine.service: drain render notices, advance master clock"]
S --> H["horizon = clock beat + look-ahead in beats"]
H --> P["post pending deck and trigger events to every instance"]
P --> A["instance.advance to horizon"]
A --> W["write or perform at beat b"]
W --> ST["engine.sampleTime for beat b"]
ST --> Q["push ControlEvent with sample time into SPSC queue"]
Q --> R["Render thread intake: due now is applied, future goes to sorted pending list"]
R --> X["Render block is cut at the next pending timestamp, event applied on that sample"]
X --> M["If the event is tracked: lateness = render sample time minus timestamp"]
A --> RP["reap finished or failed runs, update SchedulerStats"]
One tick():
engine.service()drains render-thread notices and advances the master clock; it returnsClockState(beat, BPM, sample time, master deck).- The horizon is computed. Deck events collected since the last tick (
handle(_:)) and triggers (fire(trigger:)) are posted to every instance. - Each instance is advanced to the horizon. Its writes and actions call back into the host (
AutomationTarget), which converts the beat to a sample time withengine.sampleTime(forBeat:)(clockAnchorSample + round((beat - clockAnchorBeat) * 60 / max(20, bpm) * sampleRate)) and calls the engine withat: time. - The engine pushes a
ControlEventcarrying that time. InRenderCore,intake()applies events whose time is not in the future and inserts the others into a time-ordered pending list; the render loop limits each sub-block topending[0].time - sampleTimeframes, so a scheduled event is applied on its sample rather than at a buffer boundary. See audio engine. - Statement-issued writes and actions are marked
tracked; the render thread counts them and measures how many arrived after their sample (lateEvents,maxLateSamples,totalLateSamples). Intermediate ramp updates are not tracked (tracked: rampBeats == 0); they carry a smoothing time instead. - Finished and failed runs are moved to
finishedRuns; tick duration and the gap since the previous tick are recorded inSchedulerStats.
The scheduler thread takes an NSRecursiveLock; the render thread never does. The only shared structures between them are the lock-free queues and the published render state.
Consequences of look-ahead, all visible in the code: a value read by a script is the state at the time of the tick, up to one look-ahead before the beat the statement is scheduled for; an event is delivered at the tick after it occurs; a console line cannot act earlier than "now".
AutomationHost.renderOffline(frames:) calls tick() between offline render blocks of max(16, bufferFrames) frames. Tests, the benchmark and the offline mix renderer use it, so they exercise the same scheduling path without the real-time thread.
The application starts the scheduler in AppModel.start() and stops it in shutdown().
Console execution
flowchart TD
L["Console line"] --> CP["ConsoleParser.parse"]
CP -->|"first word is a command"| CMD["command: help, list, run, stop, pause, resume, status, decks, fx, trigger, panic, clear, version"]
CP -->|"anything else"| CC["ScriptCompiler.compileConsole"]
CC -->|"errors"| INV["invalid: print each diagnostic with its code, count a validation error"]
CC -->|"program"| ST["host.start as automation named console, origin console"]
ST --> ADV["advance once to current beat plus look-ahead, capturing the trace"]
ADV --> OUT["print lines as results, errors as errors, warnings as info"]
OUT -->|"instance still alive"| SCHED["report: Automation scheduled with run id"]
OUT -->|"instance finished"| OK["report: OK when nothing was printed"]
CMD --> RUN["run Name: load source by name, full compile, start"]
AutomationHost.execute(console:) runs under the host lock. A line is a command when its first word is in ConsoleParser.commands and is not followed by =, . or ( (so stop alone is the console command, not the statement). Otherwise the line is compiled with the same compiler and limits as a file. The resulting automation is started and advanced once synchronously so that an expression such as deck.B.volume prints its value immediately; anything that waits stays in the run list and is advanced by the scheduler like any other run. run "Name" resolves the name through scriptSource (the library's saved scripts first, then PresetLibrary), and prints at most six diagnostics when the script does not compile. panic calls emergencyStop().
AutomationLiveTests.consoleDrivesTheRealEngine checks this path against a real DJEngine. User documentation: console.
Safety limits
CompileLimits (Compiler.swift)
| Field | Value | Enforced as |
|---|---|---|
maxLoopIterations |
10000 | E-LIMIT for constant repeat, for and every counts; the while … limit N constant must be 1…10000 (E-UNBOUNDED) |
maxArrayLength |
256 | E-LIMIT |
maxSourceBytes |
256 * 1024 (256 KB) | E-LIMIT, checked before parsing |
maxStatements |
20000 | E-LIMIT |
minEveryPeriodBeats |
1/64 beat | E-LIMIT |
maxHandlers |
32 | E-LIMIT |
Other compile-time bounds that are literals in the code rather than CompileLimits fields: 512 variables per automation or function; a constant wait, ramp or at position of at most 100000 beats; block and expression nesting of 20 levels (Parser.maxNesting); string literals of 512 characters (lexer).
RuntimeLimits (Runtime.swift)
| Field | Value | Behaviour when exceeded |
|---|---|---|
maxOperationsPerStep |
20000 | E-BUDGET (operations in one advance without a wait) |
maxTotalOperations |
5000000 | E-BUDGET (life of one automation) |
maxTasks |
256 | E-LIMIT on the at that would exceed it |
maxRamps |
128 | E-LIMIT |
maxHandlers |
32 (CompileLimits.maxHandlers) |
E-LIMIT |
maxCommandsPerBeat |
512 | E-RATE (statement-issued writes and actions; ramp updates are not counted) |
maxLoopIterations |
10000 (CompileLimits.maxLoopIterations) |
E-LIMIT for counts computed at run time |
maxCallDepth |
16 | E-LIMIT for nested value-returning calls; procedure calls are bounded by an activation stack of maxCallDepth * 4 = 64 entries |
maxArrayLength |
256 (CompileLimits.maxArrayLength) |
declared; the compiler enforces the length of array literals and the language has no operation that grows an array |
maxSpanBeats |
100000 | E-LIMIT for a computed wait, ramp or position |
maxPendingHandlerTasks |
64 | further events are dropped and counted in droppedEvents; not an error |
An operation is charged (charge) for each statement executed, each loop turn, each binary operator, each live read and each builtin call. Strings built with + are limited to 2048 characters (E-LIMIT) and the text of one print is cut at 2048 characters.
RuntimeLimits is a plain struct; AutomationHost.limits and SimulationConfig.limits both default to RuntimeLimits(). The Settings screen shows the limits as fixed values and offers no control for them.
Failure behaviour
| Situation | What happens |
|---|---|
| Compile error | No Program is produced, so nothing can start. Diagnostics carry a stable code, line, column and token length. AppModel.run(source:origin:) returns them and counts a validation error (SchedulerStats.validationErrors). |
Run-time error (E-ACTION, E-UNAVAILABLE, E-MATH, E-RANGE, E-TYPE, …) |
AutomationInstance.fail: all tasks, ramps and handlers of that automation are removed; every effect the automation itself switched on (tracked in enabledEffects from enable(), toggle() and enabled = true) receives a disable action and a bypassed … after the failure warning is traced; state becomes .failed(error) with the line that was executing; the error is traced. |
Budget exhaustion (E-BUDGET, E-RATE, run-time E-LIMIT, E-UNBOUNDED) |
Thrown as ScriptRuntimeError from charge / chargeCommand / the statement; handled exactly like any other run-time error. |
| Engine refuses a write (no beat grid, full rack, …) | AutomationHost.write logs a warning line (engine origin); the automation continues. An action the engine refuses returns a message and becomes E-ACTION. |
stop statement, stop command, host.stop |
State .stopped; tasks, ramps and handlers removed; ramps stop where they are; nothing is restored and no effect is bypassed. |
Emergency stop (panic in the console, the automation.panic control target, the Emergency Stop buttons and menu command, Shift-Command-Escape) |
stopAll(), then engine.bypassAllEffects() (a .panic control event): every effect in every rack is bypassed. Decks keep playing; faders and EQ are untouched. |
What is not undone on failure: faders, EQ, filters, crossfader and effect parameter values stay where the script left them. Other automations are unaffected; each instance fails on its own.
What happens to the audio: nothing in the runtime executes on the render thread, and the render thread does not wait for the scheduler, so a failing or slow script changes only which control events arrive. AutomationLiveTests.failingScriptLeavesAudioRunningAndBypassesItsEffects runs a script that enables a bitcrusher and then fails with deck.C.play() on an empty deck: the deck is still playing, the run is recorded as failed, runtimeErrors == 1, the effect is disabled, and from 1.5 s to 2.0 s the output equals the 1 kHz source sine within 1e-5 per sample. If the control queue were full, the push would fail and be counted in droppedControlEvents; the benchmark and both offline mixes report zero.
User-facing description: errors, security.
Simulator and debugger
The simulator is not a second implementation of the language. DebugSession creates a SimulatedRig (an AutomationTarget that models four decks, a parameter store seeded from schema defaults, a beat clock and a small fake library) and the same AutomationInstance class the live host uses, then steps time in increments of 1 / stepsPerBeat beats (16 steps per beat by default) until the automation ends, a breakpoint is hit, or maxBeats (256 by default) is reached, in which case timedOut is set. The rig produces deck events (play, pause, beat, trackEnd, loaded) that are posted back to the instance, and configured triggers are fired at their beats.
Simulator.run(_:automation:config:) wraps a DebugSession and returns a SimulationResult: the full trace, sampled curves for every parameter the automation wrote, per-deck play spans, final state, statistics and final variables.
Debugging is a property of the runtime, not of the simulator: AutomationInstance has breakpoints (a set of line numbers), stepping, and pausedAtLine. A breakpoint fires before the statement runs; advance returns false and the caller resumes with continueFromBreakpoint(step:). DebugSession.resume() and stepOver() wrap this. ToolTests.debuggerBreakpointsAndStepping checks the paused line, the beat and the variable values at each stop. The live host never sets breakpoints.
How the application uses it (App/Sources/Features/AutomationStudio/):
SimSettings(tempo, which decks are loaded and playing,maxBeats, triggers) is converted to aSimulationConfig.- Simulate compiles the active document and calls
Simulator.runoff the main thread;AutomationSimulatorPaneldraws the result as a timeline (play spans, parameter curves, action markers) and a trace, and marks it stale when the script has changed since. - Debug uses
DebugController, which owns oneDebugSessionon a private serial queue (ai.spboucher.orix.dj.debugger). It starts with the editor's breakpoints, or in stepping mode when there are none, and publishes aDebugSnapshot(paused line, beat, variables, tasks, ramps, handlers, trace, statistics) after eachresumeorstep. The panel states that debugging runs in the simulator and never pauses or changes live audio. - The same
Simulator.runis used by Claude Studio to validate proposals (AI integration), by the documentation viewer to check examples, and by the visual builder.
User documentation: debugger.
The simulated rig is a model, not the engine: it has no audio, its level readings are derived from fader values, and load("title") searches a fixed list of five titles. A script that passes the simulator can still fail live, for example when a deck is empty.
Presets
PresetLibrary.all contains 24 ScriptPreset values in 11 categories (PresetCategory): Transitions, Crossfades, Filters, Echo, Reverb, Beat effects, Build-ups, Drops, Loops, Auto DJ, Creative performance. A preset is a name, a category, a one-line summary and ORIX Script source text; there is no separate preset format or privileged code path. Opening a preset in the editor gives ordinary text, and run "Name" in the console falls back to PresetLibrary when no saved script has that name.
PresetTests.everyPresetCompilesAndSimulates requires, for every preset: no compile errors and no warnings, the automation named like the preset, a simulated run (deck A playing, 160 beats, trigger 1 at beat 24) with no error, no warning and no clamped value, completion for presets without event handlers, and canonical formatting. eightBarTransitionDoesWhatItSays checks the timeline of one preset in detail (deck B plays at beat 0, deck A pauses at beat 32, its fader is below -55 dB at beat 31.9 and back to 0 dB at 32). User documentation: presets.
Auto DJ expressed as scripts
Auto DJ has no mixing code of its own. AutoDJPlanner (ORIXDJEngine/AutoDJ.swift) does two things:
- Ordering.
order(_:settings:)is a greedy nearest-neighbour ordering starting from the first track, deterministic (ties keep the original order). The cost of playingbafterais a tempo term (percentage change after folding half and double time, plus a penalty of 20 abovemaxTempoChange, 8 % by default; 6 when unknown) plus a key term from the Camelot wheel distance (0.5 per step up to distance 1, 2 per step beyond; 3 when unknown). No network and no model are involved. - Transition generation.
transitionScript(from:to:settings:)returns ORIX Script text for one of five styles (blend,bassSwap,echoOut,filterSweep,cut), with the bar count clamped to 1…64 and an optionaldeck.X.sync(true)line. Every generated automation isquantize barand restores the controls it moved on the outgoing deck.
DJSession.autoDJTick() computes the lead time (leadSeconds: transition bars + 3 bars, at the deck's tempo), generates the script, compiles it with ScriptCompiler.compile and starts it with host.start(program, origin: "auto-dj"). If the compiler rejects the generated text, Auto DJ stops with the state "Transition script rejected: …". The last generated script is kept in AutoDJStatus.lastScript, and the Auto DJ screen (App/Sources/Features/AutoDJ/) describes each style in one sentence and shows the order the planner will play.
SessionTests.autoDJMixesTheQueueWithARealTransitionScript runs three synthesised demo tracks through two transitions offline and checks that exactly one deck is playing afterwards, that the last script compiles, and that there were no run-time errors. plannerIsDeterministicAndPrefersCompatibleNeighbours covers the ordering.
Schema and generated reference
ScriptSchema is the only place where the vocabulary is defined: four decks, eight hot cues, sixteen triggers, the parameter tables with type, range, default, unit, writable and rampable flags, the action and event tables, and the builtins. Four consumers read it:
- the compiler (name resolution, type and range checks);
Autocomplete(completions and hover documentation, alsohelp <path>in the console);ReferenceGenerator.generatedChapters, which producesdeck-api.md,mixer-api.md,effects-api.mdandapi-reference.mdunderdocs/orix-script/(regenerated withswift run orix-dj-bench docs);ReferenceGenerator.languageBrief, the compact description sent to Claude as the system prompt (AI integration).
DocsTests keeps the documentation and the implementation from drifting apart:
generatedChaptersAreUpToDatecompares the four generated files byte for byte with the generator's output;everyExampleCompilesAndRunscompiles and simulates everyorixdjcode block indocs/orix-script/, requires everyorixdj-errorblock to be rejected by the compiler or the simulator, and parses every>line of everyconsoleblock;everyPresetAndErrorCodeIsDocumentedrequires each preset name and each of 30 error codes to appear in the documentation;PresetTests.referenceOnlyDocumentsWhatCompilescompiles a read of every path in the generated tables (more than 150).
Result of the run used for this document (swift test --no-parallel, debug build):
=== ORIX-DOCS === 150 examples compiled and simulated, 59 error examples rejected, 59 console lines parsed === END ===Measured timing
All figures below are from offline rendering (renderOffline), which calls tick() once per 256-frame block instead of running the 4 ms real-time thread. They measure whether commands computed with look-ahead reach the render core before their sample; they do not measure the jitter of the real-time scheduler thread under load, which has not been measured for this document.
Benchmark (docs/reports/engine-benchmark.txt, release build, Apple M5 Max, orix-dj-bench bench; 48 kHz, 256-frame buffers; two automations, one issuing sixteen commands per beat and one running three continuous ramps):
Automation scheduling (offline, 256-frame buffers, 15 ms look-ahead)
ticks 3750 tick mean 2.5 µs max 343.9 µs
timed commands 687 late 0 worst lateness 0 samples dropped control events 0 runtime errors 0The heading's "15 ms" is a label in Benchmarks.swift; the host in that benchmark runs with the default 30 ms (see the note above). The maximum tick time includes preemption, since the benchmark does not run on a real-time thread.
Test (AutomationLiveTests.scriptActionsLandOnExactSamples, debug build, look-ahead 20 ms, 120 BPM click tracks on decks A and B, deck.B.play() and deck.B.pause() scheduled with at bar and at beat):
=== ORIX-AUTOMATION-TIMING === tracked 3 late 0 maxLate 0 samples; worst click offset 0 samples === END ===The test's tolerance is 2 samples between each deck B click and the nearest deck A click, and zero late events. rampsAreSmoothAndReachTheirTargets checks a scripted over 4beats fader ramp against a DC input: -10 dB within 0.25 dB at the half-way point, -20 dB within 0.05 dB at the end, back to 0 dB within 0.01 dB after the following write, and a largest sample-to-sample output step below 0.0005 during the ramp.
Offline mixes of real music (orix-dj-bench mix: decode two tracks, analyse, set gain and key lock, run a preset through AutomationHost, write a WAV):
| Preset | Tracks | Timed commands | Late | Other results |
|---|---|---|---|---|
| Bass Swap | 124 BPM into 122 BPM | 10 | 0 | deck B played at 124.00 BPM; 0 clipped blocks; peak -6.99 dBFS; the rendered file analyses at 124.00 BPM with tempo stability 0.98 |
| Eight Bar Transition | two 119 BPM tracks | 9 | 0 | peak -3.71 dBFS; the rendered file analyses at 119.00 BPM with tempo stability 0.98 |
Nobody has listened to these two renders yet. The figures say that the commands were on time and that the result has a steady tempo and does not clip; they say nothing about how the transitions sound.
Not measured: the scheduler thread's tick gap (maxTickGapMillis) and late-event counts on a real audio device during a long session, and behaviour with dozens of concurrent automations.