peerspeak/docs/WINDOWS.md

PeerSpeak on Windows

Current status: PeerSpeak cross-compiles to x86_64-pc-windows-gnu from Linux and has passed an older native Windows 11 VM smoke test for launch, GUI render, call join, and audio flow. The build environment is not the Windows VM; current Windows binaries are built from Linux, normally inside the peerspeak-win distrobox or with the same GNU target environment.

The Windows runtime still trails Linux in a few important areas. See the Claude handoff file windows-parity-audit.md for the full audit and task breakdown.

What works today

Area	Status
GUI	Iced/wgpu builds for Windows and rendered in the Windows 11 VM.
Networking	Iroh QUIC transport and gossip compile on Windows; VM call reached two peers.
Audio backend	cpal drives WASAPI capture/playback behind AudioBackend.
Device selection	cpal enumerates input/output devices; see caveat below about stable IDs.
Resampling/remap	WASAPI devices can run non-48 kHz formats; PeerSpeak converts at the backend boundary.
Codec	Opus remains 48 kHz mono, 20 ms frames.
Identity/config	Stored through dirs under the Windows profile.
Chimes	Windows uses PowerShell System.Media.SoundPlayer for WAV playback.
Game detection	Steam registry RunningAppID plus Toolhelp process-scan fallback compile on Windows.
File dialogs	rfd uses the native Win32 dialog backend.

Windows paths are resolved through dirs:

• Config: %APPDATA%\peerspeak\config.json
• Identity: %APPDATA%\peerspeak\identity.key
• Log: %LOCALAPPDATA%\peerspeak\peerspeak.log

Building

Cross-compile from Linux

Preferred local path:

distrobox enter peerspeak-win -- bash -lc '
  cd ~/git/butter/peerspeak &&
  RUSTC_BOOTSTRAP=1 ./win-cross-build.sh -Z build-std=std,panic_abort
'

Equivalent direct command when the host has the GNU target, MinGW, rust-src, and CMake available:

CMAKE_POLICY_VERSION_MINIMUM=3.5 RUSTC_BOOTSTRAP=1 \
  cargo build --release --target x86_64-pc-windows-gnu --bin peerspeak \
  -Z build-std=std,panic_abort

CMAKE_POLICY_VERSION_MINIMUM=3.5 is required with host CMake 4.x because the vendored Opus build used by audiopus_sys still declares an old minimum CMake version. Without that env var, the Windows build/check fails during Opus configure.

Native Windows

A native MSVC build is not the active development path. If used, install MSVC Build Tools and CMake, then build normally:

$env:CMAKE_POLICY_VERSION_MINIMUM = "3.5"
cargo build --release

First run and networking

Expect a Windows Firewall prompt the first time the app opens network sockets, or use the Inno installer option that pre-adds a firewall allow rule. PeerSpeak uses UDP for QUIC plus relay traffic when direct NAT traversal is unavailable.

The default network mode keeps the n0 relay available for NAT traversal without publishing presence to n0 DNS. Relayed connections are expected and valid.

Known gaps

Item	Status
Echo cancellation	Linux-only today. The Windows UI shows it disabled as unavailable.
Screen share	Blocked by PixelPass, which is currently Linux-only in practice. PeerSpeak can spawn pixelpass.exe, but there is no Windows PixelPass host/viewer parity yet.
Device persistence	Uses cpal friendly names as keys. These can duplicate or change across Windows driver/profile changes; stable WASAPI endpoint IDs are still needed.
Release hygiene	Keep .iss and installer output in sync with Cargo.toml; rebuild Windows artifacts during each release.
Runtime coverage	The Windows VM smoke test proved an older tester build. Current main needs a fresh VM smoke matrix before calling parity current.

Current smoke checklist

Before calling a Windows build current, verify on the Windows VM or real Windows hardware:

• Launch current peerspeak.exe; GUI renders and settings open.
• Run audio_probe.exe 440 30; listen for glitches and inspect playout-health.
• Create/join a Linux <-> Windows room; confirm mic and playback both directions.
• Select input/output devices, restart, and confirm selections persist or fall back clearly.
• Play chimes and custom chime paths.
• Send chat, image/file attachments, and save an attachment through the native dialog.
• Import/play/share/listen to music from Windows file paths.
• Record mixed/stems/both and inspect the WAV output path.
• Exercise friends/presence/recents and the clock-skew banner.
• Test Steam and non-Steam game detection on a real Windows Steam install.
• Install/upgrade/uninstall through the Inno installer, including firewall rule cleanup.