Performance Engineering
Measured results are in docs/reports/performance.md. This page is about how the app is built to stay fast and where to look when it isn't.
Priorities
- Never lose audio.
- Never let drawing or analysis delay capture.
- Keep memory bounded regardless of recording length.
- Then make it smooth.
Rules the code follows
| Rule | Where |
|---|---|
| The tap does copies and vector arithmetic only — no I/O, no locks | AudioCaptureEngine.ingest |
| Buffers between threads are bounded and wait-free; overflow is counted, not hidden | SPSCRingBuffer |
File writes and fsync happen on a dedicated thread |
writerLoop |
| Analysis runs on its own thread and publishes through one short critical section | analysisLoop, LiveVisuals |
| Live history is capped | 8192 buckets, 1024 columns |
| Files are processed in chunks | analyser 65 536 frames, renderer 32 768, importer per sample buffer |
| Long-file views compute only what is visible | SpectrogramTileStore, WaveformSummary levels |
| Derived data is cached on disk | waveform.owf, analysis.json |
| Every long operation can be cancelled | analyser, renderer, transcription, notes, workflows |
| Heavy work leaves the main actor | Task.detached for analysis, rendering, export, tile rasterisation |
Memory
| Structure | Size |
|---|---|
| Writer ring | 4 s of audio: about 2 MB at 48 kHz stereo (float) after rounding to a power of two |
| Analysis ring | 2 s mono: about 0.5 MB |
| Live waveform history | 8192 × 40 B ≈ 330 kB |
| Live spectrogram history | 1024 columns × 513 bins × 4 B ≈ 2.1 MB |
| Waveform summary | 40 B per 512 samples: about 13.5 MB per hour at 48 kHz, plus the smaller pyramid levels |
| Spectrogram tile | 256 columns × (N/2 + 1) bins × 4 B: about 1 MB at N = 2048; 28 tiles kept |
The waveform summary of a very long file is the largest thing held in memory for a recording; nothing else grows with duration.
Disk
A session writes uncompressed PCM until it is stopped: about 5.8 MB per minute for 48 kHz mono 16-bit and 17.3 MB per minute for 48 kHz stereo 24-bit. The app refuses to start under 128 MB free and stops itself under 64 MB.
Battery
No measurement exists. By design, a locked device does no drawing (SwiftUI does not render while the app is in the background), leaving the capture, writer and analysis threads. The analysis thread keeps running under lock so meters are live on return; if device measurements show it matters, suspending analysis while the scene is in the background is a small change.
How to measure
cd Core && swift build -c release
"$(swift build -c release --show-bin-path)/orix-bench" # DSP, analysis and export throughput
Scripts/bench-transcription.sh # transcription speed and error ratesOn a device, use Instruments: Time Profiler on the three named threads (ai.spboucher.orix.audio.writer, .analysis, and the engine's tap), Allocations during a one-hour recording, and Energy Log with the screen locked. None of this has been done yet.
Known costs
- Loudness with true peak is the slowest per-sample stage (about 634× real time on the development Mac) because of the 48-tap oversampler.
- The noise reducer needs an extra pass over the audio to build its noise profile.
- The first transcription in a language may wait several minutes for a model download.