Merge pull request #3 from AkuchiS/fix/windows-support

Windows support: GPU→CPU fallback, bundled selftest clip, UTF-8 stdout, pipx-first README (v0.1.15)

Author: AkuchiS

README.md

@@ -31,9 +31,9 @@ What you get:
 
 ## Download — no terminal needed
 
-Download, open the `.dmg`, drag **Yap** to Applications. That's the whole thing:
+Grab it for your platform — macOS is a signed, notarized app; Windows & Linux install in one line (see [Install](#install)):
 
-| [⬇ macOS (.dmg)](https://github.com/AkuchiS/Yap/releases/latest) | [Windows (pipx)](#install) | [Linux (pipx)](#install) |
+| [![macOS](https://img.shields.io/badge/macOS-download_.dmg-000000?style=for-the-badge&logo=apple&logoColor=white)](https://github.com/AkuchiS/Yap/releases/latest) | [![Windows](https://img.shields.io/badge/Windows-install-0078D6?style=for-the-badge&logo=windows&logoColor=white)](#install) | [![Linux](https://img.shields.io/badge/Linux-install-FCC624?style=for-the-badge&logo=linux&logoColor=black)](#install) |
 |:---:|:---:|:---:|
 
 > **macOS:** signed & notarized — just open it (no right-click dance). On first launch, **Allow** the Microphone, Accessibility, and Input Monitoring prompts; after allowing Accessibility, **quit and reopen Yap once** so the hotkey activates. Then hold your hotkey and talk. Comfortable with a terminal? See [Install](#install) below.
@@ -52,24 +52,28 @@ Download, open the `.dmg`, drag **Yap** to Applications. That's the whole thing:
 ## Install
 
 Requires **Python 3.9–3.13** (3.14 is too new — some native deps don't have
-wheels for it yet). The local engine downloads a small Whisper model on first use. Clone, run the installer, go:
+wheels for it yet). The local engine downloads a small Whisper model on first use.
+
+**Any OS — one line** (recommended, and the way to install on **Windows**), via
+[pipx](https://pipx.pypa.io):
 
 ```bash
-git clone https://github.com/AkuchiS/yap.git
-cd yap
-./install.sh
+pipx install "yap-dictation[full] @ git+https://github.com/AkuchiS/yap"
 yap run
 ```
 
-`./install.sh` sets up an isolated [pipx](https://pipx.pypa.io) environment so
-nothing pollutes your system Python. Then hold **Right Option**, speak, and let
-go; your words land at the cursor.
+The `[full]` extra pulls the desktop bits (macOS menu-bar `rumps`); plain `git+…`
+installs the core CLI only, so `yap app` won't start without it.
+
+**macOS / Linux — clone + installer** (sets up the pipx env for you):
+
+```bash
+git clone https://github.com/AkuchiS/yap.git && cd yap && ./install.sh && yap run
+```
 
-> Prefer a one-liner?
-> `pipx install "yap-dictation[full] @ git+https://github.com/AkuchiS/yap"`
-> does the same thing. The `[full]` extra pulls in the macOS menu-bar bits
-> (`rumps`); plain `git+…` installs the core CLI only, so `yap app` won't start
-> without it.
+> `./install.sh` is a **bash script — macOS/Linux only**. On **Windows**, use the
+> pipx one-liner above (from PowerShell or any terminal). Then hold **Right
+> Option**, speak, and let go; your words land at the cursor.
 
 ### Per-OS extras
 
@@ -80,7 +84,10 @@ go; your words land at the cursor.
   `xclip` / `xsel`. On **Wayland**, install `wl-clipboard`; some compositors
   restrict synthetic keystrokes — use `--engine local` with
   `inject.method = "type"` if paste doesn't land.
-- **Windows** — no extra steps; run from a normal terminal.
+- **Windows** — no extra steps; run from a normal terminal. **Updating:** stop yap
+  first (Ctrl-C the `yap run` window / quit the app) before `pipx upgrade
+  yap-dictation` — a running worker holds `yap.exe` open, so an in-place upgrade
+  otherwise hits `WinError 32` (file in use).
 
 ## Usage
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "yap-dictation"
-version = "0.1.14"
+version = "0.1.15"
 description = "Free, offline-first, cross-platform voice dictation — speak anywhere, get text at your cursor."
 readme = "README.md"
 license = { text = "MIT" }
@@ -49,3 +49,7 @@ Issues = "https://github.com/yap-dictation/yap/issues"
 
 [tool.setuptools.packages.find]
 include = ["yap*"]
+
+[tool.setuptools.package-data]
+# ship the self-test clip inside the wheel so `yap selftest` works from a pip/pipx install
+yap = ["assets/*.wav"]

yap/__init__.py

@@ -5,7 +5,7 @@
 cloud speed when you want it.
 """
 
-__version__ = "0.1.14"
+__version__ = "0.1.15"
 
 # Keep startup/shutdown quiet: HuggingFace's "set a HF_TOKEN" rate-limit notice
 # (we only ever download public Whisper models) and the benign leaked-semaphore

yap/assets/jfk.wav

@@ -210,12 +210,16 @@ def _cmd_license(args) -> int:
 
 
 def _bundled_sample() -> str:
-    """Path to the built-in self-test clip (works frozen via _MEIPASS or in-repo)."""
+    """Path to the built-in self-test clip. Order: PyInstaller bundle → the packaged asset shipped
+    inside the wheel (so `yap selftest` works from a pip/pipx install) → the in-repo tests dir."""
     base = getattr(sys, "_MEIPASS", None)
     if base:
         p = os.path.join(base, "jfk.wav")
         if os.path.exists(p):
             return p
+    packaged = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets", "jfk.wav")
+    if os.path.exists(packaged):
+        return packaged
     here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
     return os.path.join(here, "tests", "jfk.wav")
 
@@ -458,7 +462,18 @@ def build_parser() -> argparse.ArgumentParser:
     return p
 
 
+def _force_utf8_stdio() -> None:
+    """Windows consoles default to cp1252 and crash on the ✓/✗/⚠ glyphs (`yap doctor` etc.).
+    Make our output UTF-8 — a no-op where it already is. Fail-soft."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+
 def main(argv: list[str] | None = None) -> int:
+    _force_utf8_stdio()
     parser = build_parser()
     args = parser.parse_args(argv)
     from . import licensing

yap/cli.py

@@ -57,6 +57,20 @@ def check_trust(prompt: bool = False):
     return trusted
 
 
+def _no_key_hint() -> None:
+    """Platform-appropriate advice when the hotkey listener saw no key events (non-Wayland)."""
+    if sys.platform == "darwin":
+        print("    → a trust/permission problem, not a key-choice problem. Add the app you ran")
+        print("    this from to Accessibility AND Input Monitoring above, then Cmd+Q and reopen.")
+    elif sys.platform.startswith("win"):
+        print("    → on Windows there's no Accessibility gate. Usually another app is grabbing the")
+        print("    key, or a fullscreen/elevated app is stealing input. Try a different hotkey")
+        print("    (`yap config set hotkey.combo '\"<f9>\"'`), or run the terminal as Administrator.")
+    else:
+        print("    → on Linux/X11, global keys should work — check no other app has grabbed the")
+        print("    key, and try a different combo. (On Wayland the listener can't fire at all.)")
+
+
 def keytest(cfg: dict[str, Any], seconds: int = 12) -> None:
     try:
         from pynput import keyboard
@@ -111,8 +125,7 @@ def on_release(k):
             print("    NOT a permission problem and no key choice fixes it. Bind a")
             print("    compositor key to `yap toggle` instead (see the note above).")
         else:
-            print("    → a trust/permission problem, not a key-choice problem.")
-            print("    Fix Accessibility + Input Monitoring above.")
+            _no_key_hint()
     else:
         print("  (If you saw your hotkey above but no MATCH line, the combo is wrong —")
         print("   copy the 'canonical=' value into hotkey.combo.)")
@@ -177,7 +190,11 @@ def run(cfg: dict[str, Any], prompt: bool, seconds: int) -> int:
     _hr("4. Clipboard")
     cliptest()
 
-    print("\nDone. The #1 fix when section 2 saw no keys: add the app you ran this")
-    print("from to Accessibility AND Input Monitoring, then Cmd+Q and reopen it.")
-    print("Tip: `yap doctor --prompt` pops the macOS 'allow control' dialog for you.")
+    if sys.platform == "darwin":
+        print("\nDone. The #1 fix when section 2 saw no keys: add the app you ran this from to")
+        print("Accessibility AND Input Monitoring, then Cmd+Q and reopen it.")
+        print("Tip: `yap doctor --prompt` pops the macOS 'allow control' dialog for you.")
+    else:
+        print("\nDone. If section 2 saw no keys (and you're not on Wayland), another app is likely")
+        print("grabbing the hotkey — pick a free one: `yap config set hotkey.combo '\"<f9>\"'`.")
     return 0

yap/doctor.py

@@ -42,28 +42,39 @@ def resolved_model(self) -> str:
             return recommend_model(prefer_english=prefer_en)
         return model
 
-    def _ensure_model(self):
+    active_device = "cpu"
+
+    def _ensure_model(self, force_cpu: bool = False):
         if self._model is not None:
             return self._model
         from faster_whisper import WhisperModel
 
-        device, default_ct = _resolve_device(self.cfg.get("device", "auto"))
-        compute_type = self.cfg.get("compute_type", "auto")
-        if compute_type == "auto":
-            compute_type = default_ct
+        if force_cpu:
+            device, compute_type = "cpu", "int8"
+        else:
+            device, default_ct = _resolve_device(self.cfg.get("device", "auto"))
+            compute_type = self.cfg.get("compute_type", "auto")
+            if compute_type == "auto":
+                compute_type = default_ct
         self.active_model = self.resolved_model()
-        self._model = WhisperModel(
-            self.active_model,
-            device=device,
-            compute_type=compute_type,
-        )
+        try:
+            self._model = WhisperModel(self.active_model, device=device, compute_type=compute_type)
+        except Exception as e:
+            # GPU was chosen but its CUDA runtime is missing/broken (e.g. `cublas64_12.dll not
+            # found`) or out of memory — never crash: fall back to CPU int8, which always works.
+            if device == "cpu":
+                raise
+            import sys
+            print(f"yap: GPU init failed ({str(e)[:140]}); using CPU instead.", file=sys.stderr)
+            self._model = WhisperModel(self.active_model, device="cpu", compute_type="int8")
+            device = "cpu"
+        self.active_device = device
         return self._model
 
     def warmup(self) -> None:
         self._ensure_model()
 
-    def _decode(self, audio) -> str:
-        model = self._ensure_model()
+    def _run(self, model, audio) -> str:
         language: Optional[str] = self.cfg.get("language")
         segments, _info = model.transcribe(
             audio,
@@ -74,6 +85,21 @@ def _decode(self, audio) -> str:
         )
         return "".join(seg.text for seg in segments).strip()
 
+    def _decode(self, audio) -> str:
+        model = self._ensure_model()
+        try:
+            return self._run(model, audio)
+        except Exception as e:
+            # Some CUDA breakage only surfaces on the FIRST transcription (lazy cuBLAS load). If
+            # we're on the GPU, drop to CPU and retry once rather than crashing the app.
+            if self.active_device == "cpu":
+                raise
+            import sys
+            print(f"yap: GPU transcription failed ({str(e)[:140]}); retrying on CPU.", file=sys.stderr)
+            self._model = None
+            model = self._ensure_model(force_cpu=True)
+            return self._run(model, audio)
+
     def transcribe_file(self, wav_path: str) -> str:
         return self._decode(wav_path)