NoNoise-Mac AGENTS.md

NoNoise Mac — Agent Operating Guide

This file is the entry point for any AI agent (or human) working in this repo. Read it first, then the linked knowledge base before touching audio code.

What this is

NoNoise Mac is a macOS (Apple Silicon) menu-bar app that removes background noise and room reverb from your microphone in real time, 100% on-device, using DeepFilterNet3 on CoreML + Metal / Accelerate. It routes the cleaned voice through a virtual audio cable so any app (Zoom, Meet, Discord, OBS, …) receives studio-clean audio.

ICP / Who We Build For

• macOS Apple-Silicon users on calls, podcasts, livestreams, and screen recordings who need clean voice without cloud processing or a subscription.
• Privacy-conscious users — no audio ever leaves the machine.
• Creators who want light studio polish (EQ + leveling) without opening a DAW.
• Not for: Windows/Linux, Intel Macs, or multi-channel music mastering.

Architecture map

• Sources/Core — engine, no UI:
  • AudioModel — CoreAudio/AVFoundation capture + playback, ring buffer, render callback, preset/knob state + persistence.
  • AudioProcessing/DeepFilterNetDSP — STFT → DeepFilterNet feature pipeline → CoreML call → ISTFT → wet/dry blend.
  • AudioProcessing/DeepFilterNet3_Streaming — generated CoreML model wrapper.
  • AudioProcessing/VoiceChain + Biquad + Dynamics — post-DSP "voice polish" (high-pass → shelves → compressor → limiter) plus the optional Broadcast Voice clarity stages (presence peaking bell → subtractive DeEsser) and optional Mouth Noise finisher stages (subtractive DePlosive → broadband-gate DeClick). Driven by ClarityLevel + MouthNoiseLevel, each is gated independently of the noise preset.
  • AudioProcessing/IncomingCleanupEngine — a SECOND, independent capture→clean→play pipeline ("clean the other side"), macOS 14.4+. Captures all system audio except NoNoise via a Core Audio process tap (no BlackHole/loopback), runs its OWN DeepFilterNetDSP instance (DFN only — no VoiceChain), and re-renders the cleaned audio to the current default output (auto-following device changes; tapped originals muted). NOT an AudioModel (no mic coupling, no auto-route to the NoNoise Mic sink). Held by AudioModel as an OPTIONAL (stored AnyObject?, gated type) created ONLY while enabled. The tap IOProc → AVAudioSourceNode are bridged by the lock-free TapAudioRing / CTapRing SPSC ring. See "Incoming / guest cleanup" below.
  • AudioProcessing/TapAudioRing + Sources/CTapRing (tap_ring.{c,h}) — a lock-free C11-atomics single-producer/single-consumer float FIFO bridging the two realtime threads of the tap-based incoming path. Mirrors the driver's tested nn_ring acquire/release discipline.
  • AudioProcessing/IncomingTapLogic — pure, headless-tested decisions for the incoming path (own-process-object validity, re-pin-vs-rebuild) + the IncomingCleanupStatus enum the UI binds to.
  • AudioProcessing/RingBuffer, SpecHistoryRingBuffer, AudioUtils — buffers + helpers.
  • VoicePreset — preset → DSP params + voice-chain settings (single source of truth).
  • CLIArguments + AudioDenoiseOptions — shared CLI parser (live device, --action, --denoise).
  • AudioFileDenoiser — offline file decode → mono 48 kHz → DeepFilterNetDSP → optional VoiceChain → write WAV/CAF/etc. Waits on DeepFilterNetDSP.waitUntilReady() before processing; writes to a temp sibling then moves on success.
• Sources/App — SwiftUI menu-bar app: NoNoiseMacApp, ContentView (popover), SettingsView, and LaunchAtLoginManager (macOS Service Management adapter).
• Sources/CLI — NoNoiseMacCLI: live device pipeline, one-shot --action URL dispatch, and --denoise offline file mode (audio containers only — no MP4/video remux in v1).
• Resources — DeepFilterNet3_Streaming.mlmodelc, AppIcon.icns, NoNoiseMacLogo.png, Info.plist, NoNoiseMac.entitlements.
• Tests/NoNoiseMacTests — pure DSP / preset / voice-chain unit tests (run headless).