SPB Git

Repository Public

setup.md 27.8 KB

# Development setup

This page describes how to build, run and inspect ORIX DJ from a checkout: what must be installed, how the Xcode project is generated, what every script in Scripts/ does, the launch arguments the app understands, and where it keeps its data. It documents the repository as it is; anything that was not run or not verified is marked as such.

Related pages: testing, performance, architecture overview, persistence, release signing, distribution.

# Requirements

Item Value Source
macOS (build machine audited) 27.0 (26A5425a), Apple M5 Max, 18 cores, 48 GB environment audit
Xcode 27.2, macOS SDK 27.2 environment audit
Swift toolchain 6.4.2 environment audit
Swift language mode 6 (swiftLanguageModes: [.v6] in the package, SWIFT_VERSION: "6.0" and SWIFT_STRICT_CONCURRENCY: complete in the app) Packages/ORIXDJCore/Package.swift, project.yml
Deployment target macOS 15.0 (platforms: [.macOS(.v15)], deploymentTarget.macOS: "15.0") same
Architecture arm64 only. Every xcodebuild call uses -destination 'platform=macOS,arch=arm64'; the Release configuration sets ARCHS: arm64 Scripts/build.sh, Scripts/sign.sh, project.yml
XcodeGen required (xcodegen generate); version 2.45.4 was installed on the build machine Scripts/build.sh
create-dmg used by Scripts/package.sh; if it fails the script falls back to hdiutil Scripts/package.sh
Python 3 /usr/bin/python3 (system) for localize.py, notarize.sh, finalize.sh scripts

Only arm64 on the machine above was built and tested. Building on an Intel Mac, on an older Xcode, or running on macOS 15 was not verified.

The package has no third-party dependencies. It links system frameworks only: Accelerate (ORIXDSP, ORIXAnalysis), sqlite3 and AVFoundation (ORIXLibrary), CoreMIDI (ORIXMIDI), AudioToolbox, CoreAudio and AVFoundation (ORIXDJEngine).

# Repository layout

Path Content
project.yml XcodeGen definition of the app and the UI-test bundle
ORIXDJ.xcodeproj/ Generated by XcodeGen; ignored by git (*.xcodeproj/ in .gitignore)
App/Info.plist Info.plist of the app (regenerated by XcodeGen from the info.properties of project.yml)
App/Sources/App/ Entry point (ORIXDJApp.swift), AppModel, AppSettings, RootView
App/Sources/DesignSystem/ Tokens.swift, Components.swift (see design system)
App/Sources/Features/ One folder per section (Studio, Library, AutomationStudio, ClaudeStudio, Docs, MIDI, Recording, Settings, AutoDJ, Waveforms, ...)
App/Resources/Assets.xcassets AppIcon.appiconset (written by Scripts/icon.swift) and AccentColor.colorset
Packages/ORIXDJCore/ Swift package with the whole engine; no SwiftUI in it
Packages/ORIXDJCore/Sources/ ORIXDSP, ORIXAnalysis, ORIXLibrary, ORIXMIDI, ORIXScript, ORIXDJEngine, ORIXDJCore (umbrella), orix-dj-bench (CLI)
Packages/ORIXDJCore/Tests/ Six test targets, see testing
UITests/ORIXDJUITests.swift UI-test bundle source (nine end-to-end tests on an isolated, silent instance; see testing)
Scripts/ Build, check, screenshot, icon, localisation and release scripts
design/icon/ Icon concepts and the 1024 px master, written by Scripts/icon.swift (see icon design)
docs/orix-script/ User documentation of ORIX Script; bundled into the app as a folder
docs/reports/ Measured reports (engine-benchmark.txt, real-music-analysis.tsv)
build/, dist/ Build products and release artifacts; both ignored by git

.gitignore also excludes credentials and signing material (*.p12, *.p8, *.cer, provisioning profiles, keychains, .env*, asc.env, notary*.json, AuthKey_*), audio files (*.wav, *.aiff, *.aif, *.mp3, *.flac, *.m4a) and SQLite files. Test audio is synthesised at run time and never committed.

# The Swift package

Packages/ORIXDJCore/Package.swift declares two products: the library ORIXDJCore and the executable orix-dj-bench.

Target Depends on Linked system libraries
ORIXDSP none Accelerate
ORIXAnalysis none Accelerate
ORIXLibrary none sqlite3, AVFoundation
ORIXMIDI none CoreMIDI
ORIXScript ORIXDSP none
ORIXDJEngine ORIXDSP, ORIXAnalysis, ORIXScript, ORIXLibrary, ORIXMIDI AudioToolbox, CoreAudio, AVFoundation
ORIXDJCore all six above none
orix-dj-bench ORIXDJEngine none

Each library target except the umbrella has a test target of the same name with the suffix Tests.

# XcodeGen: project.yml explained

The Xcode project is never edited by hand. xcodegen generate rebuilds ORIXDJ.xcodeproj from project.yml.

# Project-wide settings

Setting Value Effect
bundleIdPrefix ai.spboucher.orix prefix for generated identifiers
SWIFT_VERSION / SWIFT_STRICT_CONCURRENCY 6.0 / complete Swift 6 mode with full concurrency checking
MARKETING_VERSION / CURRENT_PROJECT_VERSION 1.0.0 / 1 version and build number, injected into the Info.plist
DEVELOPMENT_TEAM 3YM54G49SN signing team
ENABLE_HARDENED_RUNTIME YES Hardened Runtime in every configuration
ENABLE_USER_SCRIPT_SANDBOXING YES build-phase script sandboxing (a build setting, not the App Sandbox)
DEAD_CODE_STRIPPING YES
SWIFT_EMIT_LOC_STRINGS, LOCALIZATION_PREFERS_STRING_CATALOGS YES the compiler extracts localisable strings (.stringsdata), consumed by Scripts/localize.py

Per configuration: Debug defines DEBUG and uses automatic signing. Release uses whole-module compilation, manual signing with CODE_SIGN_IDENTITY: "Developer ID Application", CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NO, OTHER_CODE_SIGN_FLAGS: "--timestamp" and ARCHS: arm64. The release side is described in signing.

# Target ORIXDJ (application)

  • Sources: App/Sources as a synchronised folder (type: syncedFolder), so new source files do not require regenerating the project. This is why Scripts/build.sh app can build without running XcodeGen.
  • Resources: App/Resources (with an exclude for Docs/**; no such folder exists at the time of writing) and docs/orix-script added with type: folder, buildPhase: resources. The folder is copied as a folder reference, so the bundle contains Contents/Resources/orix-script/ with the Markdown chapters, examples/ and manifest.json. The in-app documentation browser (App/Sources/Features/Docs/DocsStore.swift) reads it from there, and Scripts/sign.sh refuses to continue if orix-script/manifest.json is missing from the built bundle.
  • Dependency: the package product ORIXDJCore.
  • Target settings: PRODUCT_BUNDLE_IDENTIFIER: ai.spboucher.orix.dj, PRODUCT_NAME: ORIX DJ, PRODUCT_MODULE_NAME: ORIXDJ, app icon AppIcon, accent colour AccentColor.

# Info.plist keys

App/Info.plist is generated from the info.properties block. Besides the standard bundle keys it contains:

Key Value
CFBundleDisplayName ORIX DJ
LSApplicationCategoryType public.app-category.music
LSMinimumSystemVersion $(MACOSX_DEPLOYMENT_TARGET) (15.0)
NSHumanReadableCopyright © 2026 Simon-Pierre Boucher
NSPrincipalClass NSApplication
CFBundleLocalizations en, fr-CA
CFBundleDocumentTypes "ORIX Script" (ai.spboucher.orix.dj.script, Editor, Owner) and "ORIX DJ Project" (ai.spboucher.orix.dj.project, Editor, Owner, LSTypeIsPackage)
UTExportedTypeDeclarations ai.spboucher.orix.dj.script conforming to public.plain-text, extension orixdj; ai.spboucher.orix.dj.project conforming to com.apple.package, extension orixdjproject

There is no usage-description key (NSMicrophoneUsageDescription or similar) in the plist: the app declares no audio input.

# Entitlements

There is no .entitlements file in the repository and project.yml sets no CODE_SIGN_ENTITLEMENTS. The app is therefore not sandboxed (no App Sandbox entitlement) and the Release build is signed without custom entitlements; CODE_SIGN_INJECT_BASE_ENTITLEMENTS: NO keeps Xcode from adding com.apple.security.get-task-allow, and Scripts/sign.sh fails if that entitlement is found. See signing and the security report.

# Target ORIXDJUITests and scheme

ORIXDJUITests is a bundle.ui-testing target built from UITests/, depending on the app target, with bundle identifier ai.spboucher.orix.dj.uitests, a generated Info.plist, automatic signing and CODE_SIGN_IDENTITY: "Apple Development". The single scheme ORIXDJ builds the app, runs with Debug, tests ORIXDJUITests with Debug and archives with Release. The content of the UI-test bundle is described in testing.

# Scripts/build.sh

Usage: Scripts/build.sh generate|debug|app|core-test|uitest|bench (default debug). The script changes to the repository root first. The environment variable ORIX_DD overrides the DerivedData directory (default build/dd), which lets two checkouts or two people build in parallel without sharing intermediates.

Command What it runs
generate xcodegen generate --quiet
debug xcodegen generate --quiet, then xcodebuild -project ORIXDJ.xcodeproj -scheme ORIXDJ -configuration Debug -derivedDataPath "$DD" -destination 'platform=macOS,arch=arm64' build. The output is filtered to errors, "unre..." warnings, ** BUILD ... and test summary lines
app the same xcodebuild Debug build without regenerating the project (safe because sources are a synchronised folder)
core-test in Packages/ORIXDJCore: swift test --no-parallel, filtered to failed-test lines, Test run with ... summaries, === ORIX... measurement lines and error: lines
uitest xcodegen generate --quiet, then xcodebuild ... test on the scheme, filtered to test-case and summary lines
bench in Packages/ORIXDJCore: swift run -c release orix-dj-bench bench <seconds> with the second argument as duration (default 20), with SwiftPM progress lines removed

The Debug app is produced at build/dd/Build/Products/Debug/ORIX DJ.app.

Note: the usage message printed for an unknown command omits app (usage: Scripts/build.sh generate|debug|core-test|uitest|bench), although app is implemented.

# Other scripts

Script What it actually does
Scripts/check.sh Repository hygiene, exit status 1 on any finding. Six checks: (1) Author: Simon-Pierre Boucher within the first 16 lines of every tracked or untracked-unignored *.swift, *.sh, *.py and project.yml; (2) no signing material, .env or audio file among the files git sees; (3) no private-key block, App Store Connect key name, sk-ant- key, GitHub token or private LAN / tunnel address pattern in text files (the test placeholder sk-ant-test-0000... is excluded); (4) URLSession, NWConnection, CFSocket, import Network, WKWebView only under Sources/ORIXDJEngine/Anthropic/, Features/ClaudeStudio/ and Features/Settings/; (5) no print/NSLog/os_log/Logger call mentioning apiKey or api_key; (6) none of AuthorizationExecuteWithPrivileges, SMJobBless, NSAppleScript, /usr/bin/sudo, dlopen(, Process(), NSTask, posix_spawn in app or package sources. Prints clean or FINDINGS
Scripts/shot.sh `Scripts/shot.sh <out.png>
[dark
Scripts/tools/winid.swift Prints windowID width height title for the on-screen windows owned by a PID (first argument), largest first, using CGWindowListCopyWindowInfo. Optional second argument: window layer to keep (default 0)
Scripts/icon.swift swift Scripts/icon.swift from the repository root. Draws five icon concepts and the final icon with Core Graphics on a 1024 px canvas, writes design/icon/concept-*.png, design/icon/orix-dj-icon-1024.png, design/icon/concepts-sheet.png, copies the master and the sheet to docs/assets/icon.png and docs/assets/icon-concepts.png, then writes the ten PNGs (16 to 512 pt at 1x and 2x) and Contents.json of App/Resources/Assets.xcassets/AppIcon.appiconset
Scripts/dmg-background.swift swift Scripts/dmg-background.swift <out.png> (default dmg-background.png). Draws the 660 x 420 pt disk-image background at 2x (1320 x 840 px): gradient, title, tagline, the text "Drag ORIX DJ to the Applications folder" and an arrow. Called by Scripts/package.sh
Scripts/localize.py Rebuilds App/Resources/Localizable.xcstrings from the .stringsdata files the compiler left in build/dd or build/DerivedDataRelease (newest build directory only) with xcrun xcstringstool sync, then fills fr-CA values from Scripts/translations-fr-CA.json. Keys without two consecutive letters are marked shouldTranslate: false. Prints the number of keys, translated, missing and unused translations; --missing writes build/missing-fr.json. If no .stringsdata exists it keeps an existing catalog or exits with an error asking to build first
Scripts/sign.sh, notarize.sh, package.sh, finalize.sh, release.sh Release pipeline, documented in signing, notarization and distribution

State of localisation at the time of writing: neither App/Resources/Localizable.xcstrings nor Scripts/translations-fr-CA.json exists in the repository. localize.py handles a missing translation file (all keys are then reported as missing), so the bundle currently declares fr-CA in CFBundleLocalizations without French strings.

# Environment variables read by scripts

Variable Script Meaning Default
ORIX_DD build.sh DerivedData directory build/dd
ORIX_APP shot.sh app bundle to launch build/dd/Build/Products/Debug/ORIX DJ.app
ORIX_DATA shot.sh data directory passed as -ORIXDataDir a fresh mktemp -d /tmp/orixdj-shot.XXXXXX
ORIX_WINDOW shot.sh capture the window whose title contains this text largest window
ORIX_FRAME shot.sh value for the NSWindow Frame main default 80 80 1440 900 0 0 3456 2234
ORIX_LANG, ORIX_LOCALE shot.sh -AppleLanguages and -AppleLocale en, en_US
NOTARY_PROFILE notarize.sh notarytool keychain profile name MacLustr-Notarize

The Swift code reads no environment variable: a search of App/Sources and the package sources for ProcessInfo.processInfo.environment and getenv finds nothing. All run-time switches are launch arguments.

# Launch arguments

The app does not parse CommandLine.arguments. Every option is read through UserDefaults (-Name value on the command line lands in the argument domain), so the syntax is -ORIXSection library, -ORIXSilent YES. They exist for Scripts/shot.sh screenshots and for future UI tests.

# Core options (LaunchOptions in App/Sources/App/AppModel.swift)

Argument Type Meaning
-ORIXDataDir <dir> path Use this directory as the data root instead of Application Support. Also switches the instance to isolated mode: preferences come from the suite ai.spboucher.orix.dj.test (cleared of audio., ui., ai., mixer., record. keys at start) and the Keychain service gets the suffix .test
-ORIXSection <name> AppSection raw value Open on a section: studio, library, effects, autoDJ, automation, docs, claude, recording, midi, performance
-ORIXSilent YES bool Do not open an audio device. A thread named orix-silent-render calls renderOffline(frames: 512) paced in real time, so meters, waveforms and automation move while nothing is played
-ORIXDemo YES bool Install the synthesised demo tracks (90 s each), load them on the visible decks, start deck A at 20 s and cue deck B at 8 s
-ORIXDecks <n> int Number of decks shown (overrides the stored ui.deckCount)
`-ORIXAppearance <light dark>` string
-ORIXDeckMode <mode> DeckMode raw value standard, vinyl, performance, minimal
-ORIXScene <text> string Parsed into LaunchOptions.scene, but no code reads the value at the time of writing

# Feature options

Argument File Build Meaning
-ORIXOpenSettings <tab> Features/Settings/SettingsSupport.swift all Open the Settings window 0.6 s after launch on a tab: audio, mixer, library, appearance, ai, automation, about
-ORIXSettingsValidate YES Features/Settings/AISettingsTab.swift all Press "Validate" when the AI tab opens, if a key is present and the status is unknown
-ORIXClaudeTask <task> Features/ClaudeStudio/ClaudeStudioView.swift all Preselect the assistant task: generate, explain, fix, improve, effect, midi, plan
-ORIXClaudePrompt <text> same all Fill the prompt and send it 0.9 s later; ignored when no key is available
-ORIXClaudeAutoConfirm YES same effective in Debug only Confirm the pending proposal without a click, only when the stub transport is active (access.isStub)
-ORIXClaudeStub YES Features/ClaudeStudio/ClaudeAccess.swift #if DEBUG Replace the network transport with the local ClaudeStub client; no request leaves the Mac and the placeholder key stub-transport-no-key is used
-ORIXAutomationTab <tab> Features/AutomationStudio/AutomationStudioState.swift all Bottom panel: console, simulator, debugger, problems, log, monitor
-ORIXAutomationMode <mode> same all editor, presets, builder
-ORIXAutomationPreset <name> same all Open a preset of PresetLibrary as a new document (takes precedence over the source file)
-ORIXAutomationSourceFile <path> same all Open a script file as a new document
-ORIXAutomationBreakpoints <l1,l2,...> same all Comma-separated line numbers set as breakpoints on the active document
-ORIXAutomationBuilderImport YES same all Import the active document into the visual builder
-ORIXAutomationEditorActions <actions> same, ScriptEditor.perform(actions:) all After 2 s, drive the editor: caret=L:C, type=text, fold=L, complete, return, separated by ;
-ORIXConsoleScript <lines> same all After 3 s, run console lines separated by ;
-ORIXBuilderSelfCheck YES same #if DEBUG Run VBRoundTrip.runAll() and print `ORIX-BUILDER-CHECK PASS
-ORIXLibraryCompact YES Features/Library/LibraryView.swift all Show the compact browser inside the Library section
-ORIXLibrarySelect <n> same #if DEBUG Select the n-th row (1-based)
-ORIXLibrarySmartEditor YES same #if DEBUG Open the smart-crate editor on a new crate
-ORIXDocsChapter <file> Features/Docs/DocsView.swift all Open a chapter by file name (with or without .md, or a path suffix)
-ORIXDocsSearch <text> same all Prefill the documentation search
-ORIXDocsScale <number> same all Text scale of the reader
-ORIXDocsRunFirst YES same all Run the first ORIX Script code block of the current chapter
-ORIXAutoDJStart YES Features/AutoDJ/AutoDJView.swift #if DEBUG Start Auto DJ on the default queue 4 s after it is loaded
-ORIXRecordDemo <seconds> Features/Recording/RecordingView.swift #if DEBUG Record the engine output for that long (a real take), then stop
-ORIXRecordExport YES same #if DEBUG After the demo take, export it (normalised, fade in 0.5 s, fade out 1 s) into the Recordings folder
-ORIXMIDIDemo YES Features/MIDI/MIDIDemo.swift #if DEBUG (whole file) Create a real CoreMIDI virtual source "ORIX Virtual Controller" in the app process, store and activate an example profile, and send a short sequence of messages through the system

Example, as Scripts/shot.sh does it:

sh
"build/dd/Build/Products/Debug/ORIX DJ.app/Contents/MacOS/ORIX DJ" \
  -ORIXDataDir /tmp/orixdj-dev -ORIXSilent YES -ORIXDemo YES -ORIXSection automation \
  -ORIXAutomationPreset "Bass Swap" -ORIXAutomationTab simulator

# Where data lives

The data root is ~/Library/Application Support/ORIX DJ/ (FileManager.urls(for: .applicationSupportDirectory, in: .userDomainMask)[0] plus ORIX DJ), or the directory given with -ORIXDataDir. The app is not sandboxed, so this is the real user Library, not a container. SessionDirectories (Packages/ORIXDJCore/Sources/ORIXDJEngine/Session.swift) defines the content:

Item Path under the root Notes
Library database Library.sqlite (plus SQLite -wal / -shm files) tracks, cues, analysis, crates, playlists, history, scripts and their versions, MIDI profiles (stored as documents), settings such as midi.activeProfile. See persistence
Corrupt database backup Library.sqlite.corrupt-<suffix> written when the store recovers from a damaged file (behaviour verified by CorruptionTests)
Recordings Recordings/ takes are recorded as .caf; exports go where the user chooses (the save panel opens here). See recording
Demo tracks Demo Tracks/*.wav synthesised by the app on request
Autosave Autosave.orixdjproject/ written every 900 refresh ticks at 30 Hz (30 s) while a deck holds a track, and on quit; offered as "Restore Previous Session" in the Studio when all decks are empty
Projects wherever the user saves them, extension .orixdjproject a package containing project.json and Scripts/<name>.orixdj; written to a temporary sibling and swapped in

Outside the data root:

Item Location
Preferences UserDefaults.standard of bundle ai.spboucher.orix.dj (keys audio.deviceUID, audio.sampleRate, audio.bufferFrames, audio.masterLeft, audio.cueLeft, audio.splitCue, mixer.fourBandEQ, ui.deckCount, ui.deckMode, ui.palette, ui.appearance, ui.waveformZoom, record.format, ai.anthropic, ai.models). Isolated instances use the suite ai.spboucher.orix.dj.test
Anthropic API key Keychain generic password, service ai.spboucher.orix.dj.anthropic, account api-key, label "ORIX DJ – Anthropic API key", accessibility kSecAttrAccessibleWhenUnlockedThisDeviceOnly (APIKeyStore in Anthropic/AnthropicClient.swift). Isolated instances use the service ai.spboucher.orix.dj.anthropic.test. The key is never written to preferences or project files. See AI integration
Logs none on disk. The automation log is kept in memory (AppModel.logLines, capped at 1500 lines) and shown in the Automation Studio; no log file and no os.Logger use was found in the sources

# Running the tests

sh
Scripts/build.sh core-test          # filtered output
cd Packages/ORIXDJCore && swift test --no-parallel   # full output

--no-parallel matters: several suites measure timing or talk to the system MIDI server. Details, counts and tolerances are in testing.

# The command-line tool orix-dj-bench

Run from Packages/ORIXDJCore. Use a release build for any measurement; the bench command prints a warning in a debug build.

sh
swift run -c release orix-dj-bench <command>
Command Arguments What it does
docs <directory> output directory Writes the generated ORIX Script reference chapters (see below)
check <file.orixdj> script file Compiles the script, prints diagnostics, simulates every automation and prints decks used, length, simulated beats, action count and final state. Exit status 1 on a compile or run-time error
bench [seconds] seconds of audio per case, default 20 Offline render cost for eight deck / buffer configurations (mean, p99, max, budget, load, clipped blocks), cost of each effect on 4000 blocks of 512 frames, time-stretch pitch and residual at seven rates, analysis time of a synthesised 5-minute track, automation scheduling statistics
devices none Lists audio output devices with transport, channels, sample rates, buffer size range and reported latency
live [seconds] [buffer] defaults 20 and 256 Opens the default output device with the master at -60 dB, loads four synthesised decks with key lock and 14 effects, runs two stress automations and reports render-callback and scheduler statistics from the real-time thread
analyze <folder> folder of audio files Decodes and analyses every flac, mp3, m4a, wav, aif, aiff, caf, aac file and prints a tab-separated table plus a summary line
mix <a> <b> <out.wav> [preset] two audio files, output path, preset name (default Bass Swap) Offline render at 48 kHz with 256-frame buffers: decode, analyse, apply the suggested gain (clamped to -12...+6 dB), key lock on, 40 s of the first track, the preset transition, 30 s of the second track, written as WAV with a one-line report

docs/reports/engine-benchmark.txt is the output of bench and docs/reports/real-music-analysis.tsv the output of analyze; both are discussed in performance and analysis. The offline maxima of bench include scheduler preemption because the benchmark does not run on a real-time thread. The two transitions rendered with mix so far have been measured but nobody has listened to them yet.

# Generating the ORIX Script reference

Four chapters of docs/orix-script/ are generated from the language schema by ReferenceGenerator.generatedChapters (Packages/ORIXDJCore/Sources/ORIXScript/Reference.swift): deck-api.md, mixer-api.md, effects-api.md and api-reference.md. Each carries the note "This chapter is generated from the language schema (swift run orix-dj-bench docs). Do not edit it by hand."

To regenerate after changing the schema:

sh
cd Packages/ORIXDJCore && swift run orix-dj-bench docs ../../docs/orix-script

The command needs the output directory as its argument (the note in the generated files and the test failure message omit it). The other chapters, examples/ and manifest.json are written by hand; no generator for manifest.json exists in the repository. manifest.json is an array of { "title", "file" } entries (29 at the time of writing) that defines the chapter order of the in-app browser.

DocsTests (Tests/ORIXScriptTests/DocsTests.swift) keeps this honest on every test run: the generated chapters must be byte-identical to what the generator produces, every manifest entry must point to a file of more than 400 characters, every fenced orixdj example must compile and simulate, every orixdj-error example must be rejected, and every console line must parse. The test prints one line, which in today's run was:

text
=== ORIX-DOCS === 150 examples compiled and simulated, 59 error examples rejected, 59 console lines parsed === END ===

The language itself is documented for users in the ORIX Script introduction and the API reference.

Files main
Menu

Theme