whispers

Fast local-first speech-to-text dictation for Wayland.
Press a key, speak, transcribe, and paste.

Install · Quick start · Commands · Troubleshooting · Releases

whispers keeps the default dictation path local, with optional cloud ASR and rewrite backends when you want them. The normal loop is simple: start recording with a keybinding, stop recording, and paste the transcript directly into the focused app.

What it does

• Local-first speech-to-text for Wayland desktops.
• Optional local rewrite cleanup with a dedicated rewrite worker.
• Optional cloud ASR and rewrite backends when you want to trade locality for convenience.
• Model download, selection, and config management from the CLI.
• Wayland-native OSD support for a cleaner live dictation experience.

Install

Arch Linux (paru)

CUDA-enabled

# prebuilt GitHub release bundle with CUDA support
paru -S whispers-cuda-bin

# latest main branch build with CUDA support
paru -S whispers-cuda-git

Use these when you want the CUDA-enabled local path from the AUR.

Portable / non-CUDA

# prebuilt GitHub release bundle
paru -S whispers-bin

# latest main branch build
paru -S whispers-git

• whispers-cuda-bin installs the published Linux x86_64 CUDA bundle.
• whispers-cuda-git builds the latest main branch with cuda,local-rewrite,osd.
• whispers-bin installs the published portable non-CUDA Linux x86_64 bundle.
• whispers-git builds the latest main branch with the portable local-rewrite,osd feature set.

Cargo

# crates.io with the default OSD-enabled install
cargo install whispers

# add local rewrite support
cargo install whispers --features local-rewrite

# add CUDA + local rewrite
cargo install whispers --features cuda,local-rewrite

# no OSD
cargo install whispers --no-default-features

If you want the latest GitHub version instead of crates.io:

cargo install --git https://github.com/OneNoted/whispers --features local-rewrite

Requirements

• Linux with Wayland
• wl-copy
• access to /dev/uinput
• Rust 1.85+
• CUDA toolkit if you enable the cuda feature

If /dev/uinput is blocked, add your user to the input group and log back in:

sudo usermod -aG input "$USER"

Quick start

# generate config and download a model
whispers setup

# one-shot dictation
whispers

Default config path:

~/.config/whispers/config.toml

Canonical example config:

• config.example.toml

Keybinding

Hyprland:

bind = SUPER ALT, D, exec, whispers

Sway:

bindsym $mod+Alt+d exec whispers

Commands

# setup
whispers setup

# one-shot dictation
whispers
whispers transcribe audio.wav

# ASR models
whispers asr-model list
whispers asr-model download large-v3-turbo
whispers asr-model select large-v3-turbo

# rewrite models
whispers rewrite-model list
whispers rewrite-model download qwen-3.5-4b-q4_k_m
whispers rewrite-model select qwen-3.5-4b-q4_k_m

# personalization
whispers dictionary add "wisper flow" "Wispr Flow"
whispers snippets add signature "Best regards,\nNotes"

# cloud
whispers cloud check

# shell completions
whispers completions zsh

Notes

• Local ASR is the default path.
• Local rewrite is enabled when you install with --features local-rewrite or use the current AUR packages.
• whispers installs the helper rewrite worker for you when that feature is enabled.
• Shell completions are printed to stdout.

Troubleshooting

If the main whispers process ever gets stuck after playback when using local whisper_cpp, enable the built-in hang diagnostics for the next repro:

WHISPERS_HANG_DEBUG=1 whispers

When that mode is enabled, whispers writes runtime status and hang bundles under ${XDG_RUNTIME_DIR:-/tmp}/whispers/:

• main-status.json shows the current dictation stage and recent stage metadata.
• hang-<pid>-<stage>-<timestamp>.log is emitted if whisper_cpp spends too long in model load or transcription.

Those bundles include the current status snapshot plus best-effort stack and open-file diagnostics. If the hang reproduces, capture the newest hang-*.log file along with main-status.json.

Releases

Tagged releases publish a Linux x86_64 bundle with:

• a portable whispers-<version>-x86_64-unknown-linux-gnu.tar.gz
• a CUDA-enabled whispers-cuda-<version>-x86_64-unknown-linux-gnu.tar.gz
• whispers, whispers-osd, and whispers-rewrite-worker
• Bash, Zsh, and Fish completions
• README.md, config.example.toml, LICENSE, and NOTICE

Those bundles are what the whispers-bin and whispers-cuda-bin AUR packages install.

License

Project code in this repository is licensed under the MIT License.

Bundled third-party code under vendor/whisper-rs-sys carries upstream license notices and file-level exceptions. See NOTICE, the vendor license files, and the relevant per-file headers under vendor/whisper-rs-sys/whisper.cpp.