Architecture Overview
ORIX Audio is two things in one repository: a UI-free Swift package that does the work, and a SwiftUI app that drives it.
| Layer | Location | Depends on | Tested by |
|---|---|---|---|
| ORIXAudioCore | Core/Sources/ORIXAudioCore |
Accelerate, AVFoundation, Speech, FoundationModels | 83 tests on macOS (Scripts/test.sh core) |
| App services | ORIXAudio/Services |
ORIXAudioCore, AVFoundation, SwiftData, ActivityKit | 21 tests in the simulator (Scripts/test.sh app) |
| Features | ORIXAudio/Features |
services, design system | 9 UI tests (Scripts/test.sh ui) |
| Live Activity | ORIXAudioWidgets, Shared |
ActivityKit, WidgetKit, App Intents | not testable without a device |
The split exists for one reason: signal processing has to be provable. Everything in the package can be run against a synthetic signal with a known answer, on a Mac, in about a minute, with no simulator.
Data flow
flowchart LR Mic[Audio input] --> Capture[AudioCaptureEngine] Capture --> Master[(CAF master)] Capture --> Visuals[LiveVisuals] --> RecorderUI[Recorder screen] Master --> Finalizer[RecordingFinalizer] --> File[(Library file)] Import[MediaImporter] --> File File --> Analyzer[AudioAnalyzer] --> Sidecars[(waveform + analysis)] File --> Speech[TranscriptionEngine] --> Transcript[(transcript.json)] Transcript --> Notes[MeetingIntelligence] --> NotesFile[(notes.json)] File --> Editor[EditDocument + EditRenderer] --> NewFile[(New recording)] File --> Export[ExportService]
State and concurrency
AppModel(main actor,@Observable) owns the SwiftData container and wires the services together. It is the only object views receive through the environment besidesAppSettings.RecorderController(main actor) owns the session lifecycle. It never touches audio samples.AudioCaptureEngineis not an actor. It runs three threads of its own — the engine's tap, a writer and an analyser — and talks to the rest of the app through two wait-free ring buffers, a few atomics and one mutex-protected store. See audio-engine.md.ProcessingCenter(main actor) starts analysis, transcription and notes jobs on detached tasks, tracks their progress and cancellation, and bumps a revision counter when a sidecar changes so open views reload.- Sidecar files, not the database, hold derived data. The SwiftData store keeps what the library list needs (title, duration, format, status flags). Waveforms, reports, transcripts and notes are files next to the audio. Deleting a recording is deleting a folder.
Design decisions
| Decision | Reason |
|---|---|
| Always capture to uncompressed PCM, encode on stop | An AAC or Apple Lossless file that isn't closed properly is unreadable; a PCM master with an open-ended data chunk is always readable. Reliability outranks temporary disk use. |
Own CAF writer instead of AVAudioFile for the master |
Full control over what is on disk after each write, and a header that never needs patching. AVAudioFile reads the result (tested for 16-bit, 24-bit and float). |
| Two rings and two threads rather than one queue | A stalled analysis can never delay a write, and overflow is explicit and counted. |
| Tiles for the spectrogram | Memory stays bounded for multi-hour files; only what is on screen is analysed. |
| Canvas and Core Graphics rather than Metal | Measured CPU cost is far inside a frame. See visualization.md. |
| No server path for speech or notes | Privacy claim that can be verified by reading the code: there is no networking code. |
| Edit decision list, render to a new file | Originals are never modified; undo is a stack of small value types. |
| No third-party dependencies | Apple's frameworks already provide the mature primitives; fewer moving parts to audit. |
Further reading
Audio engine · Recording · Background audio · DSP · Visualization · Transcription · Storage