peerspeak/docs/WINDOWS.md

PeerSpeak on Windows

Current status: PeerSpeak cross-compiles to x86_64-pc-windows-gnu from Linux. PeerSpeak v0.6.7 at commit 7217015d passed a fresh Windows 10 22H2/build 19045 VM smoke test on 2026-08-22 for install/upgrade, launch, GUI/settings render, device selection and persistence, microphone capture startup, WASAPI playback pacing, room create/leave, and the missing-PixelPass guard. The v0.6.8 candidate adds the matching viewer-only PixelPass helper to the installer: Windows can watch Linux-hosted shares, while Windows capture/hosting remains intentionally unavailable. The build environment is not the Windows VM; current Windows binaries are built from Linux with the 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 renders on Windows 10; the current build's landing and settings screens were smoke-tested.
Networking	Iroh QUIC transport and gossip compile on Windows; the current build creates/leaves a room, and an older VM build completed a two-peer call.
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.
Screen-share viewing	The installer bundles the matching PixelPass viewer; VLC or mpv renders Linux-hosted shares.

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 idempotent PeerSpeak and PixelPass firewall allow rules. Both use UDP/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.

Fresh Windows 10 smoke — 2026-08-22

Validated on Windows 10 Enterprise Evaluation 22H2/build 19045 in the peerspeak-windows10 libvirt VM. The installed title screen reported PeerSpeak v0.6.7 (7217015d).

Definitive artifacts built from committed main:

• peerspeak.exe: 80,601,595 bytes, SHA-256 a9225ca8878acdbc54a424427a591b3f55774a9fc4d20decd40993274b9336ff
• peerspeak-0.6.7-setup.exe: 18,578,658 bytes, SHA-256 5ac551709814918f9c75a49aabed929d3f6618cdbeaf3cb4b22add8dfcbb68d9

Proven in this run:

• The final installer transferred with a matching Windows-side hash, installed under C:\Program Files\PeerSpeak, and upgraded in place without losing config.
• Upgrade testing exposed duplicate firewall rules. Commit 7217015d made the installer replace its owned rule; a final upgrade left exactly one enabled inbound PeerSpeak rule and logged exit code 0 for delete/add.
• The landing screen and all Settings categories rendered. Input Line In (High Definition Audio Device) and output Speakers (High Definition Audio Device) were selectable and restored after a clean app restart.
• Test Mic opened the real cpal/WASAPI capture path. The VM endpoint negotiated 44.1 kHz stereo and PeerSpeak resampled it to 48 kHz as designed.
• audio_probe.exe 440 30 exited 0. After one startup-fill event, every steady-state health line reported underrun +0 and dropped +0; the expected drain after tone generation stopped registered at shutdown. No human audible tone assessment was available during this automated run.
• A one-participant room connected and left cleanly. With no pixelpass.exe, Share Screen opened the dependency instructions rather than crashing.
• The app log ended with the correct version/hash and Windows Event Viewer had no PeerSpeak application errors.

Still manual or two-party: current-build Linux↔Windows audio in both directions, chimes, chat/files/music/recording, friends/presence, game detection, audible probe quality, and uninstall/firewall cleanup.

Known gaps

Item	Status
Echo cancellation	Linux-only today. The Windows UI shows it disabled as unavailable.
Screen share	Viewing Linux-hosted shares is implemented with the bundled PixelPass helper. Windows capture/hosting remains pending.
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 current 0.6.7 build passed the bounded Windows 10 smoke above; the remaining two-party and feature-specific rows still need coverage.

Current smoke checklist

Before calling Windows feature parity complete, finish these checks on the Windows VM or real Windows hardware. The original checks below passed for v0.6.7 at 7217015d; screen-share rows track the v0.6.8 candidate separately:

• Launch current peerspeak.exe; GUI renders and settings open.
• Run audio_probe.exe 440 30; automated playout-health passed, but listen for glitches on physical hardware.
• 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.
• Run the Windows PixelPass viewer against a live Linux PixelPass host; video rendered and the viewer exited when VLC closed.
• Watch a Linux-hosted share through the installed PeerSpeak UI; confirm video and audio on real Windows hardware.
• Confirm Windows clearly refuses screen-share hosting while Watch remains available.
• Install/upgrade/uninstall through the Inno installer, including firewall rule cleanup. Clean install and idempotent upgrade passed; uninstall remains.