SPB Git

Repository Public License

overview.md 4.3 KB 63 lines markdown

1<!--2ORIX Audio3File: docs/architecture/overview.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Architecture Overview910ORIX Audio is two things in one repository: a UI-free Swift package that does the work, and a SwiftUI app that drives it.1112| Layer | Location | Depends on | Tested by |13|---|---|---|---|14| **ORIXAudioCore** | `Core/Sources/ORIXAudioCore` | Accelerate, AVFoundation, Speech, FoundationModels | 83 tests on macOS (`Scripts/test.sh core`) |15| **App services** | `ORIXAudio/Services` | ORIXAudioCore, AVFoundation, SwiftData, ActivityKit | 21 tests in the simulator (`Scripts/test.sh app`) |16| **Features** | `ORIXAudio/Features` | services, design system | 9 UI tests (`Scripts/test.sh ui`) |17| **Live Activity** | `ORIXAudioWidgets`, `Shared` | ActivityKit, WidgetKit, App Intents | not testable without a device |1819The 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.2021## Data flow2223```mermaid24flowchart LR25  Mic[Audio input] --> Capture[AudioCaptureEngine]26  Capture --> Master[(CAF master)]27  Capture --> Visuals[LiveVisuals] --> RecorderUI[Recorder screen]28  Master --> Finalizer[RecordingFinalizer] --> File[(Library file)]29  Import[MediaImporter] --> File30  File --> Analyzer[AudioAnalyzer] --> Sidecars[(waveform + analysis)]31  File --> Speech[TranscriptionEngine] --> Transcript[(transcript.json)]32  Transcript --> Notes[MeetingIntelligence] --> NotesFile[(notes.json)]33  File --> Editor[EditDocument + EditRenderer] --> NewFile[(New recording)]34  File --> Export[ExportService]35```3637<p align="center"><img src="../assets/diagrams/capture-pipeline.svg" alt="Audio capture pipeline" width="820"></p>3839## State and concurrency4041- **`AppModel`** (main actor, `@Observable`) owns the SwiftData container and wires the services together. It is the only object views receive through the environment besides `AppSettings`.42- **`RecorderController`** (main actor) owns the session lifecycle. It never touches audio samples.43- **`AudioCaptureEngine`** is 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](audio-engine.md).44- **`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.45- **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.4647## Design decisions4849| Decision | Reason |50|---|---|51| 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. |52| 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). |53| Two rings and two threads rather than one queue | A stalled analysis can never delay a write, and overflow is explicit and counted. |54| Tiles for the spectrogram | Memory stays bounded for multi-hour files; only what is on screen is analysed. |55| Canvas and Core Graphics rather than Metal | Measured CPU cost is far inside a frame. See [visualization.md](visualization.md). |56| No server path for speech or notes | Privacy claim that can be verified by reading the code: there is no networking code. |57| Edit decision list, render to a new file | Originals are never modified; undo is a stack of small value types. |58| No third-party dependencies | Apple's frameworks already provide the mature primitives; fewer moving parts to audit. |5960## Further reading6162[Audio engine](audio-engine.md) · [Recording](recording.md) · [Background audio](background-audio.md) · [DSP](dsp.md) · [Visualization](visualization.md) · [Transcription](transcription.md) · [Storage](storage.md)63
Files main
Menu

Theme