Skip to content

Windows port: same Rust architecture, same models, unified release - #26

Open
itisrmk wants to merge 7 commits into
mainfrom
t3code/add-windows-rust-port
Open

itisrmk wants to merge 7 commits into
mainfrom
t3code/add-windows-rust-port

Conversation

@itisrmk

@itisrmk itisrmk commented Sep 30, 2026

Copy link
Copy Markdown
Owner

What this adds

A full Windows port under windows/, built the same way as the Linux port: a separate Rust crate mirroring linux/ module for module, sharing the same behaviour, the same speech engines, and the same model catalog.

Same everything, Windows underneath

Layer Linux Windows
Core (state machine, settings, catalog, text pipeline) linux/src/core/ identical port, same tests
Hotkey evdev (/dev/input) WH_KEYBOARD_LL hook — left/right modifiers distinct, injected keys filtered, same press/hold/double-press tracker
Insertion wtype, then Ctrl+V paste SendInput Unicode typing, then Ctrl+V paste, terminal-aware delays
Audio cpal (ALSA) cpal (WASAPI), same 16 kHz mono converter
Engines whisper.cpp / faster-whisper / Parakeet ONNX / OpenAI same engines, same stt_daemon.py JSONL protocol, same Hugging Face repos and GGUF files
UI GTK4 + layer-shell + ksni egui + tray-icon, carrying the same design tokens (palette, Archivo, 2px rules, zero radius, 900×700 settings window, same tabs, bubble/top-bar overlay, same drawn tray mark)

Windows-specific decisions

  • whisper.cpp stays the default provider. Windows has no distro package, so Settings → Provider gains an Install whisper.cpp button that downloads the official prebuilt whisper-cli.exe (pinned v1.9.2 tag, checksum-verified) into the app's data directory. No Python, no installer, one click to remove.
  • The managed Python runtime prefers uv (winget install astral-sh.uv), since Windows ships no Python and the Store python alias is a stub.
  • Config in %APPDATA%\whisper-smart\config.toml, models/runtime/logs under %LOCALAPPDATA%\whisper-smart\ — a Linux config.toml works as-is (the catalogs share IDs).

Unified release

  • CI gains a Windows job (fmt + clippy -D warnings + tests + package). It uploads the zip as a workflow artifact, so this PR's build can be downloaded and tested on a real Windows machine before merging.
  • release.yml becomes params → (macos ‖ linux ‖ windows) → publish: the zip is version-stamped, verified against the tag, and attached to the same vX.Y.Z release as the DMG and tarball. Release notes gain a Windows download row.

Verification

  • 247 tests pass (cargo test), cargo fmt --check and cargo clippy --all-targets -- -D warnings clean on both the host and x86_64-pc-windows-msvc targets; the Python sidecar compiles.
  • The crate also builds/tests on Unix hosts with stubbed platform integrations, so the portable core stays testable everywhere.
  • Not yet exercised on a live Windows desktop — that is what the CI artifact from this PR is for.

🤖 Generated with Claude Code

itisrmk and others added 7 commits September 29, 2026 23:07
A new windows/ crate mirroring linux/ module for module: same dictation
state machine, settings model, model catalog, text pipeline, and the same
speech engines over the same JSONL sidecar protocol (whisper.cpp,
faster-whisper, Parakeet ONNX, OpenAI API). The platform layer is Win32 —
a WH_KEYBOARD_LL hook for the hold-to-talk hotkey (left/right modifiers
are distinct VK codes, injected keystrokes filtered), SendInput Unicode
typing with a clipboard-paste fallback and terminal-aware delays, WASAPI
capture via cpal — and the UI is egui carrying the same design tokens:
palette, Archivo, 2px rules, zero corner radius, the 900x700 settings
window with the same tabs, the bubble/top-bar overlay, and the same drawn
tray mark per dictation state.

Windows has no distro package for whisper.cpp, so the app installs the
official prebuilt whisper-cli.exe (pinned tag, checksum-verified) into
its own data directory on request, keeping whisper.cpp as the zero-Python
default provider. The managed Python runtime prefers uv, since Windows
ships no Python and the Store alias is a stub.

CI gains a windows job (fmt + clippy + tests + zip, uploaded as a
workflow artifact so PR builds are testable), and the release workflow
becomes params -> (macos || linux || windows) -> publish, with the zip
stamped, version-verified, and attached to the same vX.Y.Z release as
the DMG and tarball.

The crate also builds and tests on Unix hosts with stubbed platform
integrations; the Win32 layer is checked from them with
--target x86_64-pc-windows-msvc.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Field testing surfaced three linked failures, all rooted in one eframe
behaviour: on Windows, a hidden or minimized window stops receiving
update passes, and viewport show/hide commands stop being processed with
them (egui#5229). The old structure hid the root settings window at
launch, so tray commands (Settings, Quit) queued forever, the window
Windows showed anyway painted the intentionally blank "hidden" frame,
and with Quit dead every relaunch stacked another instance.

Restructure to the architecture eframe supports: the root viewport is a
permanent 1x1 transparent helper parked off-screen (always "visible",
so the loop always ticks, still 0 fps when idle), and the settings
window and recording overlay are child viewports that exist exactly
while they are open — no hide/show commands left to deadlock. Settings
opens on launch so running the exe visibly does something; closing it
leaves the app in the tray.

Also:
- single-instance guard via a named mutex; a second launch shows a
  toast pointing at the tray instead of stacking processes
- Quit gets a 2s process-exit failsafe behind the clean Close path
- the overlay re-centres from its own monitor (the off-screen root's
  monitor cannot be trusted) and is click-through, matching the Linux
  layer-shell overlay's non-interactivity
- the settings viewport's window icon is cached instead of being
  PNG-decoded per frame

Verified: all gates green on host and x86_64-pc-windows-msvc targets,
and an 8s live run of the new viewport structure (settings + error
overlay) on the dev host rendered without panics.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Second round of field findings.

The Model card's tier badges used a justified layout, which expanded each
badge to the full row width and shoved the tier titles, descriptions and —
worst of all — the download progress text past the right edge of the
window, so a long model download looked like nothing was happening. The
badge is now painted at a fixed size, the tier rows claim their selection
control from the right edge first so the text column wraps inside what
remains, and prose (notes, row descriptions, status lines) wraps instead
of clipping.

Downloads could also genuinely hang silently: ureq had no connection
timeouts, so a stalled connection sat at "Downloading…" forever. Name
resolution, connect, and response-header phases are now bounded (bodies
are not — a 1.6 GB model on a slow line is legitimate), chunked responses
without a Content-Length report progress in 5 MB steps, and the OpenAI
request is bounded end to end. The other real slowness: installing the
Python runtime with the default "Auto" compute device pulled the NVIDIA
CUDA wheels — roughly a gigabyte — on machines with no NVIDIA GPU. Auto
now resolves against the actual hardware at install time; an explicit
CUDA/CPU choice is honoured unchanged.

The error pill also floated at the top of the screen instead of
bottom-centre: the overlay's parent window is parked off-screen, where no
monitor resolves, so positioning fell back to a guess. The primary
monitor's work area (via SystemParametersInfo + system DPI) now anchors
the initial position and the per-frame correction, and the pill's text
truncates to one line instead of overflowing its fixed height.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…real

The "models take forever" report was not slowness. Switching ureq to the
native-tls feature had left its *default TLS provider* set to Rustls, so
the first byte of every HTTPS download panicked the worker thread — and
the panic was swallowed, leaving the status at "Downloading…" forever.
Every build so far shipped with this. The agents now state their
provider explicitly, a UI task that panics surfaces as a visible error
instead of an eternal spinner, and a regression test makes an actual
HTTPS request in CI so this class of misconfiguration can never ship
silently again. Verified end to end: the 141 MB base model streams in
seconds with a live readout.

The Model page overflow also truly dies this time: the previous badge
fix had silently failed to apply (unasserted text replacement), so the
justified-layout badge that stretches to the window edge shipped again.
Every settings page is now verified from rendered screenshots via a new
`--ui-preview` harness (`WHISPER_SMART_TAB` picks the page) that runs
the settings UI as a plain window on any host. Rendered-and-reviewed
fixes that came out of that: fixed-size painted badges, tier rows and
the shared label/control row rebuilt with plain nesting (the nested
right-to-left layout handed its text column a sliver and rendered one
letter per line), history rows likewise, the selected-tier dot drawn
instead of a missing-font glyph, and wrapped prose everywhere.

Downloads now report "47% · 231 / 488 MB · 3.4 MB/s" in the status line
and log their duration and average rate, so slow-network and stalled
are distinguishable at a glance. The footer and --version carry the
build commit (GITHUB_SHA at compile time), so which build is running is
never a guess.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Field report: every dictation died with "Microphone capture stopped: a
buffer underrun or overrun occurred." That message is cpal's Xrun error,
which WASAPI raises through the stream error callback whenever a capture
packet carries the data-discontinuity flag — a routine event on Windows
(scheduling hiccups, Bluetooth mics) during which the stream keeps
delivering; cpal's own docs call it "a potential audio glitch". Our
error callback treated every invocation as the end of the capture.

Stream errors are now classified: Xrun, a device reroute, and a refused
real-time promotion are logged and the recording continues (a tiny gap
in the audio beats losing the dictation); genuinely terminal conditions
(device unplugged, stream invalidated) still end the session with the
same message as before. A storm of glitches (12 in one stream) still
escalates to a real error, so a truly broken capture is not silently
transcribed as garbage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Field report: dictation sticks at "Transcribing…". Two compounding
problems. The Best tier (Large-v3 Turbo) can legitimately need minutes
per utterance on CPU, which the fixed 120s timeout mislabels as a
failure. And when the state machine did time out, nothing killed the
whisper-cli process — the STT worker stayed blocked on it, so every
following dictation queued behind the zombie and the app looked
permanently stuck.

whisper-cli now runs under a hard deadline and is killed when it blows
it, with an error that names the fix ("pick a smaller model"); its
pipes are drained on their own threads so a chatty child can never
deadlock the poll. Large models get 300s, small ones keep 120s, and the
invocation logs start, duration and exit status at info level so the
log file shows exactly where a session spent its time.

Verified locally through --transcribe: the new spawn path transcribes
3s of audio in 0.4s through the real provider.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…nging

The official whisper.cpp binaries link the MSVC runtime dynamically; on
a machine without the Visual C++ Redistributable, whisper-cli.exe is
present but cannot start. Depending on the error mode it either dies
with STATUS_DLL_NOT_FOUND — which surfaced as an unexplained "no
output" failure — or blocks forever on a loader error dialog that a
GUI-subsystem parent never shows anyone, which presents as dictation
stuck at "Transcribing…".

Three layers of defence:
- SetErrorMode at startup (inherited by children) suppresses the
  invisible modal dialogs, so a failed start always returns a code;
- the known startup-failure codes (DLL_NOT_FOUND, ENTRYPOINT_NOT_FOUND,
  DLL_INIT_FAILED) are translated everywhere into a remedy that names
  the VC++ Redistributable download;
- "Install whisper.cpp" now ends with a probe run of the binary, so a
  machine that needs the redistributable hears about it at install
  time, not mid-dictation — and the Setup page's provider check probes
  the same way.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant