Guides: install and run

Two ways to install, from a native package or a Git clone, dictation in four languages, and the push-to-talk that drives a session.

Native packages for Debian 12 and 13, Ubuntu 22.04 and 24.04, Fedora 42, openSUSE Leap 15.6 and Arch Linux. There are two installation paths; pick one per machine.

Install from a package

# Debian 12 and 13, Ubuntu 22.04 and 24.04 and their derivatives
sudo apt install ./whispskrid_1.0.1_all.deb

# Fedora 42
sudo dnf install ./whispskrid-1.0.1-1.fc42.noarch.rpm

# openSUSE Leap 15.6
sudo zypper install ./whispskrid-1.0.1-1.leap156.noarch.rpm

# Arch Linux
sudo pacman -U whispskrid-1.0.1-1-any.pkg.tar.zst

The whispskrid command is then on your PATH. On first run it builds a private virtual environment and installs faster-whisper once; the per-user configuration file is created at ~/.config/whispskrid/config.yaml from the shipped template. The Whisper model is not bundled — see Downloads for what the package installs and where the model goes.

Install from a Git checkout

For working on the code, or on a distribution without the package:

git clone https://github.com/RonanDavalan/whispskrid.git
cd whispskrid
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/whispskrid --diagnose

Run it with .venv/bin/whispskrid. The system packages portaudio19-dev, gettext and one injection backend (below) are still required.

Dictation languages

Four languages are supported: English, French, German and Spanish. A single multilingual Whisper model covers all of them — there is no per-language model. The active language is chosen by -l, otherwise the operating system language, otherwise Whisper’s autodetection.

whispskrid -l en

The model lives in ~/.local/share/whispskrid/whisper-models/. The command downloads it and checks that it loads:

whispskrid --download-model base

On the first run with no model, it offers the same download. Available models: tiny, base (default), small, medium, large-v3.

Driving a session

WhispSkrid works push-to-talk: you hold a key, speak, release; the transcribed text is injected into the focused window. There is no automatic cutoff — the only guard is capture.max_seconds (default 300). The default key is the right Shift (shift_r), configurable through hotkeys.push_to_talk.

The local key listener (pynput) only reaches X11 and XWayland windows. Under Wayland, or for a desktop global shortcut, bind these subcommands instead — they are passed to the running session over the control socket:

whispskrid --dictate       # start capture
whispskrid --dictate-stop  # stop, transcribe, inject
whispskrid --toggle        # one or the other, by current state
whispskrid --cancel        # discard the capture in progress

A desktop shortcut does not carry key-hold, so on that path --dictate and --dictate-stop bracket the dictation. Punctuation is not spoken — Whisper punctuates and applies sentence capitals on its own.

whispskrid --diagnose reports the session type, injection backend, audio device, backend and model status, then exits.

Wayland and X11

Text is injected through the clipboard, so it needs both a keystroke engine and a clipboard tool. The engine is probed once at startup: ydotool first (driver level, through the ydotoold daemon), then xdotool, then degraded mode (text left in the terminal, no keystroke sent). The clipboard tool is wl-clipboard under Wayland (always required) and xclip under X11. The native packages pull these in; a source install adds them itself. Without a clipboard tool the paste re-inserts the last thing copied by hand. ydotool, when it is the retained engine, needs the ydotoold daemon and membership of the input group (log out and back in after adding it). The pynput listener reaches X11 and XWayland windows only; on Wayland, bind the subcommands above to your desktop’s own shortcut settings for every window.

Full reference

Every configuration key, the model-path cascade and the control socket are documented in the project’s docs/: configuration.md and the whispskrid(1) manpage, both in the four languages. See Architecture for how the pieces fit together.

In this section

Downloads — Which file to take depending on whether you want to use WhispSkrid or change it, how to check what you received, and what that apt notice means.