SPB Git

Repository Public License

audio-engine.md 4.5 KB 67 lines markdown

1<!--2ORIX Audio3File: docs/architecture/audio-engine.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->78# Audio Engine910`ORIXAudio/Services/AudioCaptureEngine.swift` owns the `AVAudioEngine` input tap and two worker threads.1112<p align="center"><img src="../assets/diagrams/capture-pipeline.svg" alt="Audio capture pipeline" width="820"></p>1314<details><summary>Mermaid source</summary>1516```mermaid17flowchart LR18  In[AVAudioEngine input node] --> Tap[Tap block: copy only]19  Tap --> WR[Writer ring 4 s] --> WT[Writer thread] --> CAF[(CAF master)]20  Tap --> AR[Analysis ring 2 s] --> AT[Analysis thread] --> LV[LiveVisuals]21  CAF -->|on stop| Fin[Finalizer] --> Lib[(Library file)]22```23</details>2425## The tap2627The 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.2829`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.3031## The rings3233`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.3435| Ring | Capacity | Consumer |36|---|---|---|37| Writer | 4 s of interleaved audio (rounded up to a power of two) | writer thread |38| Analysis | 2 s of mono audio | analysis thread |3940A 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.4142## The writer thread4344Drains 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.4546On 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.4748## The analysis thread4950<p align="center"><img src="../assets/diagrams/realtime-dsp.svg" alt="Real-time analysis thread" width="760"></p>5152For 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).5354The 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).5556## Route changes and sample rates5758The 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.5960## Audio session6162`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`.6364## Not verified on hardware6566All 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.67
Files main
Menu

Theme