Repository Public
1# Development setup23This 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.45Related pages: [testing](testing.md), [performance](performance.md), [architecture overview](../architecture/overview.md), [persistence](../architecture/persistence.md), [release signing](../release/signing.md), [distribution](../release/distribution.md).67## Requirements89| Item | Value | Source |10|---|---|---|11| macOS (build machine audited) | 27.0 (26A5425a), Apple M5 Max, 18 cores, 48 GB | environment audit |12| Xcode | 27.2, macOS SDK 27.2 | environment audit |13| Swift toolchain | 6.4.2 | environment audit |14| 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` |15| Deployment target | macOS 15.0 (`platforms: [.macOS(.v15)]`, `deploymentTarget.macOS: "15.0"`) | same |16| 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` |17| XcodeGen | required (`xcodegen generate`); version 2.45.4 was installed on the build machine | `Scripts/build.sh` |18| create-dmg | used by `Scripts/package.sh`; if it fails the script falls back to `hdiutil` | `Scripts/package.sh` |19| Python 3 | `/usr/bin/python3` (system) for `localize.py`, `notarize.sh`, `finalize.sh` | scripts |2021Only 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.2223The 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`).2425## Repository layout2627| Path | Content |28|---|---|29| `project.yml` | XcodeGen definition of the app and the UI-test bundle |30| `ORIXDJ.xcodeproj/` | Generated by XcodeGen; ignored by git (`*.xcodeproj/` in `.gitignore`) |31| `App/Info.plist` | Info.plist of the app (regenerated by XcodeGen from the `info.properties` of `project.yml`) |32| `App/Sources/App/` | Entry point (`ORIXDJApp.swift`), `AppModel`, `AppSettings`, `RootView` |33| `App/Sources/DesignSystem/` | `Tokens.swift`, `Components.swift` (see [design system](../design/design-system.md)) |34| `App/Sources/Features/` | One folder per section (Studio, Library, AutomationStudio, ClaudeStudio, Docs, MIDI, Recording, Settings, AutoDJ, Waveforms, ...) |35| `App/Resources/Assets.xcassets` | `AppIcon.appiconset` (written by `Scripts/icon.swift`) and `AccentColor.colorset` |36| `Packages/ORIXDJCore/` | Swift package with the whole engine; no SwiftUI in it |37| `Packages/ORIXDJCore/Sources/` | `ORIXDSP`, `ORIXAnalysis`, `ORIXLibrary`, `ORIXMIDI`, `ORIXScript`, `ORIXDJEngine`, `ORIXDJCore` (umbrella), `orix-dj-bench` (CLI) |38| `Packages/ORIXDJCore/Tests/` | Six test targets, see [testing](testing.md) |39| `UITests/ORIXDJUITests.swift` | UI-test bundle source (nine end-to-end tests on an isolated, silent instance; see [testing](testing.md)) |40| `Scripts/` | Build, check, screenshot, icon, localisation and release scripts |41| `design/icon/` | Icon concepts and the 1024 px master, written by `Scripts/icon.swift` (see [icon design](../design/icon-design.md)) |42| `docs/orix-script/` | User documentation of ORIX Script; bundled into the app as a folder |43| `docs/reports/` | Measured reports (`engine-benchmark.txt`, `real-music-analysis.tsv`) |44| `build/`, `dist/` | Build products and release artifacts; both ignored by git |4546`.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.4748## The Swift package4950`Packages/ORIXDJCore/Package.swift` declares two products: the library `ORIXDJCore` and the executable `orix-dj-bench`.5152| Target | Depends on | Linked system libraries |53|---|---|---|54| `ORIXDSP` | none | Accelerate |55| `ORIXAnalysis` | none | Accelerate |56| `ORIXLibrary` | none | sqlite3, AVFoundation |57| `ORIXMIDI` | none | CoreMIDI |58| `ORIXScript` | `ORIXDSP` | none |59| `ORIXDJEngine` | `ORIXDSP`, `ORIXAnalysis`, `ORIXScript`, `ORIXLibrary`, `ORIXMIDI` | AudioToolbox, CoreAudio, AVFoundation |60| `ORIXDJCore` | all six above | none |61| `orix-dj-bench` | `ORIXDJEngine` | none |6263Each library target except the umbrella has a test target of the same name with the suffix `Tests`.6465## XcodeGen: `project.yml` explained6667The Xcode project is never edited by hand. `xcodegen generate` rebuilds `ORIXDJ.xcodeproj` from `project.yml`.6869### Project-wide settings7071| Setting | Value | Effect |72|---|---|---|73| `bundleIdPrefix` | `ai.spboucher.orix` | prefix for generated identifiers |74| `SWIFT_VERSION` / `SWIFT_STRICT_CONCURRENCY` | `6.0` / `complete` | Swift 6 mode with full concurrency checking |75| `MARKETING_VERSION` / `CURRENT_PROJECT_VERSION` | `1.0.0` / `1` | version and build number, injected into the Info.plist |76| `DEVELOPMENT_TEAM` | `3YM54G49SN` | signing team |77| `ENABLE_HARDENED_RUNTIME` | `YES` | Hardened Runtime in every configuration |78| `ENABLE_USER_SCRIPT_SANDBOXING` | `YES` | build-phase script sandboxing (a build setting, not the App Sandbox) |79| `DEAD_CODE_STRIPPING` | `YES` | |80| `SWIFT_EMIT_LOC_STRINGS`, `LOCALIZATION_PREFERS_STRING_CATALOGS` | `YES` | the compiler extracts localisable strings (`.stringsdata`), consumed by `Scripts/localize.py` |8182Per 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](../release/signing.md).8384### Target `ORIXDJ` (application)8586- 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.87- 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.88- Dependency: the package product `ORIXDJCore`.89- Target settings: `PRODUCT_BUNDLE_IDENTIFIER: ai.spboucher.orix.dj`, `PRODUCT_NAME: ORIX DJ`, `PRODUCT_MODULE_NAME: ORIXDJ`, app icon `AppIcon`, accent colour `AccentColor`.9091### Info.plist keys9293`App/Info.plist` is generated from the `info.properties` block. Besides the standard bundle keys it contains:9495| Key | Value |96|---|---|97| `CFBundleDisplayName` | `ORIX DJ` |98| `LSApplicationCategoryType` | `public.app-category.music` |99| `LSMinimumSystemVersion` | `$(MACOSX_DEPLOYMENT_TARGET)` (15.0) |100| `NSHumanReadableCopyright` | `© 2026 Simon-Pierre Boucher` |101| `NSPrincipalClass` | `NSApplication` |102| `CFBundleLocalizations` | `en`, `fr-CA` |103| `CFBundleDocumentTypes` | "ORIX Script" (`ai.spboucher.orix.dj.script`, Editor, Owner) and "ORIX DJ Project" (`ai.spboucher.orix.dj.project`, Editor, Owner, `LSTypeIsPackage`) |104| `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` |105106There is no usage-description key (`NSMicrophoneUsageDescription` or similar) in the plist: the app declares no audio input.107108### Entitlements109110There 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](../release/signing.md) and the [security report](../reports/security.md).111112### Target `ORIXDJUITests` and scheme113114`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](testing.md).115116## `Scripts/build.sh`117118Usage: `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.119120| Command | What it runs |121|---|---|122| `generate` | `xcodegen generate --quiet` |123| `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 |124| `app` | the same `xcodebuild` Debug build without regenerating the project (safe because sources are a synchronised folder) |125| `core-test` | in `Packages/ORIXDJCore`: `swift test --no-parallel`, filtered to failed-test lines, `Test run with ...` summaries, `=== ORIX...` measurement lines and `error:` lines |126| `uitest` | `xcodegen generate --quiet`, then `xcodebuild ... test` on the scheme, filtered to test-case and summary lines |127| `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 |128129The Debug app is produced at `build/dd/Build/Products/Debug/ORIX DJ.app`.130131Note: the usage message printed for an unknown command omits `app` (`usage: Scripts/build.sh generate|debug|core-test|uitest|bench`), although `app` is implemented.132133## Other scripts134135| Script | What it actually does |136|---|---|137| `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` |138| `Scripts/shot.sh` | `Scripts/shot.sh <out.png> <section> [dark|light] [seconds] [extra app arguments...]`. Compiles `Scripts/tools/winid.swift` to `build/tools/winid` if needed, launches the app binary directly with `-ORIXDataDir <dir> -ORIXSilent YES -ORIXDemo YES -ORIXSection <section> -ORIXAppearance <appearance>`, `-AppleLanguages`, `-AppleLocale`, a fixed main-window frame and `-ApplePersistenceIgnoreState YES`, waits (default 8 s), finds the window ID for the process, captures it with `screencapture -x -o -l <id>`, prints the pixel size and kills the process on exit |139| `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) |140| `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` |141| `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` |142| `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 |143| `Scripts/sign.sh`, `notarize.sh`, `package.sh`, `finalize.sh`, `release.sh` | Release pipeline, documented in [signing](../release/signing.md), [notarization](../release/notarization.md) and [distribution](../release/distribution.md) |144145State 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.146147### Environment variables read by scripts148149| Variable | Script | Meaning | Default |150|---|---|---|---|151| `ORIX_DD` | `build.sh` | DerivedData directory | `build/dd` |152| `ORIX_APP` | `shot.sh` | app bundle to launch | `build/dd/Build/Products/Debug/ORIX DJ.app` |153| `ORIX_DATA` | `shot.sh` | data directory passed as `-ORIXDataDir` | a fresh `mktemp -d /tmp/orixdj-shot.XXXXXX` |154| `ORIX_WINDOW` | `shot.sh` | capture the window whose title contains this text | largest window |155| `ORIX_FRAME` | `shot.sh` | value for the `NSWindow Frame main` default | `80 80 1440 900 0 0 3456 2234` |156| `ORIX_LANG`, `ORIX_LOCALE` | `shot.sh` | `-AppleLanguages` and `-AppleLocale` | `en`, `en_US` |157| `NOTARY_PROFILE` | `notarize.sh` | notarytool keychain profile name | `MacLustr-Notarize` |158159The 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.160161## Launch arguments162163The 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.164165### Core options (`LaunchOptions` in `App/Sources/App/AppModel.swift`)166167| Argument | Type | Meaning |168|---|---|---|169| `-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` |170| `-ORIXSection <name>` | `AppSection` raw value | Open on a section: `studio`, `library`, `effects`, `autoDJ`, `automation`, `docs`, `claude`, `recording`, `midi`, `performance` |171| `-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 |172| `-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 |173| `-ORIXDecks <n>` | int | Number of decks shown (overrides the stored `ui.deckCount`) |174| `-ORIXAppearance <light|dark>` | string | Force the colour scheme of the main and settings windows (`light` gives light, anything else dark) |175| `-ORIXDeckMode <mode>` | `DeckMode` raw value | `standard`, `vinyl`, `performance`, `minimal` |176| `-ORIXScene <text>` | string | Parsed into `LaunchOptions.scene`, but no code reads the value at the time of writing |177178### Feature options179180| Argument | File | Build | Meaning |181|---|---|---|---|182| `-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` |183| `-ORIXSettingsValidate YES` | `Features/Settings/AISettingsTab.swift` | all | Press "Validate" when the AI tab opens, if a key is present and the status is unknown |184| `-ORIXClaudeTask <task>` | `Features/ClaudeStudio/ClaudeStudioView.swift` | all | Preselect the assistant task: `generate`, `explain`, `fix`, `improve`, `effect`, `midi`, `plan` |185| `-ORIXClaudePrompt <text>` | same | all | Fill the prompt and send it 0.9 s later; ignored when no key is available |186| `-ORIXClaudeAutoConfirm YES` | same | effective in Debug only | Confirm the pending proposal without a click, only when the stub transport is active (`access.isStub`) |187| `-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 |188| `-ORIXAutomationTab <tab>` | `Features/AutomationStudio/AutomationStudioState.swift` | all | Bottom panel: `console`, `simulator`, `debugger`, `problems`, `log`, `monitor` |189| `-ORIXAutomationMode <mode>` | same | all | `editor`, `presets`, `builder` |190| `-ORIXAutomationPreset <name>` | same | all | Open a preset of `PresetLibrary` as a new document (takes precedence over the source file) |191| `-ORIXAutomationSourceFile <path>` | same | all | Open a script file as a new document |192| `-ORIXAutomationBreakpoints <l1,l2,...>` | same | all | Comma-separated line numbers set as breakpoints on the active document |193| `-ORIXAutomationBuilderImport YES` | same | all | Import the active document into the visual builder |194| `-ORIXAutomationEditorActions <actions>` | same, `ScriptEditor.perform(actions:)` | all | After 2 s, drive the editor: `caret=L:C`, `type=text`, `fold=L`, `complete`, `return`, separated by `;` |195| `-ORIXConsoleScript <lines>` | same | all | After 3 s, run console lines separated by `;` |196| `-ORIXBuilderSelfCheck YES` | same | `#if DEBUG` | Run `VBRoundTrip.runAll()` and print `ORIX-BUILDER-CHECK PASS|FAIL ...` lines and a summary on standard output |197| `-ORIXLibraryCompact YES` | `Features/Library/LibraryView.swift` | all | Show the compact browser inside the Library section |198| `-ORIXLibrarySelect <n>` | same | `#if DEBUG` | Select the n-th row (1-based) |199| `-ORIXLibrarySmartEditor YES` | same | `#if DEBUG` | Open the smart-crate editor on a new crate |200| `-ORIXDocsChapter <file>` | `Features/Docs/DocsView.swift` | all | Open a chapter by file name (with or without `.md`, or a path suffix) |201| `-ORIXDocsSearch <text>` | same | all | Prefill the documentation search |202| `-ORIXDocsScale <number>` | same | all | Text scale of the reader |203| `-ORIXDocsRunFirst YES` | same | all | Run the first ORIX Script code block of the current chapter |204| `-ORIXAutoDJStart YES` | `Features/AutoDJ/AutoDJView.swift` | `#if DEBUG` | Start Auto DJ on the default queue 4 s after it is loaded |205| `-ORIXRecordDemo <seconds>` | `Features/Recording/RecordingView.swift` | `#if DEBUG` | Record the engine output for that long (a real take), then stop |206| `-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 |207| `-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 |208209Example, as `Scripts/shot.sh` does it:210211```sh212"build/dd/Build/Products/Debug/ORIX DJ.app/Contents/MacOS/ORIX DJ" \213 -ORIXDataDir /tmp/orixdj-dev -ORIXSilent YES -ORIXDemo YES -ORIXSection automation \214 -ORIXAutomationPreset "Bass Swap" -ORIXAutomationTab simulator215```216217## Where data lives218219The 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:220221| Item | Path under the root | Notes |222|---|---|---|223| 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](../architecture/persistence.md) |224| Corrupt database backup | `Library.sqlite.corrupt-<suffix>` | written when the store recovers from a damaged file (behaviour verified by `CorruptionTests`) |225| Recordings | `Recordings/` | takes are recorded as `.caf`; exports go where the user chooses (the save panel opens here). See [recording](../architecture/recording.md) |226| Demo tracks | `Demo Tracks/*.wav` | synthesised by the app on request |227| 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 |228| 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 |229230Outside the data root:231232| Item | Location |233|---|---|234| 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` |235| 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](../architecture/ai-integration.md) |236| 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 |237238## Running the tests239240```sh241Scripts/build.sh core-test # filtered output242cd Packages/ORIXDJCore && swift test --no-parallel # full output243```244245`--no-parallel` matters: several suites measure timing or talk to the system MIDI server. Details, counts and tolerances are in [testing](testing.md).246247## The command-line tool `orix-dj-bench`248249Run from `Packages/ORIXDJCore`. Use a release build for any measurement; the `bench` command prints a warning in a debug build.250251```sh252swift run -c release orix-dj-bench <command>253```254255| Command | Arguments | What it does |256|---|---|---|257| `docs <directory>` | output directory | Writes the generated ORIX Script reference chapters (see below) |258| `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 |259| `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 |260| `devices` | none | Lists audio output devices with transport, channels, sample rates, buffer size range and reported latency |261| `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 |262| `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 |263| `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 |264265`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](performance.md) and [analysis](../architecture/analysis.md). 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.266267## Generating the ORIX Script reference268269Four 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."270271To regenerate after changing the schema:272273```sh274cd Packages/ORIXDJCore && swift run orix-dj-bench docs ../../docs/orix-script275```276277The 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.278279`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:280281```text282=== ORIX-DOCS === 150 examples compiled and simulated, 59 error examples rejected, 59 console lines parsed === END ===283```284285The language itself is documented for users in [the ORIX Script introduction](../orix-script/introduction.md) and the [API reference](../orix-script/api-reference.md).286