_     _
 __      __| |__ (_)___  _ __ ___
 \ \ /\ / /| '_ \| / __|| '__/ __|
  \ V  V / | | | | \__ \| |  \__ \
   \_/\_/  |_| |_|_|___/|_|  |___/

  speak. type. done.

whisrs

whisrs is a Linux voice-to-text dictation tool written in Rust that transcribes speech via 7 backends — Groq, Deepgram REST, Deepgram Streaming, OpenAI REST, OpenAI Realtime, local whisper.cpp, and a generic ASR sidecar — and types it into the focused window. It is the open-source Wispr Flow alternative for Linux.

Press a hotkey, speak, and your words appear at the cursor in any focused app on Wayland, X11, Hyprland, Sway, Niri, GNOME, or KDE. Audio is captured via cpal across PipeWire, PulseAudio, and ALSA. Fully offline local transcription runs in under 500 MB of RAM with base.en. Fast, private, open source.

How does whisrs differ from Wispr Flow and Superwhisper?

Wispr Flow and Superwhisper are closed-source dictation apps that don't run on Linux. whisrs is open source (MIT), Linux-native, and ships as a single async Rust process with native keyboard layout support (uinput + XKB), window tracking across Hyprland, Sway, Niri, X11, GNOME, and KDE, and 7 swappable transcription backends — both cloud (Groq, Deepgram, OpenAI) and fully offline (whisper.cpp, plus a generic ASR sidecar for arbitrary local models). xhisper proved the concept on Linux; whisrs rebuilds it from scratch in Rust with broader compositor support and a daemon/CLI architecture you can bind to any hotkey.

Installation

Quick install (Linux x86_64 / aarch64)

curl -sSL https://y0sif.github.io/whisrs/install.sh | bash

The install script downloads the latest prebuilt tarball, installs whisrs/whisrsd to /usr/local/bin, and runs interactive setup.

Pin a specific version with WHISRS_VERSION=v0.1.10 or use the cloud-only minimal build with WHISRS_MINIMAL=1. Re-run the same command later to upgrade.

To build from source instead — including custom feature flag combos or unsupported architectures — use cargo install whisrs --locked or the whisrs-git AUR package.

After install, press your hotkey to start recording, press again to stop. Text appears at your cursor.

Pre-built binary (manual)

The Quick install above already does this — this section is for users who want to install the tarball by hand.

Each tagged release publishes tarballs on GitHub Releases with both whisrs and whisrsd plus the contrib files (udev rule, systemd unit, man pages).

# Pick the artifact for your arch + variant:
ARCH=x86_64   # or aarch64
curl -sSL -o whisrs.tar.gz https://github.com/y0sif/whisrs/releases/latest/download/whisrs-linux-${ARCH}.tar.gz

# Or the minimal build (cloud backends only — no whisper.cpp):
# curl -sSL -o whisrs.tar.gz https://github.com/y0sif/whisrs/releases/latest/download/whisrs-linux-${ARCH}-minimal.tar.gz

tar xzf whisrs.tar.gz
sudo install -m755 whisrs whisrsd /usr/local/bin/
sudo install -m644 contrib/99-whisrs.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
sudo usermod -aG input $USER   # log out / back in for the group change
whisrs setup

Arch Linux (AUR)

yay -S whisrs-git

After install, run whisrs setup to configure your backend, API keys, permissions, and keybindings.

Cargo

cargo install whisrs

Requires system dependencies: alsa-lib, libxkbcommon, clang, cmake.

After install, run whisrs setup.

Nix

nix profile install github:y0sif/whisrs

Or add to your flake inputs:

inputs.whisrs.url = "github:y0sif/whisrs";

Manual install

1. Dependencies

# Arch Linux
sudo pacman -S base-devel alsa-lib libxkbcommon clang cmake

# Debian/Ubuntu
sudo apt install build-essential libasound2-dev libxkbcommon-dev libclang-dev cmake

# Fedora
sudo dnf install gcc-c++ alsa-lib-devel libxkbcommon-devel clang-devel cmake

2. Build

git clone https://github.com/y0sif/whisrs
cd whisrs
cargo install --path .

3. Setup

whisrs setup

The interactive setup will walk you through backend selection, API keys / model download, microphone test, uinput permissions, systemd service, and keybindings.

4. Bind a hotkey

Example for Hyprland (~/.config/hypr/hyprland.conf):

bind = $mainMod, W, exec, whisrs toggle

Example for Sway (~/.config/sway/config):

bindsym $mod+w exec whisrs toggle

What transcription backends does whisrs support?

Groq is the default. For fully offline use, run whisrs setup and select Local > whisper.cpp — base.en (142 MB, ~388 MB RAM) is recommended; tiny.en (75 MB) for low-end hardware, small.en (466 MB) for higher accuracy.

For local ASR models without a Rust runtime (Moonshine, NVIDIA Parakeet, Microsoft VibeVoice-ASR), use the generic ASR sidecar backend — it talks to a small local HTTP service that hosts the model. See contrib/asr-sidecars/ for ready-to-run sidecars.

Configuration

Config file: ~/.config/whisrs/config.toml — whisrs setup writes a working file. A minimal example:

[general]
backend = "groq"   # groq | deepgram-streaming | deepgram | openai-realtime | openai | local-whisper | asr-sidecar
language = "en"    # ISO 639-1 or "auto"
overlay = false    # bottom-screen recording overlay

[groq]
api_key = "gsk_..."

Env-var overrides: WHISRS_GROQ_API_KEY, WHISRS_DEEPGRAM_API_KEY, WHISRS_OPENAI_API_KEY.

For the full reference (overlay, [input], [asr-sidecar], [llm], [hotkeys], GNOME extension setup), see docs/configuration.md.

CLI Commands

whisrs setup     # Interactive onboarding
whisrs toggle    # Start/stop recording
whisrs cancel    # Cancel recording, discard audio
whisrs status    # Query daemon state
whisrs restart   # Restart the daemon (uses the systemd user service when present)
whisrs command   # Command mode: select text + speak instruction → LLM rewrite
whisrs log       # Show recent transcription history
whisrs log -n 5  # Show last 5 entries
whisrs log --clear  # Clear all history

Does whisrs work on Wayland, GNOME, KDE, Hyprland, Sway, and Niri?

Yes. whisrs runs natively on both Wayland and X11 across Hyprland, Sway, Niri, i3, GNOME Wayland, KDE Wayland, and any X11 window manager — with daily-driver coverage on Hyprland and community-confirmed reports on GNOME Wayland and Xorg. Audio capture works on PipeWire, PulseAudio, and ALSA via cpal.

Note: whisrs is daily-driven on Hyprland (Arch Linux), with community confirmation on GNOME Wayland (Ubuntu 24.04 + Arch), Xorg (Ubuntu 24.04), and Niri (CachyOS). Sway, i3, and KDE reports are still wanted — if you use whisrs there, please open an issue with what works and what doesn't.

Project Status

whisrs is functional and usable for daily dictation. Streaming transcription, command mode, multi-language support, system tray, OSD overlay, layout-aware injection (incl. AltGr + dead keys), the generic ASR sidecar backend (Moonshine, Parakeet, VibeVoice-ASR), and packaging for AUR / Nix / crates.io all ship today. Native local Vosk and Parakeet backends are next.

Per-release details: docs/version-roadmap.md.

Troubleshooting

See docs/troubleshooting.md.

Contributing

The biggest way to help right now:

1. Test on your compositor — Sway, i3, KDE, GNOME. Report what works and what doesn't.
2. Test on your distro — Ubuntu, Fedora, NixOS, etc. Build issues, missing deps, etc.
3. Bug reports — if text goes to the wrong window, characters get dropped, or audio doesn't capture, open an issue.

See CONTRIBUTING.md for development setup and project structure.

How whisrs Compares to Wispr Flow and Other Dictation Tools

whisrs is the open source alternative to closed-source dictation apps like Wispr Flow and Superwhisper, neither of which ships a Linux client. The closest open-source equivalents include nerd-dictation, Speech Note, and the cross-platform Handy. Head-to-head against the Linux-native options:

For the full comparison, see docs/comparison.md.

FAQ

License

MIT