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:

```sh
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:

```sh
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:

```powershell
$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:

- [x] 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.
- [x] 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.
- [x] 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.