Installing WhisperWriter on Windows

I wanted local, push-to-talk voice dictation into a Claude Code CLI session running over a VS Code Remote-SSH connection from my Windows laptop to a Linux box. The right place to do speech-to-text in that setup is the Windows side — that’s where the microphone is, and any tool that types into the focused window will land characters straight into the integrated terminal.

WhisperWriter is the obvious choice: free, runs faster-whisper locally, global hotkey, types into any focused window. The catch is that the install on a fresh Windows 11 machine fights you in three or four different ways before it works. This post is the recipe I wish I’d had.

The recipe

1. Install MSVC Build Tools (safety net)

Go to https://visualstudio.microsoft.com/visual-cpp-build-tools/ and click Download Build Tools. Run the installer and check the “Desktop development with C++” workload. It’s about 6 GB.

You may not strictly need this once you’ve fixed every package below, but having it installed eliminates an entire failure category and costs you nothing once it’s there.

2. Clone outside OneDrive

This is non-negotiable. OneDrive’s Files On-Demand provider blocks hardlinks, and uv (along with most modern Python tooling) wants to hardlink aggressively. Create a folder that OneDrive does not touch and clone there:

mkdir C:\Users\jagat\non_onedrive
cd C:\Users\jagat\non_onedrive
git clone https://github.com/savbell/whisper-writer
cd whisper-writer

If you’ve used Windows’ “Move Documents to OneDrive” feature, even C:\Users\jagat\Documents is OneDrive-backed. Pick a path that clearly isn’t.

3. Patch requirements.txt

Open requirements.txt and change:

av==11.0.0

to:

av>=12.0.0

PyAV 12+ ships prebuilt Windows wheels with FFmpeg bundled, so no compiler, no FFmpeg install, no link errors. WhisperWriter only uses PyAV for audio decoding and the API is stable across the bump.

4. Force uv to copy instead of hardlink

Even outside OneDrive, the uv cache itself lives under %LOCALAPPDATA%\uv\cache, which is inside your user profile and may inherit OneDrive attributes if Known Folder Move is on. The bulletproof fix is to tell uv to copy:

$env:UV_LINK_MODE = "copy"

To make it permanent across sessions:

[Environment]::SetEnvironmentVariable("UV_LINK_MODE", "copy", "User")

If you also want the cache itself outside the user profile:

[Environment]::SetEnvironmentVariable("UV_CACHE_DIR", "C:\uv-cache", "User")

5. Pin Python 3.11 and create the venv

WhisperWriter’s deps have the best wheel coverage on 3.11. Don’t try this on 3.12 or 3.13 — you’ll trip more compile errors.

uv python pin 3.11
uv venv
.\.venv\Scripts\activate

6. Install the prebuilt webrtcvad fork

Don’t install webrtcvad directly. Use the prebuilt wheel fork — it ships the same webrtcvad Python module, no code changes needed:

uv pip install webrtcvad-wheels

7. Install everything else

uv pip install -r requirements.txt
uv pip install setuptools
uv pip install -U ctranslate2

setuptools is for the missing pkg_resources import. Upgrading ctranslate2 is the proper fix — newer versions dropped that legacy import — and it’s a no-op if your pinned version is already new enough.

8. Run it

python .\run.py

You should get the WhisperWriter tray icon and config window. Set your hotkey, pick a model (base.en for speed, medium.en or large-v3 for accuracy on technical vocabulary), and talk.