hyprwhspr
Native speech-to-text for Linux - Fast, accurate, private and hackable system-wide dictation
instant performance | Cohere / Parakeet / Whisper / Qwen3-ASR / ElevenLabs / REST API | stylish visuals
Supports Arch, Debian, Ubuntu, Fedora, openSUSE and more
hyprwhspr.com
https://github.com/user-attachments/assets/4c223e85-2916-494f-b7b1-766ce1bdc991
---
- **Built for Linux** - Native AUR package for Arch, or use Debian/Ubuntu/Fedora/openSUSE/NixOS
- **Very fast defaults** - Nearly instant and accurate performance via in-memory models
- **Offline and private** - Transcription never leaves your machine. Cloud APIs are fully optional.
- **Latest models** - Cohere Transcribe? Orukeet? Parakeet TDT V3? Qwen3-ASR? Latest and greatest
- **GPU memory efficient** - Limit or zero memory usage easily, more for other local models
- **onnx-asr for wild CPU speeds** - No GPU? Optimized for great speed on any hardware
- **Strong CJK** - Qwen3-ASR for Chinese, Japanese and Korean
- **Translation** - Translate non-English to English with a single config
- **REST API or websockets** - Secure, fast wires to top clouds like Gemini, ElevenLabs
- **Live streaming** - Self-host NeMo or Phonon: watch words form, or type as you speak (experimental)
- **Themed visualizer** - Visualizes your voice, will automatch Omarchy and Noctalia themes
- **Word overrides and prompts** - Custom hot keys, common words, and more
- **Multi-lingual** - Great performance in many languages
- **Long form mode with saving** - Pause, think, resume, pause: submit... Bam!
- **Auto-paste anywhere** - Instant paste into any active buffer, or even auto enter (optional)
- **Audio ducking 🦆** - Reduces or pauses other audio on record (optional)
---
**Why hyprwhspr?** There are a lotta dictation apps. This one is built ground-up for performance and stability: your hardware will auto-optimize to the **best possible accuracy and speed**. Actively maintained, at the leading edge, fully featured, strictly offline unless you use an API, and works on both Wayland and X11.
---
## Quick start
### Prerequisites
- **Linux** with systemd (Arch, Debian, Ubuntu, Fedora, openSUSE, NixOS etc.)
- **Python 3.11-3.14**
- **Wayland or X11 session** (GNOME, KDE Plasma, Sway, Hyprland, Niri, etc.).
- **Clipboard/window tools:**
- `wl-clipboard` and `wtype` on Wayland
- `python-pyperclip`, `xclip`, `xdotool`, and `xprop` on X11 (installed by the dependency script)
- **Waybar or Noctalia** (optional, for status bar)
- **gtk4 + PyCairo** (optional, for visualizer)
- **NVIDIA GPU** (optional, for CUDA acceleration)
- **AMD/Intel GPU / APU** (optional, for Vulkan acceleration)
### Install
---
#### Arch Linux
On the AUR:
```bash
# Install for stable
yay -S hyprwhspr
# Or install for bleeding edge
yay -S hyprwhspr-git
```
Then run the interactive setup:
```bash
hyprwhspr setup
```
#### Ubuntu, Debian, Fedora, openSUSE
```bash
curl -fsSL https://hyprwhspr.com/install.sh | bash
```
Installs dependencies, clones to `~/.local/share/hyprwhspr/src`, and walks you through setup.
Manual install
```bash
# Clone the repo
git clone https://github.com/goodroot/hyprwhspr.git
cd hyprwhspr
# Install dependencies for your distro
./scripts/install-deps.sh
# Run interactive setup
./bin/hyprwhspr setup
```
#### Nix and NixOS (beta)
Use the [Nix flake and NixOS module](docs/integrations/NIX.md) for x86_64 Linux
with Whisper.cpp CPU transcription.
We'd appreciate [issue reports and requests](https://github.com/goodroot/hyprwhspr/issues)!
---
**Setup then walks you through:**
1. ✅ Configure transcription backend (Cohere Transcribe, Parakeet TDT V3, Whisper, Qwen3-ASR, REST API, or Realtime WebSocket)
2. ✅ Download models
3. ✅ Configure themed visualizer for maximum coolness (optional)
4. ✅ Configure bar integration for your shell -- Waybar or Noctalia (optional)
5. ✅ Set up systemd user services
6. ✅ Set up permissions
7. ✅ Validate installation
### First use
> Ensure your microphone of choice is available in audio settings!
1. **Log out and back in** (for group permissions)
2. **Press `Super+Alt+D`** to start dictation - _beep!_
3. **Speak naturally**
4. **Press `Super+Alt+D`** again to stop dictation - _boop!_
5. **Bam!** Text appears in active buffer!
> **What you'll see while recording:** on layer-shell compositors (Hyprland, Sway, niri, KDE) the animated mic OSD overlay -- on Noctalia / Omarchy it auto-matches your live shell theme; on GNOME/Mutter you may need to make additional changes. See [Themed visualizer](docs/usage/FEEDBACK.md#themed-visualizer) for details.
Any snags, please [create an issue](https://github.com/goodroot/hyprwhspr/issues/new/choose).
### Updating
```bash
# Arch: update via your AUR helper
yay -Syu hyprwhspr
# Managed release installs
hyprwhspr update
# Legacy bootstrap installs: re-run the installer
curl -fsSL https://hyprwhspr.com/install.sh | bash
# Either way, setup is idempotent if you need to re-run it
hyprwhspr setup
```
Managed release rollout and recovery: [installation guide](docs/MANAGED_INSTALLATION.md).
### CLI commands
- `hyprwhspr setup` - Interactive initial setup
- `hyprwhspr update [--version VERSION]` - Update a managed release
- `hyprwhspr install status` - Inspect managed installation state
- `hyprwhspr install repair [--python PATH]` - Repair a managed installation
- `hyprwhspr config` - Manage configuration (`show` / `show --all` / `edit` / `secondary-shortcut`)
- `hyprwhspr model` - Manage models (`download` / `list` / `status` / `unload` / `reload`)
- `hyprwhspr record` - External hotkey control (`start` / `stop` / `toggle` / `cancel` / `capture` / `status` / `copy-last` / `paste-last` / `clear-last`)
- `hyprwhspr transcribe INPUT` - Transcribe a WAV or MP3 file to stdout (use `-o PATH` to write a file)
- `hyprwhspr status` - Overall status check
- `hyprwhspr validate` - Validate installation
- `hyprwhspr test` - Test microphone and transcription end-to-end
- `hyprwhspr keyboard` - List/test keyboard devices (`list` / `test`)
- `hyprwhspr waybar` / `hyprwhspr noctalia` - Manage bar integration
- `hyprwhspr mic-osd` - Enable/disable the mic OSD (`enable` / `disable` / `status`)
- `hyprwhspr systemd` - Manage systemd services
- `hyprwhspr uninstall` - Remove hyprwhspr; preserve settings, credentials and models
- `hyprwhspr uninstall --purge` - Also remove recorded personal files (`--keep-models` preserves models)
## Documentation
All of it at **[hyprwhspr.com/docs](https://hyprwhspr.com/docs/)**, or here:
- [Configuration](docs/CONFIGURATION.md) -- the config file, validation, minimal setup
- [Recording modes](docs/usage/RECORDING_MODES.md) · [Hotkeys](docs/usage/HOTKEYS.md) · [Paste](docs/usage/PASTE.md) · [Text processing](docs/usage/TEXT_PROCESSING.md) · [Feedback](docs/usage/FEEDBACK.md)
- [Backends](docs/backends/OVERVIEW.md) · [Memory](docs/backends/MEMORY.md) -- which model, and freeing it
- [Troubleshooting](docs/TROUBLESHOOTING.md)
## Getting help
- **Check logs**: `journalctl --user -u hyprwhspr.service`
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** covers common issues
- **Still stuck?** [Create an issue](https://github.com/goodroot/hyprwhspr/issues/new/choose) - logs helpful!
## License
MIT License - see [LICENSE](LICENSE) file.
## Contributing
Start with an issue - happy to help! Pull requests best begin there too.
Upvotes on the AUR and/or GitHub stars are also a nice way to show appreciation.
---
**Built with ❤️ in 🇨🇦**