Summary

Multiple reports describe CW sidetone being absent, distorted, delayed, or otherwise unreliable. During the investigation for PR #2899, we found one concrete local-audio routing failure mode: the dedicated CW sidetone sink can be out of sync with the PC audio output selected in AetherSDR.

Tracking PR:

• [bug] Route CW sidetone to selected audio output #2899

Findings from the PR #2899 investigation

• Local CW sidetone is generated by CwSidetoneGenerator and played through a dedicated sidetone backend, separate from the normal RX QAudioSink.
• The app settings output selector and the new-device dialog both route through AudioEngine::setOutputDevice().
• setOutputDevice() persists the selected output and restarts the RX stream when RX audio is running.
• Restarting RX audio also stops and restarts the local CW sidetone sink via stopRxStream() / startRxStream().
• The Qt sidetone backend (CwSidetoneQAudioSink) accepted and used the selected QAudioDevice.
• The PortAudio sidetone backend accepted a QAudioDevice in its interface but ignored it internally, opening PortAudio's default output instead.
• Therefore, when the operator selected a non-default PC output in AetherSDR, RX audio could move to that selected output while CW sidetone stayed on the OS/PortAudio default output.
• That mismatch can present to the user as “lost sidetone,” especially with headphones, virtual cables, USB audio devices, or after the OS changes the default route.
• A related default-following gap also existed: when AetherSDR was configured to follow the system default output, the audio-device monitor restarted local audio paths on device add/remove, but not on a pure OS default-output change where the device list stayed the same.

What PR #2899 changes

• Maps the selected Qt output device name to a PortAudio output device before opening the low-latency sidetone stream.
• Treats missing or ambiguous PortAudio mappings as a PortAudio backend failure, causing fallback to the Qt QAudioSink sidetone backend on the selected device.
• Passes the current Qt output device object into sidetone startup so default-following and explicit-output selection go through the same routing logic.
• Tracks Qt default input/output IDs in MainWindow.
• Restarts default-following local audio paths when Qt reports that the OS default input/output changed, even if no device was removed.
• Updates docs/audio-pipeline.md with the default-device restart behavior and sidetone backend routing/fallback behavior.

Expected user-facing behavior after PR #2899

• Changing the PC output device from AetherSDR settings restarts CW sidetone on the selected output device.
• Accepting a new output device from the new-device dialog restarts CW sidetone on the selected output device.
• If AetherSDR is following the system default output, changing the OS default output restarts the local output path so RX audio and CW sidetone bind to the new default.
• If PortAudio cannot map the selected Qt output reliably, AetherSDR should use the Qt sidetone sink instead of silently playing sidetone through the wrong PortAudio/default endpoint.

Validation performed for PR #2899

• cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=RelWithDebInfo
• cmake --build build --parallel 22
• cmake --build build --target AetherSDR --parallel 22
• ./build/cw_sidetone_test
• git diff --check

Follow-up verification needed

• Confirm on Windows with explicit non-default output device selected.
• Confirm on macOS with explicit non-default output device selected.
• Confirm with USB audio/headset devices where the OS default differs from AetherSDR's selected output.
• Confirm with virtual audio devices/cables.
• Confirm the OS-default-following path by changing the OS default output while AetherSDR is connected and PC audio/CW sidetone are active.
• Capture logs showing either:
  • CwSidetonePortAudioSink: matched selected Qt output ...
  • or fallback to QAudioSink when the selected output cannot be mapped.

Known related CW issues

These are not all the same root cause. This list is meant to keep the CW/sidetone context connected while #2899 is verified.

Open sidetone / keying / timing reports

• CWX: CW PTT not sent to external amplifier #2878 — CWX CW PTT not working
• CWX sidetone latency and distorted/non-pure CW tone on Windows with FLEX-8400 #2694 — CWX sidetone latency and distorted/non-pure CW tone on Windows with FLEX-8400
• CWX keying with PC Audio: No CW sidetone monitor heard #2629 — CWX keying with PC Audio: No CW sidetone monitor heard
• CW Break-in timing issue with serial paddle in remote operation: initial CW elements lost before TX state #2563 — CW Break-in timing issue with serial paddle in remote operation: initial CW elements lost before TX state
• Contest Support - Ability to record CW sidetone along with RX Audio. #2539 — Contest Support - Ability to record CW sidetone along with RX Audio
• Ver 0.9.8 TX to RX delay when stop sending CW #2528 — Ver 0.9.8 TX to RX delay when stop sending CW
• Local sidetone and USB paddle/key not working #1075 — Local sidetone and USB paddle/key not working
• CW practice mode (sidetone only, no TX) #324 — CW practice mode (sidetone only, no TX)

Open CW decoder / CW feature requests

• CW decoder and transmitter #2815 — CW decoder and transmitter
• CW decoder ( CW Skimmer) #350 — CW decoder (CW Skimmer)
• Add a hardware panel switch to toggle the CW decoder on and off #2238 — CW Decoder on/off through switch
• Add CW (CWX) keying and macros over the TCI protocol #1677 — CW over TCI
• Automatically open CW decode window on mode change to CW (even for non-active slices), with optional setting #1645 — Automatically open CW decode window on mode change to CW
• CW pitch centering indicator within filter bandwidth (K3-style) #1494 — CW pitch centering indicator within filter bandwidth (K3-style)
• CW Decoder With Radio Audio #1031 — CW Decoder With Radio Audio
• Bug / Feature Request: CW Decoder Should Not Require PC Audio to be Enabled #617 — Bug / Feature Request: CW Decoder Should Not Require PC Audio to be Enabled
• CW: add Ultimatic keyer mode alongside Iambic A/B #416 — CW ultimatic mode
• CWX: support merged CW prosigns (BT, AR, SK, KN) in input and macros #325 — CWX prosign support
• Add asymmetric CW filter shape control (independent left/right bandwidth) #1756 — Add asymmetric CW filter shape control

Open CW-adjacent UI / slice / spectrum reports

• changed mode from ssb to cw on scile A when i clicked dxspot in cw on scile B #1981 — changed mode from ssb to cw on slice A when clicking a CW DX spot on slice B
• Waterfall goes blank for ~12 seconds after CW transmit before resuming #1916 — Waterfall disappears after transmitting CW
• Zero beat Slice A affects in slice B #2516 — Zero beat Slice A affects in slice B

Closed or previously-addressed sidetone/keying/CWX history

• bug(cwx): CW sidetone ignores speaker mute — dedicated sink bypasses AudioEngine::setMuted() #2755 — CW sidetone ignores speaker mute; dedicated sink bypasses AudioEngine::setMuted()
• Add CWX function key support to FlexControl mappings #2721 — Add CWX function key support to FlexControl mappings
• Disagree with closing https://github.com/ten9876/AetherSDR/issues/2629 #2668 — Follow-up/disagreement around CWX keying with PC Audio: No CW sidetone monitor heard #2629 closure
• CWX with PC Audio ON looses the first character #2628 — CWX with PC Audio ON loses the first character
• Function key macros (F1-F12) for CWX/DVK only work when their side panels are open #2582 — Function key macros (F1-F12) for CWX/DVK only work when their side panels are open
• CWX Live mode force-sends new characters before previous character finishes #2473 — CWX Live mode force-sends new characters before previous character finishes
• CWX macro / Fx key TX leaves radio stuck in TX >60 s before returning to RX #2450 — CWX macro / Fx key TX leaves radio stuck in TX >60 s before returning to RX
• [Feature] Independent RX/TX CW decode toggles — decode what you send #2417 — Independent RX/TX CW decode toggles
• No RF from iambic paddle connected to USB port of MacBook #2332 — No RF from iambic paddle connected to USB port of MacBook
• RX audio lost after CWX macro/send transmission on AetherSDR 0.9.5.1 #2306 — RX audio lost after CWX macro/send transmission
• ggmorse.cpp line 87: Å Morse sequence incorrect (01110 → 01101) per ITU-R M.1677-1 #2264 — ggmorse Morse sequence correction
• No CW local sidetone on Windows version 0.9.1 #2097 — No CW local sidetone on Windows version 0.9.1
• No CW local sidetone on Windows version 0.9.1 #2100 — No CW local sidetone on Windows version 0.9.1
• Local sidetone generated when keying iambic paddle in SSB mode #2091 — Local sidetone generated when keying iambic paddle in SSB mode
• Iambic paddle now has local sidetone, but does not transmit #2087 — Iambic paddle has local sidetone but does not transmit
• CW sidetone: replace QAudioSink with PortAudio backend for sub-5ms latency #2072 — Replace CW sidetone QAudioSink with PortAudio backend for sub-5 ms latency
• CWX no sidetone and Send does not work version 0.9.0 #2045 — CWX no sidetone and Send does not work version 0.9.0
• Local STn slider has no effect on PC sidetone volume #2030 — Local STn slider has no effect on PC sidetone volume
• CW decode how to disable the pannel #2018 — CW decode panel disable behavior
• CW Paddle connected to a midi device do not transmit with AetherSDR 0.9.0 #2010 — CW paddle connected to MIDI device does not transmit
• [BUG] Local CW sidetone latency exceeds ~25 ms claim; iambic paddle sidetone tracks lever state, not element timing (follow-up to #1969) #1989 — Local CW sidetone latency exceeds claim; iambic paddle sidetone tracks lever state
• CW Straight Key netCW UDP keying does not trigger radio TX (firmware 4.1.5) #1973 — CW straight key netCW UDP keying does not trigger radio TX
• Clicking SSB DXCluster spot incorrectly switches radio to CW mode #1846 — Clicking SSB DXCluster spot incorrectly switches radio to CW mode
• Center vertical line in CW mode #1526 — Center vertical line in CW mode
• CW Decoder Should Default to Off #1310 — CW Decoder Should Default to Off
• Options to Save Decoded CW Text #1299 — Options to Save Decoded CW Text
• too thick zero line in cw #1196 — Too-thick zero line in CW
• CW Return to RX takes > 3 sec #1127 — CW return to RX takes more than 3 seconds
• CW Autotune Once keeps tuning #1080 — CW Autotune Once keeps tuning
• CWX Macro features need a little imrpvements #1030 — CWX macro feature improvements
• Ver0.8.6 CW TX off center #1027 — CW TX off center
• Persist CW (decoder) sensitivity #804 — Persist CW decoder sensitivity
• CW loc cut slope #764 — CW low-cut slope
• CW decoder not working #474 — CW decoder not working
• cw decode #392 — CW decode
• cw decode #296 — CW decode
• CW remote Operation #258 — CW remote operation

Acceptance criteria for closing this tracking issue

• [bug] Route CW sidetone to selected audio output #2899 is merged or superseded by an equivalent fix.
• Field verification confirms sidetone follows the selected AetherSDR PC output after settings changes.
• Field verification confirms sidetone follows the selected output after accepting the new-device dialog.
• Field verification confirms sidetone follows OS default changes when AetherSDR is configured to use the system default output.
• Any remaining CW sidetone reports after [bug] Route CW sidetone to selected audio output #2899 are triaged into separate root causes instead of being folded into the output-routing failure mode.