feat(audio): live wrapper + RX & TX-mic migration onto the sink factory (#3306)

[jensenpat]

Stacks on #3397 (the pure foundation). The first two commits here are #3397's (foundation + live wrapper); the last two are the RX and TX-mic migrations. Merge #3397 first and this collapses to just those deltas. Kept as separate commits per the maintainer's one-change-at-a-time / soak rule (#3194 thread).

What

Layer 2 + the first two sink migrations of the consolidated audio sink factory (#3306):

1. Live Qt-Multimedia wrapper AudioDeviceNegotiator — the thin, and only, platform-specific bridge. probe(QAudioDevice) → pure DeviceCaps; negotiate()/formatLadder() → openable QAudioFormats. Smoke-tested against the real default devices (audio_device_negotiator_test, 8/8).
2. RX speaker — startRxStream() walks the factory's Float ladder with real start() attempts instead of two forked per-OS #ifdef blocks (net −87 lines). m_resampleTo48k (bool) → m_rxOutputRate (int).
3. PC mic (TX), macOS + Linux — startTxStream() drives mic rate/format from the factory's Int16 Input ladder (stereo-then-mono), removing the per-OS rate lists and the bespoke macTxInputRateCandidates() helper.

Behaviour (preserved)

• RX: Windows/macOS → 48k (WASAPI 24k-resampler artifacts Garbled RNN audio when RNN is accessed from AetherSDR #2120; macOS A2DP off HFP), Linux → 24k native. New strictly-additive wins: a 44.1k-only output now works (Consolidate audio sink sample-rate negotiation into one shared component #3306/fix(audio): align QsoRecorder format ladder with ClientPuduMonitor (add 44.1 kHz Int16 step) #3385); the Quindar local monitor now opens on Windows (old branch returned before startQuindarLocalSink()).
• TX mic: standard macOS mic → 48k; Linux → 24k native; Bluetooth-HFP mic → native low rate first ([mac] Fix macOS Bluetooth headset mic capture rate #2615), fed in via macBluetoothNativeInputRate() + the wrapper's new preferredRateOverride; preferred-rate-first avoids the silent-48k-open trap (fix(audio): silent SSB/voice TX on macOS — honour mic native rate + start capture for remote_audio_tx #2930).

Scope notes / invariants

• Two stereo resampler strategies kept distinct: PreservePan (RX, dual L/R, VITA-49 pan 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) vs MonoCollapse (RADE/TCI-TX).
• macOS telephony/HFP output substitution (Cannot change Audio Ouput on MacOs, Macbook Pro M2. #1705) unchanged (device selection, before the ladder).
• Windows mic left as-is — already matches the factory's force-48k + probe-at-open policy and carries the mono-only USB-mic channel clamp (AetherSDR does not recognize input from USB microphone. #2929) that needs its own soak. That + the device-following AudioOutputRouter, TCI-TX client-rate, and PipeWire DAX are the remaining increments (see docs/audio-sink-factory.md).

Test / build

• audio_format_negotiation_test 25/25, audio_device_negotiator_test 8/8.
• Full macOS app builds & links clean (RelWithDebInfo); deployed to the macOS test box. Soak on Windows/Linux requested before un-drafting.

Refs #3306

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

[aethersdr-agent]

Thanks for the careful staging here, @jensenpat — the OS-as-data design carries through cleanly to the wrapper, and isolating it to one live-Qt-Multimedia layer makes the regression matrix a real artifact rather than aspirational. A few notes from a focused read:

Real findings

1. PR title contains an unsubstituted ${PR_TITLE} / ${PR_DIFF} placeholder ("live wrapper + RX ${PR_TITLE} TX-mic migration…", and similar in the body). Looks like a templating substitution that didn't run before push. Worth editing the title and the "Full macOS app builds ${PR_DIFF} links clean" line in the body before merge so the squashed commit message lands clean. (Not a code issue, but it propagates to the commit log.)

2. m_rxOutputRate is plain int, read from the m_rxTimer lambda and written from startRxStream() (AudioEngine.cpp:676 and :1044). Identical hazard to the prior bool m_resampleTo48k, so not a regression introduced here — but as long as the field is changing shape, it'd be cheap to make it std::atomic<int> to match the surrounding m_rxPan / m_rxBufferCapMs / m_rxBufferSampleRate (which are all std::atomic). Drive-by, not blocking.

3. Windows Quindar-on-RX is a real, scope-creep-y behavior delta worth flagging on the soak list explicitly — the PR description does mention it, but the body bullet calls it a "strictly-additive win." It's additive in intent, but it does mean Windows users get an additional QAudioSink opening alongside RX on a code path that previously short-circuited. Probably fine, but it deserves its own line item in the Windows soak ("verify Quindar local sink opens cleanly, no extra device contention, no Bluetooth-route flip").

Smaller observations

4. startRxStream() skips Int16 ladder rungs (AudioEngine.cpp:1037) because the RX drain is Float PCM. Consistent with the old makeFormat() (Float-only), so no regression — but the policy generates Int16 candidates that you then filter out. A Direction::OutputFloatOnly variant or a policy.formatMask would let buildLadder() skip them at source. Pure cleanup, doesn't have to happen now.

5. The new RX loop captures lastRxError = audioErrorName(sink->error()) before delete sink — good. But on the success path, triedFloatRung is left false on the first rung succeeding, so noteRxFallback("preferred RX format unavailable -> N Hz") only fires after a real fallback. That reads correctly.

6. m_audioSink = nullptr; m_audioDevice = nullptr; at :1030 is redundant given the early-return guard at :932, but harmless.

Correctness spot-checks that came back clean

• Resampler::dstRate() exists (src/core/Resampler.h:40), so the rebuild check on device-rate change is well-formed.
• macOS telephony substitution stays pre-ladder (intentional, matches #1705).
• formatLadder() falls back to optimistic first-rung-only on a null/unprobeable device (AudioDeviceNegotiator.cpp:39), which is the right move for WASAPI probe-at-open.
• The two stereo resampler strategies (PreservePan vs MonoCollapse) stay distinct in ResamplerPolicy, with the policy header explicitly calling out the #2403/#2459 regression they must not re-introduce.

Architecture is sound and the golden matrix is the right shape for catching this class of bug on a Linux runner. Mostly housekeeping comments above — please fix the title placeholder, and consider the atomic on m_rxOutputRate while you're in there.

---

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

[ten9876]

Rebased against current main (post-#3397 merge) and pushed `0b4a85b3` addressing the one substantive item from @aethersdr-agent's review.

What changed in the force-push:

1. Rebased onto current main. Git's cherry-pick logic dropped the squashed-and-merged foundation commit (`5e3fb831` → `204585bc`) cleanly, replayed only the three real commits: live wrapper + RX migration + TX-mic migration. The PR now shows its true delta of +439/-234 across 7 files, not the +1223/-226 it showed when stacked on the unsquashed foundation.

2. `m_rxOutputRate` upgraded to `std::atomic` to match its neighbours (`m_rxPan`, `m_rxBufferCapMs`, `m_rxBufferSampleRate`, `m_muted` are all atomic). Mechanical: 16 read sites take `.load()`, the single write at `startRxStream():1044` takes `.store()`, the inline `rxOutputResamplingActive()` getter in the header takes `.load()`. The previous `bool m_resampleTo48k` had the same latent hazard, so this isn't a regression introduced by the migration — but @aethersdr-agent was right that the field-shape change is the cheapest moment to close it.

On the other two bot findings:

• The `${PR_TITLE}` / `${PR_DIFF}` placeholder concern was already stale by the time I looked — the title and body both read clean now.
• The Windows Quindar behaviour delta is correctly documented in code at `AudioEngine.cpp:1117-1119` (the comment explicitly calls out "the old Windows branch returned before `startQuindarLocalSink()`, so the Quindar local monitor never opened on Windows — unifying the path fixes that"). Belongs on the Windows soak checklist.

Verified locally (Arch Linux x86):

• `audio_format_negotiation_test` — 25/25 (pure golden matrix)
• `audio_device_negotiator_test` — 8/8 (live wrapper against my default devices: `rate=24000 ch=2 resampler=None` — Linux native 24k, exactly what Consolidate audio sink sample-rate negotiation into one shared component #3306 specified)
• Full `AetherSDR` build clean (626/626, only pre-existing unrelated warnings)

Same maintainer-fix-up pattern as #3279/#3286/#3289/#3381/#3391/#3397. Soak on Linux from my side is clean; Windows/macOS soak still wanted before final merge per your description, but CI is green and the code is in a state where soak is the bottleneck, not review.

@jensenpat — happy to revert the rebase or the atomic upgrade if you'd rather take a different cut at either.

Principle XI.