Recording Engine

A lock-free, real-time audio recording engine in Rust. The core design separates the time-critical audio callback from all disk I/O using a wait-free SPSC ring buffer, achieving 2,000x+ real-time headroom on stereo and 19x even at 64ch/192kHz.

CoreAudio / ALSA
Audio Device
Hardware input
RT Thread
cpal Callback
Zero alloc · Zero I/O
Lock-Free
SPSC Ring Buffer
5s runway · wait-free
Writer Thread
Writer Thread
Bit convert · Peak meter
Disk I/O
WAV Files
Single or split mode

RT Callback (cpal)

The real-time audio callback runs on the OS audio thread — the most latency-sensitive code path in the entire app. It does exactly three things:

  • Receives an incoming buffer of interleaved f32 samples from the audio device
  • Pushes the raw samples into the rtrb ring buffer via a wait-free write
  • Checks one AtomicBool to signal file rotation timing

It is designed to guarantee zero of each:

Zero file I/O Zero mutex locks Zero heap allocs

SPSC Ring Buffer (rtrb)

The bridge between the RT and writer threads. Uses the rtrb crate — a wait-free single-producer single-consumer ring buffer designed for audio.

  • Sized for 5 full seconds of audio at the device’s sample rate × channel count
  • At 2ch/48kHz that’s ~1.8 MB; at 64ch/192kHz it’s ~234 MB
  • Provides massive I/O runway — even during file rotation, there’s 4,990+ ms of buffer before any risk of drop
  • No locks, no atomics beyond the internal read/write cursors — true wait-free

Writer Thread

A dedicated thread that does all the heavy lifting away from the audio callback:

  • Pops raw f32 samples from the ring buffer
  • Converts to configured bit depth (16/24/32-bit integer PCM)
  • Writes WAV directly (custom RawWavWriter)
  • Tracks per-channel peak levels at zero extra cost (exposed via FFI for the SwiftUI meters)
  • Handles file rotation with crash-safe WAV writes
  • Monitors disk space — auto-stops if below threshold
  • Runs silence gate — pauses recording during silence

WAV Output & Rotation

Two output strategies — single (one multichannel file) or split (one WAV per channel).

  • Continuous mode rotates files at a configurable cadence (default 300s)
  • Rotation overhead: <1ms in single mode, ~10ms for 64-channel split
  • Ring buffer runway during rotation: 4,990+ ms remaining
  • Crash-safe writes ensure valid WAV headers even on unexpected termination
  • Silence gate pauses recording during silence, resumes on signal

Ring Buffer — Live Simulation

Write Head (RT) 0
Read Head (Writer) 0
Fill Level 0%
Buffer Runway 5.0s

Why It’s Highly Optimized

01

RT / Writer Thread Separation

The audio callback never touches the filesystem. All I/O, encoding, and monitoring happens on a separate thread. This eliminates the #1 cause of audio glitches: blocking the RT thread on disk.

02

Wait-Free SPSC Ring Buffer

The rtrb crate provides a lock-free, wait-free SPSC queue. No mutexes, no condition variables, no syscalls on the hot path. Just atomic load/store on read/write cursors.

03

Zero Allocation in RT Path

The callback pushes raw f32 samples directly into a pre-allocated ring buffer. No Vec growth, no Box, no String formatting. The ring buffer is sized once at startup and never resized.

04

5-Second Buffer Runway

The ring buffer holds 5 full seconds of audio. File rotation takes <10ms worst case (64ch split). That’s 4,990+ ms of headroom — enough to absorb any OS scheduling jitter or disk I/O spike.

05

Rust’s Zero-Cost Abstractions

No garbage collector, no runtime overhead. Rust compiles to the same tight machine code as hand-tuned C, with memory safety guaranteed at compile time.

06

Batch I/O on Writer Thread

The writer thread processes samples in bulk from the ring buffer, amortizing syscall overhead. Peak metering piggybacks on the write pass at zero extra cost.