Architecture Overview
ORIX DJ is a native macOS application made of two parts:
ORIXDJCore, a Swift package (Packages/ORIXDJCore) that contains everything that is not interface: DSP, analysis, the library, MIDI, the ORIX Script language, and the audio engine. No SwiftUI is imported anywhere in the package, so the whole engine can be built and tested from the command line withswift test.- The application (
App/Sources), a SwiftUI and AppKit front end that owns one session object and draws its state. The Xcode project is generated fromproject.ymlby XcodeGen.
There is no third-party code in either part. The package links only system frameworks and libraries: Accelerate,
AudioToolbox, CoreAudio, AVFoundation, CoreMIDI and sqlite3.
This page is the map. Each area has its own document, linked from the tables below.
Module map
The package is split into targets with a strict dependency direction (from Package.swift):
flowchart TD
APP["ORIX DJ application (SwiftUI + AppKit + Metal)"]
CORE["ORIXDJCore (umbrella, re-exports every module)"]
ENGINE["ORIXDJEngine"]
SCRIPT["ORIXScript"]
DSP["ORIXDSP"]
ANALYSIS["ORIXAnalysis"]
LIBRARY["ORIXLibrary"]
MIDI["ORIXMIDI"]
BENCH["orix-dj-bench (command-line tool)"]
APP --> CORE
CORE --> ENGINE
BENCH --> ENGINE
ENGINE --> SCRIPT
ENGINE --> DSP
ENGINE --> ANALYSIS
ENGINE --> LIBRARY
ENGINE --> MIDI
SCRIPT --> DSP
ORIXDSP, ORIXAnalysis, ORIXLibrary and ORIXMIDI depend on nothing but system frameworks. ORIXScript
depends on ORIXDSP only for the effect catalogue, from which part of the language schema is generated.
ORIXDJEngine is the only target that knows about all the others.
| Target | Contents | Document |
|---|---|---|
ORIXDSP |
Primitives.swift (gain maths, biquads, smoothers, delay lines, the lock-free single-producer single-consumer queue), EffectUnit.swift (base class of every effect), EffectCatalog.swift (the single table of 18 effect kinds and their parameters), Effects/* |
DSP |
ORIXAnalysis |
FFT helper, onset strength, tempo and beat grid, key, loudness, waveform summary, and SignalSynth (deterministic synthetic audio for tests and demo material) |
Analysis, Waveform |
ORIXLibrary |
SQLiteDatabase (wrapper over the SQLite C API), LibraryStore (schema, migrations, tracks, collections, scripts), SmartCrateSQL, MediaImporter |
Persistence |
ORIXMIDI |
MIDIManager (CoreMIDI client, hot-plug, input, learn, output), MIDIParser, mapping profiles and the pure mapping engine |
Automation for the shared parameter space; Testing for what is verified |
ORIXScript |
Lexer, parser, AST, compiler, plan, runtime, simulator and debugger, schema, generated reference, presets, editor tools | Automation |
ORIXDJEngine |
TrackBuffer, DeckVoice, RenderCore, AudioOutput, DJEngine, AutomationHost, Recorder, DJSession, AutoDJ, Project, ControlSurface, Anthropic/* |
Audio engine, Deck engine, Mixer, Recording, AI integration |
orix-dj-bench |
Benchmarks, documentation generation, script validation, real-music analysis and offline mixes | Performance, Setup |
The application is organised by feature under App/Sources/Features: Studio (decks and mixer), Decks, Mixer,
Effects, Waveforms, Library, Auto DJ, Automation Studio, Docs, Claude Studio, Recording, MIDI, Performance and
Settings. App/Sources/App holds the entry point, the application model and the root layout;
App/Sources/DesignSystem holds the tokens and shared controls (see design system).
Overall architecture
flowchart TD
subgraph UI["Application process, main thread"]
VIEWS["SwiftUI and AppKit views"]
MODEL["AppModel (main actor)"]
METAL["Waveform renderer (Metal)"]
end
subgraph CONTROL["Control plane (any thread, lock protected)"]
SESSION["DJSession"]
ENGINE["DJEngine"]
HOST["AutomationHost"]
SURFACE["ControlSurface"]
LIB["LibraryStore (SQLite)"]
MIDI["MIDIManager (CoreMIDI)"]
REC["Recorder"]
AI["ScriptAssistant + AnthropicClient"]
end
subgraph RT["Audio render thread (Core Audio)"]
CORE["RenderCore"]
VOICES["4 x DeckVoice"]
FX["Effect racks + master limiter"]
end
DEVICE["Output device (AUHAL)"]
API["api.anthropic.com (optional, user key)"]
VIEWS --> MODEL
MODEL --> SESSION
SESSION --> ENGINE
SESSION --> HOST
SESSION --> LIB
SESSION --> REC
MIDI --> SURFACE
SURFACE --> ENGINE
HOST --> ENGINE
ENGINE -- "timestamped control events (lock-free queue)" --> CORE
CORE -- "state snapshots + notices" --> ENGINE
CORE --> VOICES
CORE --> FX
CORE --> DEVICE
CORE -- "master audio (lock-free ring)" --> REC
MODEL --> AI
AI --> API
MODEL --> METAL
The central design rule is the boundary between the control plane and the render thread:
- Into the render thread there is exactly one path for behaviour:
ControlEventvalues pushed onto a bounded lock-free queue (SPSCQueue<ControlEvent>with a minimum capacity of 4096 inRenderCore). Each event carries the engine sample time at which it applies; zero means "as soon as possible". Output routing is the one exception: the channel indices are atomics read by the render thread. - Out of the render thread there are three paths, none of which can block it: sequence-locked state snapshots
(
SnapshotCell) for positions, meters and timing counters; a notice queue (SPSCQueue<RenderNotice>, minimum capacity 1024) for "track ended", "brake finished" and "release this object"; and the recording ring.
On-screen controls, MIDI controllers and ORIX Script all address the same parameter space (ParamAddress in
DJEngine.swift). There is no separate code path for automation: a script that sets deck.A.volume and a fader that
does so produce the same kind of event.
Objects that the render thread uses but did not create (decoded tracks, effect units) are created on the control side, handed over as unmanaged pointers inside events, and handed back through a notice when replaced, so that they are released off the render thread.
Threads
| Thread | Created by | What runs on it | Rules |
|---|---|---|---|
| Audio render thread | Core Audio, through the AUHAL render callback in AudioOutput.swift |
RenderCore.render: event intake, the four deck voices, channel strips, racks, crossfader, master rack, limiter, meters, cue bus, recording tap, snapshot publication |
Written to avoid allocation, locks and blocking calls. The honest caveats are listed in audio engine. |
| Automation scheduler thread | AutomationHost.startScheduler(); thread name ai.spboucher.orix.dj.automation |
tick() every 4 ms: services the engine (drains notices, advances the master clock, maintains sync), advances every running automation to the clock plus a look-ahead, and emits their commands as timestamped control events |
Runs under the Mach time-constraint policy (period 4 ms, computation 0.4 ms, constraint 2 ms, preemptible). Never touches audio buffers. The default look-ahead is 30 ms (lookaheadSeconds = 0.03); the application clamps the user setting to 5 to 50 ms. The benchmark report's heading says 15 ms, but the benchmark code does not change the default; see automation. |
| Main thread | AppKit | SwiftUI and AppKit views, AppModel (a main-actor class). A timer refreshes live state (positions, meters) 30 times per second and slower state 5 times per second by reading the engine's snapshots. The Metal waveform view draws here. |
Never decodes, analyses or queries the library synchronously for large results. |
| Background work | Dispatch queues in DJSession: ai.spboucher.orix.dj.work (concurrent, user-initiated) and ai.spboucher.orix.dj.analysis (serial, utility) |
Track decoding into TrackBuffer, analysis, import, the Auto DJ timer |
Results reach the interface through DJSession.onChange. |
| Recorder writer | Dispatch queue ai.spboucher.orix.dj.recorder (utility) with a timer |
Drains the recording ring and writes the CAF take | See recording. |
| CoreMIDI | A dedicated run-loop thread (MIDIRunLoopThread) plus CoreMIDI's own callback thread and the queue ai.spboucher.orixdj.midi |
Device notifications, incoming event lists, mapping dispatch into ControlSurface |
Mapping logic itself is pure and has no CoreMIDI dependency. |
| Device notifications | Dispatch queue ai.spboucher.orix.dj.devices |
Core Audio property listeners for device list and default output changes | |
| Network | URLSession (ephemeral configuration) |
The Anthropic client only | See AI integration. |
When no audio device is running (unit tests, the benchmark tool, offline mixes), DJEngine.renderOffline calls the
same RenderCore.render from the calling thread and services the engine after each block. This is how audio
behaviour is tested without hardware; see testing.
Data flow
From a file to sound
MediaImportervalidates a file (extension, readable by AVFoundation, not DRM-protected), reads its tags and stores a row in the SQLite library with a bookmark to the file. The audio itself is never copied.- Loading a deck decodes the whole file on a background queue into a
TrackBuffer: two planar arrays of 32-bit float at the file's own sample rate. Files longer than 150 minutes are refused. - Analysis runs on the decoded buffer (tempo and beat grid, key, loudness, peak, waveform summary). The result is stored in the library, zlib-compressed JSON, so a track is analysed once. See analysis.
DJEnginehands the buffer to the render thread in adeckSetTrackevent. From then on the render thread reads only memory.- The waveform summary (not the audio) is uploaded once as a texture and drawn by a Metal fragment shader. See waveform.
Audio signal flow
One call to RenderCore.render produces one device buffer. Internally the buffer is rendered in chunks of at most
64 frames, and a chunk is cut short when a timed event falls inside it, so that an event takes effect on its exact
sample.
flowchart LR
subgraph DECK["Per deck (x4)"]
V["DeckVoice: resampled or time-stretched playback"]
T["Trim"]
EQ["EQ (3 or 4 bands)"]
F["High-pass / low-pass"]
R["Channel rack (8 slots)"]
FAD["Fader"]
end
XF["Crossfader (side A, side B or through)"]
SUM["Master sum"]
MR["Master rack (8 slots)"]
MV["Master volume"]
LIM["Limiter"]
OUT["Master output pair"]
RECTAP["Recording ring"]
CUE["Cue bus: pre-fader channels blended with master"]
COUT["Cue output pair, or split cue"]
V --> T --> EQ --> F --> R --> FAD --> XF --> SUM --> MR --> MV --> LIM --> OUT
R -- "pre-fader listen" --> CUE
LIM --> RECTAP
LIM -- "cue mix" --> CUE
CUE --> COUT
The details of each stage (filter frequencies, crossfader formulas, limiter, metering) are in mixer and DSP; the two playback paths of a deck are in deck engine.
From a control gesture to the render thread
sequenceDiagram
participant S as Source (view, MIDI mapping or script)
participant E as DJEngine (control plane)
participant Q as Event queue (lock-free)
participant R as RenderCore (render thread)
S->>E: set parameter or trigger action
E->>E: validate, quantise, compute target sample time
E->>Q: push ControlEvent(time, kind, values)
R->>Q: pop at the start of the next render call
R->>R: apply now, or insert into the time-ordered pending list
R->>R: split the chunk at the event time and apply on that sample
R-->>E: state snapshot and notices
A manual gesture carries time zero and is applied at the start of the next buffer, so its latency is at most one buffer plus the device latency. An automation command is computed ahead of the clock by the scheduler and carries an exact sample time; the render core counts how many such tracked events arrived after their target sample. The measured results are in performance.
Automation
ORIX Script source is compiled to a plan, which the runtime executes as cooperative tasks in beat time. The live
AutomationHost and the offline simulator drive the same runtime; only the target differs (the engine, or a
simulated rig). Auto DJ and the Claude Studio proposals are ordinary scripts and go through the same compiler. See
automation and AI integration.
Persistence
| Data | Where | Document |
|---|---|---|
| Library, analysis results, cues, crates, playlists, history, saved scripts, MIDI profiles, settings documents | One SQLite database (WAL mode) managed by LibraryStore |
Persistence |
| Projects | .orixdjproject packages: decks, mixer, effect chains, routing, scripts and MIDI mapping; audio is referenced, never copied |
Persistence |
| Recordings | 32-bit float CAF takes and exported files | Recording |
| User preferences | UserDefaults (AppSettings) |
Setup |
| Anthropic API key | Keychain only | Security report |
What the architecture does not contain
- No audio input path (no microphone, line input, DVS or timecode).
- No plug-in hosting (Audio Units or VST).
- No disk streaming of audio: tracks are fully decoded in memory.
- No network use other than the optional Anthropic client.
- No variable-tempo beat grid.
The reasons for these choices, and the alternatives that were considered, are in the technology evaluation. The comparison with existing software is in the competitive analysis.
Verification status
The engine package had 241 tests in 44 suites passing in the run of 2026-11-21 (see testing). They render audio offline and use CoreMIDI virtual endpoints, temporary SQLite files and an in-process stub transport for the Anthropic client. Not covered by any test or manual check so far: listening evaluation, physical MIDI hardware, multi-channel audio interfaces, the live Anthropic API, and long live sessions. The UI test target contains nine end-to-end tests added on 2026-11-21; no run of them is recorded in this documentation.