SPB Git

Repository Public

overview.md 14.7 KB

# 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 with swift 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 from project.yml by 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: ControlEvent values pushed onto a bounded lock-free queue (SPSCQueue<ControlEvent> with a minimum capacity of 4096 in RenderCore). 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

  1. MediaImporter validates 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.
  2. 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.
  3. 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.
  4. DJEngine hands the buffer to the render thread in a deckSetTrack event. From then on the render thread reads only memory.
  5. 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.

Files main
Menu

Theme