SPB Git

Repository Public License

overview.md 4.3 KB

# 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]

Audio capture pipeline

# 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 besides AppSettings.
  • RecorderController (main actor) owns the session lifecycle. It never touches audio samples.
  • 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.
  • 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

Files main
Menu

Theme