feat: add noctwhspr plugin

2026-07-16 20:16:39 -07:00
parent c5ee4f4fe1
commit 681e8ee057
5 changed files with 223 additions and 0 deletions
@@ -0,0 +1,72 @@
+# noctwhspr
+
+Noctalia companion for [hyprwhspr](https://github.com/goodroot/hyprwhspr) —
+native speech-to-text for Linux. hyprwhspr is fast, accurate, private,
+system-wide dictation: press a hotkey, talk, and your words land in whatever
+you were typing — transcribed by local in-memory models (Whisper, Parakeet)
+that never leave your machine, or by top cloud APIs if you point it there.
+Its visuals even theme themselves to match your Noctalia theme.
+
+This plugin puts hyprwhspr on your bar: the widget shows the dictation state
+at a glance, left-click starts or stops a recording, and right-click restarts
+the hyprwhspr service if it ever gets stuck.
+
+## Plugin
+
+| Field | Value |
+| --- | --- |
+| ID | `goodroot/noctwhspr` |
+| Entries | Bar widget: `status` |
+
+## Requirements
+
+Install [`hyprwhspr`](https://github.com/goodroot/hyprwhspr) and set it up so
+its `hyprwhspr.service` systemd user service exists. The widget drives
+hyprwhspr's own tray script (`hyprwhspr-tray.sh`), which it looks up under the
+install root — `/usr/lib/hyprwhspr` for the Arch/AUR package. Nothing else is
+needed; the widget has no network access of its own.
+
+## Usage
+
+Enable the plugin in Settings → Plugins, then add the `status` widget to your
+bar in Settings → Bar.
+
+The glyph tracks the dictation state reported by hyprwhspr:
+
+| Glyph | State |
+| --- | --- |
+| Filled record dot (error color) | Recording — dictation is capturing audio |
+| Microphone (primary color) | Ready — service is up, waiting for a hotkey or click |
+| Zzz | Model unloaded — first recording will load it |
+| Microphone off | Service stopped |
+| Warning triangle | Error — the tooltip explains what is wrong |
+
+Interactions:
+
+- **Left-click** — toggle recording (same as the hyprwhspr hotkey). If the
+  service is stopped, this starts it first.
+- **Right-click** — restart the `hyprwhspr.service` systemd user service.
+- **Hover** — the tooltip shows the detailed status line, including error
+  reasons when something is wrong.
+
+## Settings
+
+| Setting | Type | Default | Description |
+| --- | --- | --- | --- |
+| `root` | `string` | `/usr/lib/hyprwhspr` | Directory hyprwhspr is installed under. Leave at the default unless hyprwhspr lives at a non-standard prefix; `HYPRWHSPR_ROOT` in Noctalia's environment is also honored. |
+
+## Notes
+
+- The widget is a thin shim over hyprwhspr's tray script — the same script
+  that backs its Waybar module — so state detection stays in one place. It
+  polls `<root>/config/hyprland/hyprwhspr-tray.sh status` every 2 seconds and
+  renders the returned JSON.
+- Spawned processes: the tray script on every poll and click; the script in
+  turn queries `systemctl --user` and hyprwhspr's runtime state files.
+  Right-click runs `systemctl --user restart hyprwhspr.service` through the
+  script. No network calls and no filesystem writes are made by the plugin
+  itself.
+- If the widget shows "hyprwhspr not found", hyprwhspr is not installed at
+  the configured root — point the `root` setting at your install prefix.
+- Works on any compositor Noctalia runs on; the `hyprland` in the script path
+  is historical, hyprwhspr itself supports Hyprland, Niri and friends.