Audio Engine
ORIXAudio/Services/AudioCaptureEngine.swift owns the AVAudioEngine input tap and two worker threads.
Mermaid source
flowchart LR In[AVAudioEngine input node] --> Tap[Tap block: copy only] Tap --> WR[Writer ring 4 s] --> WT[Writer thread] --> CAF[(CAF master)] Tap --> AR[Analysis ring 2 s] --> AT[Analysis thread] --> LV[LiveVisuals] CAF -->|on stop| Fin[Finalizer] --> Lib[(Library file)]
The tap
The tap block receives buffers of about 4096 frames from the input node and does three things: converts the sample rate if the route changed mid-session, writes a mono mix into the analysis ring, and writes the mono mix or an interleaved stereo pair into the writer ring. It performs no file I/O and takes no lock. Its scratch buffers are allocated once and grow only if a larger buffer ever arrives.
AVAudioEngine delivers tap buffers on its own thread rather than on the hardware I/O thread, so the block is not a hard real-time context; it is still kept to copies and vector arithmetic so that nothing in it can stall.
The rings
SPSCRingBuffer (in the core package) is a bounded FIFO for exactly one producer and one consumer, built on Synchronization.Atomic. Neither side locks or allocates. When the consumer falls behind, write stores what fits and adds the remainder to a dropped-samples counter. That counter is surfaced on the recording screen: back-pressure is visible, never silent.
| Ring | Capacity | Consumer |
|---|---|---|
| Writer | 4 s of interleaved audio (rounded up to a power of two) | writer thread |
| Analysis | 2 s of mono audio | analysis thread |
A test pushes two million samples through a ring from one task while another reads them and checks order and completeness; another checks that overflow is reported rather than blocking.
The writer thread
Drains the writer ring into CAFWriter in chunks of up to 16 384 frames, sleeping 20 ms when the ring is empty. Every two seconds it calls synchronize() — the checkpoint that bounds how much audio a power loss could cost. Every five seconds it checks free space and, below 64 MB, reports a failure that stops and saves the recording. A write error is reported once through the same path.
On stop, the phase flips to stopping, the tap is removed, the engine stops, and the writer drains whatever is left before closing the file. framesWritten == framesAccepted afterwards is asserted in the tests.
The analysis thread
For each chunk it updates a waveform processor, a streaming spectrogram (1024-point FFT, hop 512), a spectrum analyser fed from a sliding window of the last 32 768 samples, a loudness meter, and peak / RMS meters with a 9 dB/s peak-hold fall-back and a 1.5 s clip latch. Results go into LiveVisuals, a mutex-protected store with bounded history (8192 waveform buckets, 1024 spectrogram columns).
The interface reads that store on its own schedule through TimelineView. Analysis rate and display rate are independent; the data read happens outside the Canvas drawing closure so each tick hands the canvas new input (an earlier version read inside the closure and SwiftUI skipped the redraws).
Route changes and sample rates
The capture format is fixed when the session starts: the input's sample rate, and two channels only if the preset wants stereo and the input delivers them. On AVAudioEngineConfigurationChange the tap is reinstalled; if the new input runs at another rate an AVAudioConverter brings its audio back to the session's rate so the master stays uniform.
Audio session
AudioSessionManager configures .playAndRecord with .defaultToSpeaker and .allowBluetoothA2DP; Bluetooth hands-free microphones (.allowBluetoothHFP) are opt-in because they are narrow-band. "Raw input" switches the mode to .measurement. Stereo from the built-in microphones is requested only when a data source advertises the stereo polar pattern. Playback uses .playback.
Not verified on hardware
All of the above was exercised in the simulator through a debug-only file input (-ORIXInput) that feeds the same ingest function the tap calls. Real microphones, built-in stereo capture, Bluetooth and wired route changes have not been tested on a device.