feat(audio): compile the PortAudio CW sidetone sink on Windows (#5200) (#5201)

Fixes #5200.

## What

Stock Windows/MSVC builds have never compiled
`CwSidetonePortAudioSink.cpp`: PortAudio detection ran exclusively
through pkg-config, which does not resolve on Windows, so
`HAVE_PORTAUDIO` was never defined and every Windows build silently took
the push-model `CwSidetoneQAudioSink` sidetone (2 ms timer). The WASAPI
host-API preference added in #3193 *specifically for Windows CW jitter*
has consequently never been active in any shipped build. Windows is the
build-configuration route to the same push-path landing spot as #4978's
Linux runtime route (per the split documented in #4890).

**Build plumbing** mirrors the established FFTW3/hidapi
Windows-dependency pattern:

- **`scripts/setup/setup-portaudio.ps1`** — downloads PortAudio v19.7.0
(pinned, SHA256-verified, same `_verify_sha256.ps1` helper as the other
setup scripts), builds the static lib with MSVC (WASAPI requested
explicitly; WDM-KS / DirectSound / MME from upstream's Windows
defaults), installs into `third_party/portaudio/`.
- **`CMakeLists.txt`** — a `WIN32` detection branch that soft-detects
`third_party/portaudio/` (absent → build proceeds, with a
`message(WARNING)` naming the script and the consequence), checking both
the header and the static lib it links, and naming that lib's system
dependencies from PortAudio's own CMake export.
- **CI wiring** — the Windows CI job runs the script (after
`msvc-dev-cmd`, same as hidapi), plus an assert step that fails the job
if CMake did not actually find PortAudio, so this job cannot go green
having compiled nothing new.

**Sink fixes.** Merely compiling the sink was NOT enough. Live A/B
testing by ear (FLEX-6300 into a dummy load, keyboard iambic paddles)
found it audibly broken on Windows, three defects deep — all in code
that had only ever run against CoreAudio:

1. **Windows friendly names are not unique.** The test box has **three
active endpoints all named "TOSHIBA-TV (NVIDIA High Definition Audio)"**
(one per HDMI connector; five including unplugged ones). Name matching
selected a live-but-unwired port that accepted the stream and played it
into nothing — instrumentation showed 50k callbacks rendering a clean
0.566-peak tone into an inaudible endpoint. The fix matches the Qt
device to the PortAudio WASAPI device **by endpoint ID**
(`PaWasapi_GetIMMDevice` → `IMMDevice::GetId` compared against
`QAudioDevice::id()`), demoting name matching to fallback. This is the
Windows analog of the name-match fragility skerker is fixing on Linux in
#5123/#5135 — same disease, platform-appropriate cure.
2. **The exact-match branch defeated #3193.**
`findPortAudioOutputDevice()` returned the *first* exact name match in
enumeration order — DirectSound on Windows — so the WASAPI preference
(written only into the partial-match branch) never ran. Exact matches
are now collected and the same WASAPI preference applied; a multi-exact
match with no WASAPI candidate names the losing candidates rather than
silently taking the first.
3. **`suggestedLatency = 0.0` is a CoreAudio-ism.** DirectSound built an
unservable buffer ring: the stream ran, the callback rendered a clean
tone, and the speaker output was garbled crackle. Windows now requests
the device's `defaultLowOutputLatency` (22 ms reported on WASAPI shared
for this endpoint); other platforms unchanged.

**Observability**, because the diagnosis above needed instrumentation
the start line lacked — `hostApi=` on the started line, a stopping line
with `callbacks=` / `peak=` / `underflows=` / `overflows=`, and the
endpoint-ID match. All on `lcAudioSummary` so they reach a **default**
support bundle; `lcAudio` sits at `QtWarningMsg`, so a `qCInfo` on it
would not. A started stream that renders silence or garbage is now
distinguishable from a working one without asking the operator to re-run
with debug logging. Underflow counting exempts the first couple of
stream-prime callbacks, which report `paOutputUnderflow` on essentially
every host and are not deadline misses.

**`src/core/CwSidetoneEdgeProbe.h`** (new) is the bench instrument
behind the timing tables in the thread: `AETHER_CW_EDGE_PROBE=1` makes
**both** sidetone sinks capture envelope transitions at the sink
boundary with a running sample counter, dumped at `stop()` as
`EDGEPROBE` lines. Positions are stream-sample-exact, so element
durations and onset spacing are measured on the stream's own clock — no
loopback recording, no wall-clock jitter in the instrument. Disabled it
costs one bool test per rendered buffer and allocates nothing.
`CwSidetoneQAudioSink` is wired up too, which is what makes the
push-vs-callback A/B a like-for-like comparison; that is the only change
here to a file that runs on every platform.

`tests/cw_sidetone_edge_probe_test.cpp` covers the probe: the
empty-stream reset (reverting it fails the test with `got 480001, want
0`), the zero-crossing rule the falling-edge detection rests on,
short-element detection, and the absolute-threshold limitation — pinned
so it stays a deliberate property.

## Shipped Windows builds switch to the callback sink

This is the maintainer decision #5200 asked to be made explicitly, and
it has been made: `windows-installer.yml` runs the setup script, so
**shipped Windows installers now build with `HAVE_PORTAUDIO` and ship
the PortAudio callback sidetone** — the same transport macOS and Linux
already ship, and what #3193 intended but never delivered.

Note there is no per-platform default being changed: `CwSidetoneBackend`
has always defaulted to `"PortAudio"` on every platform. On Windows that
default was simply unsatisfiable, because the sink was never compiled.
This makes it reachable.

**The trade being accepted**, from the element timing further down this
thread:

- **Latency (the win):** ~22 ms buffered depth to the DAC against the
push sink's ~50 ms — roughly **28 ms less key-to-ear delay**. That is
what a CW operator feels at the key and what #3193 was chasing.
- **Rhythm (the cost):** a small jitter tail at 30 WPM that two
independent Windows boxes both show and neither explains — displacements
quantized around 10.3–10.8 ms, with `underflows= 0` across 169,523
callbacks, so it is *not* a device deadline miss. At 20 WPM the tail is
absent (SD 0.262 ms, 0 of 176 elements beyond 3SD). The in-stream rhythm
of the push path remains tighter (SD 0.26 ms vs 0.96 ms on the
originating box).

Latency wins; the tail is tracked rather than dismissed, and the
instrumentation in this PR is what will explain it.

The installer job also gains an assert mirroring the GPU-spectrum guard
— the `WIN32` detection is soft-optional, and this is the workflow that
produces what users install, so a silent skip would ship the push
sidetone while the release notes claimed otherwise. It fails the build
instead.

`CwSidetoneBackend=QAudioSink` remains the escape hatch, and the
PortAudio-start-failure → QAudioSink fallback (with the
consequence-naming log from the #4978 fixes) is unchanged.

## Verified on real hardware (Windows 11, MSVC, Qt 6.10.3, FLEX-6300 on
a dummy load)

Full build from clean configure; app run, connected, keyboard iambic
paddles keyed by both an operator and synthesized key events; every
claim below is **by ear**, A/B on the same physical endpoint:

- **QAudioSink control:** clean tones (establishes the endpoint + gate
path).
- **Sink as first compiled** (DirectSound selected by defect 2, garbled
by defect 3): audibly broken — first reported as "sounds crap", then
near-silent on a different endpoint pick (defect 1).
- **Sink with all three fixes:** `matched WASAPI endpoint by ID
"{0.0.0.00000000}.{35f3f303-…}"` → `hostApi= Windows WASAPI …
outputLatency= 22 ms` → **clean tones**, operator-confirmed, radio
keying verified via `cw key` wire traces and clean unkey after every
run.

Element-timing measurement per @williamscody's #4890 methodology is in
the thread below, as is @skerker's independent replication on macOS,
Windows and Linux — the macOS arm is the regression check that mattered,
since that platform already ships this sink.

A process note worth stating plainly: the PR as first opened claimed the
sink "works" from a clean start line and low reported latency. That
claim was wrong — a started stream was rendering garbage. The by-ear A/B
is what caught it, and the `callbacks=` / `peak=` instrumentation is
there so the next person can catch it from a log instead.

## Not exercised

- MME-truncation partial-match path (all live selections here resolved
exact or by ID).
- PortAudio start-failure → QAudioSink fallback on Windows.
- The Windows-only `#ifdef Q_OS_WIN` paths have no automated coverage —
`findPortAudioOutputDevice()` needs live device enumeration, and a
synthetic peer would be worse than nothing. They rest on the hardware
A/B above and @skerker's Windows bench.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Jeremy [KK7GWY] <kk7gwy@aethersdr.com>

Author: 3 people

.github/workflows/ci.yml

@@ -522,6 +522,15 @@ jobs:
         shell: pwsh
         run: .\scripts\setup\setup-hidapi.ps1
 
+      - name: Setup PortAudio (CW sidetone callback sink)
+        # Without this, HAVE_PORTAUDIO is undefined and
+        # CwSidetonePortAudioSink never compiles on Windows — the CW
+        # sidetone silently takes the push-model QAudioSink path and CI
+        # would miss real compile errors in the PortAudio sink (#5200).
+        # Runs after msvc-dev-cmd for cl.exe + link.exe on PATH.
+        shell: pwsh
+        run: .\scripts\setup\setup-portaudio.ps1
+
       # zlib is bundled under third_party/zlib (1.3.1) — no vcpkg install
       # needed; CMake builds zlibstatic from source.  (#2651)
 
@@ -612,6 +621,31 @@ jobs:
           }
           Select-String -Path configure.log -Pattern 'GPU spectrum rendering enabled'
 
+      # The WIN32 PortAudio detection keys on EXISTS third_party/portaudio and
+      # is soft-optional — if the setup step's output ever goes missing (tag
+      # moved, cache restored a partial tree, output rename in a bump), CMake
+      # would skip CwSidetonePortAudioSink.cpp without a word and this job
+      # would go green having compiled nothing new. Assert the found line so
+      # the coverage this job exists to buy cannot evaporate silently (#5200).
+      - name: Assert PortAudio sidetone sink actually enabled
+        shell: pwsh
+        run: |
+          if (-not (Select-String -Path configure.log -Pattern 'PortAudio \(third_party\) found' -Quiet)) {
+            Write-Host "ERROR: setup-portaudio.ps1 ran but CMake did not find third_party/portaudio."
+            # NOT Select-String on configure.log: the not-found leg is a
+            # message(WARNING), which CMake writes to stderr, and the configure
+            # step tees stdout only (see the note there). Show the tree the
+            # detection actually keys on instead.
+            Write-Host "--- third_party/portaudio ---"
+            if (Test-Path third_party\portaudio) {
+              Get-ChildItem -Recurse third_party\portaudio | Select-Object -ExpandProperty FullName
+            } else {
+              Write-Host "(third_party/portaudio does not exist)"
+            }
+            exit 1
+          }
+          Select-String -Path configure.log -Pattern 'PortAudio \(third_party\) found'
+
       - name: Build Opus (RADE dependency)
         # ExternalProject dependency ordering via BUILD_BYPRODUCTS is correct,
         # but a separate step gives clearer CI failure attribution and avoids

.github/workflows/windows-installer.yml

@@ -131,6 +131,24 @@ jobs:
         if: steps.cache-hidapi.outputs.cache-hit != 'true'
         run: .\scripts\setup\setup-hidapi.ps1
 
+      # PortAudio is what makes the CW sidetone run on the callback ("pull")
+      # path with WASAPI, the same transport macOS and Linux already ship.
+      # Without it HAVE_PORTAUDIO is undefined, CwSidetonePortAudioSink.cpp is
+      # not compiled, and the shipped installer silently falls through to the
+      # push-model QAudioSink — which is what every Windows build did before
+      # #5200, including the #3193 WASAPI preference that was never active.
+      # Static lib, so nothing to bundle in the Deploy step. (#5200)
+      - name: Cache PortAudio
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
+        id: cache-portaudio
+        with:
+          path: third_party/portaudio
+          key: portaudio-${{ runner.os }}-${{ hashFiles('scripts/setup/setup-portaudio.ps1') }}
+
+      - name: Setup PortAudio (CW sidetone callback sink)
+        if: steps.cache-portaudio.outputs.cache-hit != 'true'
+        run: .\scripts\setup\setup-portaudio.ps1
+
       - name: Cache DeepFilterNet3
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
         id: cache-deepfilter
@@ -239,6 +257,28 @@ jobs:
           }
           Select-String -Path configure.log -Pattern 'GPU spectrum rendering enabled'
 
+      # Same shape as the GPU-spectrum guard above, and for the same reason:
+      # the WIN32 PortAudio detection is soft-optional, so a missing or
+      # half-restored third_party/portaudio makes CMake skip the callback sink
+      # without failing. This workflow is the one place that matters most --
+      # it produces what users install, so a silent skip would ship the
+      # push-model QAudioSink while the release notes claim the callback path.
+      # Fail here instead. (#5200)
+      - name: Assert PortAudio sidetone sink actually enabled
+        run: |
+          if (-not (Select-String -Path configure.log -Pattern 'PortAudio \(third_party\) found' -Quiet)) {
+            Write-Host "ERROR: setup-portaudio.ps1 ran but CMake did not find third_party/portaudio."
+            Write-Host "The installer would ship the push-model QAudioSink sidetone. Refusing."
+            Write-Host "--- third_party/portaudio ---"
+            if (Test-Path third_party\portaudio) {
+              Get-ChildItem -Recurse third_party\portaudio | Select-Object -ExpandProperty FullName
+            } else {
+              Write-Host "(third_party/portaudio does not exist)"
+            }
+            exit 1
+          }
+          Select-String -Path configure.log -Pattern 'PortAudio \(third_party\) found'
+
       - name: Build Opus (RADE dependency)
         # ExternalProject dependency ordering via BUILD_BYPRODUCTS is correct,
         # but a separate step gives clearer CI failure attribution and avoids

.gitignore

@@ -41,6 +41,11 @@ third_party/onnxruntime-*.zip
 third_party/sherpa-onnx/
 third_party/sherpa-onnx-*.tar.bz2
 
+# Built by scripts/setup/setup-portaudio.ps1 on Windows (#5200); the tarball
+# only survives a run that failed partway.
+third_party/portaudio/
+third_party/portaudio-*.tar.gz
+
 # Claude Code / Browser-pane dev-server config. Per-developer and per-worktree:
 # it names a local build path and the entry is generated by whoever opens the
 # preview, so a committed copy is wrong for everybody else. `.claude/commands/`

CMakeLists.txt

@@ -296,10 +296,43 @@ else()
     message(STATUS "Qt6Keychain not found — credential persistence disabled")
 endif()
 
-# PortAudio (optional fallback for audio)
-find_package(PkgConfig QUIET)
-if(PkgConfig_FOUND)
-    pkg_check_modules(PORTAUDIO portaudio-2.0)
+# PortAudio (optional fallback for audio; on Windows it is the CW sidetone's
+# callback-model path — without it the sidetone runs on the push-model
+# QAudioSink and the WASAPI-preference logic from #3193 never compiles, #5200)
+# Windows: run scripts/setup/setup-portaudio.ps1 first to build the static lib
+# Linux:   apt install portaudio19-dev
+# macOS:   brew install portaudio
+if(WIN32)
+    set(PORTAUDIO_ROOT "${CMAKE_SOURCE_DIR}/third_party/portaudio")
+    # Check BOTH artefacts the link below depends on. Testing only the header
+    # let a half-populated third_party/portaudio (interrupted setup run, cache
+    # restored without lib/) configure as "found", satisfy the CI assert, and
+    # then die at link. setup-portaudio.ps1's own early-exit guard tests the
+    # .lib, so this keeps the two in agreement. (#5200)
+    if(EXISTS "${PORTAUDIO_ROOT}/include/portaudio.h"
+       AND EXISTS "${PORTAUDIO_ROOT}/lib/portaudio_static_x64.lib")
+        set(PORTAUDIO_FOUND TRUE)
+        set(PORTAUDIO_INCLUDE_DIRS "${PORTAUDIO_ROOT}/include")
+        # Static lib, so its host-API system dependencies must be named here
+        # (matches INTERFACE_LINK_LIBRARIES of PortAudio's own CMake export).
+        set(PORTAUDIO_LIBRARIES
+            "${PORTAUDIO_ROOT}/lib/portaudio_static_x64.lib"
+            winmm dsound ole32 uuid setupapi)
+        # CI greps configure output for this exact line — a soft-optional
+        # dependency that vanishes must fail the gate, not silently skip
+        # compiling the sink (same rule as the GPU-spectrum assert).
+        message(STATUS "PortAudio (third_party) found — CW sidetone callback sink enabled")
+    else()
+        # Soft-optional (build proceeds), but VISIBLY: without this the
+        # sidetone silently lands on the push-model QAudioSink path.
+        message(WARNING "PortAudio not found — run scripts/setup/setup-portaudio.ps1; "
+                        "the CW sidetone will use the push-model QAudioSink")
+    endif()
+else()
+    find_package(PkgConfig QUIET)
+    if(PkgConfig_FOUND)
+        pkg_check_modules(PORTAUDIO portaudio-2.0)
+    endif()
 endif()
 
 # FFTW3 (required by vendored WDSP; also used by NR2 spectral noise reduction)

scripts/setup/setup-portaudio.ps1

@@ -0,0 +1,104 @@
+<#
+.SYNOPSIS
+    Download and build PortAudio for Windows x64.
+
+.DESCRIPTION
+    Downloads PortAudio v19.7.0 source from GitHub, builds the static library
+    with CMake + MSVC, and places headers/lib in third_party/portaudio/ ready
+    for CMake. WASAPI is requested EXPLICITLY (-DPA_USE_WASAPI=ON) because the
+    sidetone sink's whole reason to exist is #3193's WASAPI preference — a
+    future PortAudio bump must not be able to drop it silently. WDM-KS /
+    DirectSound / MME come from upstream's Windows defaults.
+
+    Required for the callback-model CW sidetone sink (CwSidetonePortAudioSink)
+    and its WASAPI host-API preference (#3193). Without it the Windows build
+    silently falls back to the push-model QAudioSink sidetone path.
+
+.EXAMPLE
+    .\setup-portaudio.ps1
+#>
+
+$ErrorActionPreference = "Stop"
+. "$PSScriptRoot\_verify_sha256.ps1"
+
+$PaVersion = "19.7.0"
+$PaUrl     = "https://github.com/PortAudio/portaudio/archive/refs/tags/v${PaVersion}.tar.gz"
+# SHA256 of the GitHub source archive. Bump alongside the version.
+$PaSha256  = "5af29ba58bbdbb7bbcefaaecc77ec8fc413f0db6f4c4e286c40c3e1b83174fa0"
+$OutDir    = "third_party\portaudio"
+$TarFile   = "third_party\portaudio-${PaVersion}.tar.gz"
+
+# ── Check if already set up ──────────────────────────────────────────────
+if (Test-Path "$OutDir\lib\portaudio_static_x64.lib") {
+    Write-Host "PortAudio already set up in $OutDir" -ForegroundColor Green
+    exit 0
+}
+
+# ── Create directories ───────────────────────────────────────────────────
+New-Item -ItemType Directory -Force -Path "third_party" | Out-Null
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+New-Item -ItemType Directory -Force -Path "$OutDir\lib" | Out-Null
+New-Item -ItemType Directory -Force -Path "$OutDir\include" | Out-Null
+
+# ── Download source ─────────────────────────────────────────────────────
+if (-not (Test-Path $TarFile)) {
+    Write-Host "Downloading PortAudio ${PaVersion} source..." -ForegroundColor Cyan
+    Invoke-WebRequest -Uri $PaUrl -OutFile $TarFile
+}
+# Verify OUTSIDE the download guard. This script deletes the tarball on
+# success, so a tarball that survives to a later run is by definition from a
+# run that failed partway — possibly mid-download. Verifying only what we just
+# fetched would consume that one unchecked.
+Confirm-Sha256 -Path $TarFile -Expected $PaSha256
+
+# ── Extract ──────────────────────────────────────────────────────────────
+Write-Host "Extracting..." -ForegroundColor Cyan
+$tempDir = "third_party\portaudio-temp"
+if (Test-Path $tempDir) { Remove-Item -Recurse -Force $tempDir }
+New-Item -ItemType Directory -Force -Path $tempDir | Out-Null
+tar -xzf $TarFile -C $tempDir 2>$null
+
+$srcDir = Get-ChildItem "$tempDir\portaudio-*" -Directory | Select-Object -First 1
+if (-not $srcDir) {
+    Write-Error "Failed to locate extracted PortAudio source"
+    exit 1
+}
+
+# ── Build with CMake + MSVC ──────────────────────────────────────────────
+Write-Host "Building PortAudio from source with MSVC..." -ForegroundColor Cyan
+
+$buildDir = "$($srcDir.FullName)\build"
+# CMAKE_POLICY_VERSION_MINIMUM: v19.7.0's CMakeLists declares a
+# cmake_minimum_required below 3.5, which CMake 4.x refuses outright — same
+# situation and same fix as setup-hidapi.ps1. The flag MUST be quoted:
+# PowerShell's native-argument tokenizer splits an unquoted -Dkey=3.5 at
+# the dot, so CMake receives "3" and rejects it.
+cmake -B $buildDir -S $srcDir.FullName -G "Ninja" `
+    -DCMAKE_BUILD_TYPE=Release `
+    -DPA_BUILD_SHARED=OFF `
+    -DPA_BUILD_STATIC=ON `
+    -DPA_USE_WASAPI=ON `
+    -DPA_BUILD_EXAMPLES=OFF `
+    -DPA_BUILD_TESTS=OFF `
+    "-DCMAKE_POLICY_VERSION_MINIMUM=3.5"
+
+cmake --build $buildDir --config Release -j $env:NUMBER_OF_PROCESSORS
+
+# ── Find and copy built artifacts ────────────────────────────────────────
+$libFile = Get-ChildItem "$buildDir" -Recurse -Filter "portaudio_static_x64.lib" | Select-Object -First 1
+if (-not $libFile) {
+    Write-Error "Failed to build portaudio_static_x64.lib"
+    exit 1
+}
+
+Copy-Item $libFile.FullName "$OutDir\lib\portaudio_static_x64.lib"
+# Public header plus the pa_win_* host-API headers (WASAPI stream options etc.)
+Copy-Item "$($srcDir.FullName)\include\*.h" "$OutDir\include\"
+
+# ── Cleanup ──────────────────────────────────────────────────────────────
+Remove-Item -Recurse -Force $tempDir
+Remove-Item -Force $TarFile
+
+Write-Host "PortAudio ready in $OutDir" -ForegroundColor Green
+Write-Host "  Header: $OutDir\include\portaudio.h"
+Write-Host "  Lib:    $OutDir\lib\portaudio_static_x64.lib"

src/core/AudioEngine.cpp

@@ -4113,8 +4113,10 @@ void AudioEngine::setMuted(bool muted)
 }
 
 // Pick the sidetone backend based on build flag + AppSettings override.
-// PortAudio when available (lower latency on Linux/macOS); QAudioSink
-// fallback otherwise or when explicitly requested by the user.
+// PortAudio when available (the callback path: lower latency on every
+// platform that builds it — Windows joined Linux/macOS in #5200, where the
+// shipped installer started providing it); QAudioSink fallback otherwise or
+// when explicitly requested by the user.
 static std::unique_ptr<CwSidetoneSinkBackend> makeSidetoneBackend(QObject* qparent)
 {
     const QString pref =