feat(audio): consolidated sink/rate negotiation foundation (#3306)

[jensenpat]

What

First, pure-addition step of the consolidated audio sink factory (#3306): a single shared, OS-parameterized format/rate negotiation policy that every audio sink and source will migrate onto, replacing the ~9 divergent per-sink fallback ladders and per-OS #ifdef branches that are the root of a recurring class of platform audio bugs.

Zero behaviour change — this is the maintainer-endorsed "land the helper first, migrate sinks incrementally" approach (#3306, and the #3194 thread's "sensitive audio-stack changes must be separate PRs with soak time").

Why this shape

The historical bugs escaped CI because the per-OS rate ladders were compiled behind Q_OS_*, so a Linux runner could only ever exercise the Linux path. The new policy is a pure function over an injected DeviceCaps snapshot with TargetOs as a parameter, not an #ifdef — so one headless, hardware-free test binary exercises the Windows, macOS and Linux ladders on any runner.

Contents

• src/core/AudioFormatNegotiator.{h,cpp} — dependency-free policy (links only Qt6::Core). One ladder owns:
  • Windows force-48k + r8brain (Garbled RNN audio when RNN is accessed from AetherSDR #2120/Prefer 48kHz RX audio sink on Windows to avoid WASAPI resampler artifacts (#2120) #2123), macOS 48k/A2DP (Cannot change Audio Ouput on MacOs, Macbook Pro M2. #1705), Linux native-24k — divergences preserved as data, not #ifdef.
  • The universal 44.1 kHz rung that RX/Quindar/QSO are missing today (fix(audio): align QsoRecorder format ladder with ClientPuduMonitor (add 44.1 kHz Int16 step) #3385).
  • Int16↔Float32 + preferredFormat() catch-all (fix(cw): Int16 fallback for sidetone sink on Int16-only WASAPI devices (#2668). Principle I. #2669 / Add CommonRadioAudio / Float32 virtual driver support (#1070) #1090 / fix(audio): add preferredFormat() fallback for WASAPI Float32 output devices #3231).
  • macOS mic preferred-rate-first (fix(audio): silent SSB/voice TX on macOS — honour mic native rate + start capture for remote_audio_tx #2930) and Bluetooth-HFP native rate ([mac] Fix macOS Bluetooth headset mic capture rate #2615); Windows probe-at-open (AetherSDR does not recognize input from USB microphone. #2929).
  • The two stereo resampler strategies — PreservePan (RX/QSO) vs MonoCollapse (TCI-TX/RADE) — kept deliberately distinct (Windows L-R pan has not worked since build 9.2.1, not a direct dupe of #1603 #2403/fix(audio): restore L-R pan on Windows 48kHz resampler path (#2403) #2459).
• tests/audio_format_negotiation_test.cpp — table-driven golden matrix, registered under CTest. 25/25 pass, including the 44.1k-only-device regression guard.
• docs/audio-sink-factory.md — the full three-layer design (pure policy → live Qt wrapper → device-ownership router), the device-following "uncoupling" fix (CW / RADE / Aetherial-Audio "Pudu" recorder following the selected output), the regression-guard invariants, and the one-sink-per-PR migration plan.

Test

$ ./build/audio_format_negotiation_test
...
25/25 checks passed

Follow-ups (per the migration plan in the doc)

Live Qt wrapper → migrate RX speaker → migrate PC mic → AudioOutputRouter (closes the uncoupling class) → TCI-TX client-rate → PipeWire DAX shared resampler. Each a separate, soakable PR.

Refs #3306

💻 Generated with Claude Code (Opus 4.8) with architecture by @jensenpat

[aethersdr-agent]

Thanks @jensenpat — this is a really clean foundation PR.

What I checked

• Scope. The five files (CMake test target, design doc, AudioFormatNegotiator.{h,cpp}, golden-matrix test) are all in scope; no drive-by changes touch live sinks. Behaviour-change is genuinely zero because nothing consumes the new module yet.
• Conventions. No QSettings use (irrelevant here — pure policy module), no raw owning pointers, value-semantics throughout. The single #if defined(Q_OS_*) lives in hostTargetOs() exactly as the design doc commits to.
• Bugs / leaks / null-deref. Nothing. Pure value-based code over QList/QString, no allocation, no I/O.
• Error handling at boundaries. No system boundaries in this layer (the live wrapper lands in a follow-up PR). The total-failure case is correctly surfaced via NegotiatedFormat::ok = false with a reason string — the test exercises it ("empty reliable device -> negotiation fails").

Things I particularly liked

• TargetOs as a parameter rather than #ifdef makes the golden matrix actually able to assert all three OS ladders from any runner — the right primitive for catching the historical bug class.
• The preferredFirst rung for macOS input correctly precedes the per-OS ladder so BT-HFP and 16k-native mics aren't forced to 48k, and the test covers both #2615 and #2930 explicitly.
• The nothingProbeable heuristic for Windows probe-at-open is well-contained in negotiate() and has a dedicated test row.
• resamplerKindFor() keeps PreservePan and MonoCollapse deliberately distinct — the unit checks at the bottom of the test guard #2403 from coming back.

Tiny nit (non-blocking, no need to spin)

primaryRateOrder() falls through to return {internalRate} after the switches; that's only reachable if a new TargetOs value is added later. A Q_UNREACHABLE() or default: would document the invariant for whoever touches the enum next, but the current shape is fine.

Looking forward to the live wrapper. The migration plan in the doc is exactly the cadence the audio stack needs.

---

_{🤖 aethersdr-agent · cost: $13.4278 · model: claude-opus-4-7}