fix(cw): prefer WASAPI host API for CW sidetone on Windows (#3193)

[M7HNF-Ian]

Standalone split of Fix #2 from #3194, as requested by @jensenpat.

Problem

CwSidetonePortAudioSink picks audio output devices via PortAudio, but on Windows:

1. defaultPortAudioOutputDevice() falls straight through to Pa_GetDefaultOutputDevice(), which returns an MME device (the first host API PortAudio enumerates). MME carries 50–150 ms OS-level buffering, producing audible CW timing jitter on fast keying.

2. findPortAudioOutputDevice() matches devices by name substring. On Windows, the same physical device is enumerated three times under MME, DirectSound, and WASAPI. The old code treated this as an ambiguous match and returned paNoDevice — causing the sidetone to fall back to CwSidetoneQAudioSink and lose low-latency timing. When it did resolve, it picked whichever host API appeared first (MME).

Fix

defaultPortAudioOutputDevice() — add a WASAPI preference pass before the Pa_GetDefaultOutputDevice() fallback, mirroring the existing Linux JACK preference exactly. WASAPI shared mode runs at ~10 ms, vs 50–150 ms for MME.

findPortAudioOutputDevice() — collect all partial-match candidates, then resolve to the WASAPI entry when exactly one exists. Logs a clear qCInfo message showing which host API won. Falls back to the existing "matched multiple" warning only if multiple WASAPI entries are somehow present (pathological case).

Scope

CwSidetonePortAudioSink.cpp only. No changes to AudioEngine.cpp, no RX path changes, no buffer size changes.

Related

• Partially addresses External USB Audio Interface and Windows 11, latency is a huge issue #3193 (CW sidetone latency component)
• May also help Ver 0.9.8 TX to RX delay when stop sending CW #2528 (TX→RX delay when stopping CW) and the latency component of CWX sidetone latency and distorted/non-pure CW tone on Windows with FLEX-8400 #2694
• Sibling of the held HOLD FOR TESTING - fix(audio): reduce Windows USB audio latency for RX and CW sidetone (#3193) #3194 Fix PHONE applet: DEXP commands rejected on firmware v1.4.0.0 #1 (RX WASAPI ring cap — separate review track)

[aethersdr-agent]

Thanks @M7HNF-Ian — this is a well-scoped, well-explained fix. The two changes mirror each other nicely and the comments in the code make the why obvious (Windows multi-host-API enumeration, MME latency rationale). A few notes:

Logic LGTM

• findPortAudioOutputDevice() — the refactor from "first match + ambiguity flag" to "collect all + pick WASAPI" is straightforward, and the behaviour for non-Windows or exactly-one-match cases is preserved. The paInDevelopment sentinel is a neat trick and the inline comment justifies it.
• defaultPortAudioOutputDevice() — the WASAPI preference pass on Windows is a clean mirror of the existing Linux JACK block. Nice symmetry.

One small observation (non-blocking)

start() at CwSidetonePortAudioSink.cpp:161–167 re-inspects the device's host API after defaultPortAudioOutputDevice() returns and sets m_fallbackOccurred = true / m_fallbackReason = "backend selected JACK default output" so the summary logger surfaces JACK selection as a backend substitution. The new WASAPI default-selection path doesn't get the same surfacing.

I think that's actually defensible — on Windows, WASAPI is the expected low-latency target, not an override the operator needs flagged the way JACK is on Linux — and you do emit a qCInfo at the selection site. Mentioning it only so you can confirm it's intentional. If you wanted parity, you'd add a qstrncmp(api->name, "Windows WASAPI", 14) == 0 arm to the same if (device.isNull()) block, but I don't think it's necessary.

Minor / cosmetic

• The Candidate::apiType field is populated on every platform but only read inside #ifdef Q_OS_WIN. Trivially wasteful (one PaHostApiTypeId per match candidate, on a list that's almost always tiny). Not worth changing.
• partials.size() - 1 in the qCInfo log expression is fine — we only enter that block when partials.size() >= 2, so the value can't be negative.

Scope / conventions

• Single file changed, exactly as described.
• No QSettings / AppSettings touched; no RAII surface; no new resources to leak.
• No null-deref risks introduced — every Pa_GetHostApiInfo / Pa_GetDeviceInfo return is checked before deref.
• The #ifdef Q_OS_WIN guards around the WASAPI-specific code keep this from affecting Linux/macOS builds.

Looks ready to me. 73 from a fellow CW operator-in-spirit — fast-keying jitter is a real annoyance and this should make a noticeable difference. Thanks for splitting it out of #3194 as requested.

---

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