whispers

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

Install · Quick start · Docs · 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: bind whispers to a key, press once to start recording, press again to stop, transcribe, and paste into the focused Wayland 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

For the full package matrix, prerequisites, and post-install notes, see docs/install.md.

Arch Linux (paru)

paru -S whispers-bin
# or: whispers-git / whispers-cuda-bin / whispers-cuda-git

Cargo

cargo install whispers

cargo install whispers follows crates.io releases. The AUR *-bin packages follow published GitHub release bundles, and *-git packages track the repository main branch. If you need rewrite or CUDA features, or want install details before choosing a package, use docs/install.md.

Quick start

# generate config and download a model
whispers setup

# start dictation (run again to stop, transcribe, and paste)
whispers

Default config path:

~/.config/whispers/config.toml

Example compositor bindings:

Hyprland:

bind = SUPER ALT, D, exec, whispers

Sway:

bindsym $mod+Alt+d exec whispers

Docs

• Installation guide — package choices, prerequisites, config path, and feature notes.
• CLI guide — command groups, examples, and newer rewrite-policy commands.
• Troubleshooting — wl-copy, /dev/uinput, cloud checks, and hang diagnostics.
• Contributor workflow — install the local pre-push hook and mirror CI before opening a PR.
• config.example.toml — the canonical config template.

Troubleshooting

If /dev/uinput is blocked, run whispers setup and let it configure the dedicated uinput group and udev rule for you. If the main dictation process hangs around local whisper_cpp transcription, enable hang diagnostics for the next repro:

WHISPERS_HANG_DEBUG=1 whispers

For the full troubleshooting guide, including the emitted main-status.json and hang-*.log files, see docs/troubleshooting.md.

Releases

Tagged releases publish portable and CUDA-enabled Linux x86_64 bundles. The AUR whispers-bin and whispers-cuda-bin packages install those published release artifacts.

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.