whisper‑desk.

$ curl -LsSf https://raw.githubusercontent.com/SalvadorCardona/whisper-desk/main/install.sh | sh

The script recognises the host — Linux, WSL or macOS — and adapts every step:

1. it checks the system dependencies (microphone, clipboard, notifications, GTK) and offers to install them, with apt or brew as appropriate;
2. it creates an isolated Python environment and installs faster-whisper in it — plus the CUDA libraries if an NVIDIA card is detected;
3. it installs the whisper-desk command in ~/.local/bin;
4. it enables the user service — systemd on Linux and WSL, launchd on macOS — started at login;
5. it registers the global shortcut with the host’s shortcut manager.

First launch

A first installation ends on the welcome window: the microphone with a gauge that must move, the language and the model, the download with its progress, then your shortcut and a first dictation. whisper-desk welcome opens it again; WD_NO_WELCOME=1 skips it.

1 — the microphone

2 — language and model

3 — the download, with its progress

4 — your shortcut, a first dictation

Check that everything is in place

$ whisper-desk doctor

Every line is ✓ (fine), ✗ (to fix) or ⚠ (optional), and every failure comes with the command or the setting that fixes it.

Updating

$ whisper-desk update

It says which version runs and what is available upstream, and stops there if there is nothing new. Otherwise it fetches the sources, brings the Python environment up to date, rewrites the command and the service, restarts the daemon, and hands back a summary of what changed. Your configuration is kept, and so is your keyboard shortcut — a binding you have made your own is never rewritten. A dictation under way is never cut off: the update refuses to run and asks you to come back once it is over.

$ whisper-desk update --check     # compares the versions and writes nothing

--check prints one line and exits 0 if the machine is up to date, 1 if something newer exists upstream, and 2 if the question could not be answered (offline, private repository, nonexistent branch) — enough to hang it on a cron or a status bar. whisper-desk --version and the doctor both name the commit installed: the project is distributed by main, where the commit says more than the version number.

What each host uses

None of these choices are set in stone: backend, keyboard and paste_shortcut can be forced in the configuration.

Requirements

Uninstalling

$ curl -LsSf https://raw.githubusercontent.com/SalvadorCardona/whisper-desk/main/uninstall.sh | sh

The menu entries and the tray icon go with it. Add WD_PURGE=1 to remove the configuration and the history as well. Downloaded models stay in ~/.cache/huggingface.

The default shortcut follows the host: Super + J on Linux and macOS (Cmd + J), Ctrl + Alt + J on WSL — Windows reserves the Windows key for itself.

Correcting yourself as you speak

Change your mind mid-sentence and say so: “On se voit mardi, non, plutôt mercredi” is written On se voit mercredi., “Let’s meet at 2, actually 3” is written Let’s meet at 3. Local rules, no language model: corrections = false turns them off.

Hesitations left out

The euh, hum and um Whisper writes down and the words you stumble over stay out of the text: “Je je pense, euh, qu’on devrait livrer” is written Je pense qu’on devrait livrer, “We could, we could meet” is written We could meet. Nous nous voyons or had had stay as they are. hesitations = false keeps everything.

Snippets

Save the texts you keep retyping under a cue, in the [snippets] section of config.toml: say “Tu peux m’envoyer le colis à mon adresse perso” and Tu peux m’envoyer le colis à 12 rue des Lilas, 75011 Paris. is typed. Alone or inside a sentence, whatever the case or punctuation Whisper gives the cue; the longest cue wins. Applied on your machine, after the transcription.

From the command line

$ whisper-desk record     # dictate and write the text to standard output
$ whisper-desk toggle     # same as the keyboard shortcut
$ whisper-desk status     # daemon state, loaded model, GPU or CPU
$ whisper-desk doctor     # full diagnostic
$ whisper-desk update     # update the installation (--check to compare only)
$ whisper-desk history    # past dictations — see below
$ whisper-desk settings   # the settings window
$ whisper-desk welcome    # the first-launch window, again
$ whisper-desk tray       # the tray icon
$ whisper-desk pause      # the shortcut is ignored until whisper-desk resume
$ whisper-desk config     # open the configuration in $EDITOR
$ whisper-desk reload     # reload the configuration without restarting
$ whisper-desk quit       # stop the daemon

Tray icon

The icon says whether the service runs, with which model and which microphone, and holds a menu: start or finish a dictation, History…, Settings…, Pause dictation, Quit. It needs gir1.2-ayatanaappindicator3-0.1 for the system Python. GNOME shows no tray icon by itself: without the AppIndicator extension (gnome-shell-extension-appindicator, on by default on Ubuntu) the icon has nowhere to go, and whisper-desk doctor says so. Settings and History are then in the applications menu.

History

Every dictation is kept — date, listening time, model and text — in ~/.local/state/whisper-desk/history.jsonl. A text lost on the way can be found again, copied or typed again at the cursor. The history.log of earlier versions is still read.

$ whisper-desk history                  # the 20 latest, numbered from 1 (the latest)
$ whisper-desk history invoice friday   # search: every word, case and accents ignored
$ whisper-desk history --copy 3         # copies dictation 3 to the clipboard
$ whisper-desk history --delete 3       # deletes it
$ whisper-desk history --keep-days 30   # deletes dictations older than 30 days, from now on
$ whisper-desk history --window         # the history window

Search, Copy, Insert again where the cursor was, delete — and the automatic purge

$ whisper-desk settings

Language, model (with its size, its speed and whether it is already downloaded), microphone with a test gauge, shortcut captured from the keyboard, output mode, vocabulary, overlay position and colour. Save writes only what changed — your comments are kept — and reloads the daemon.

The settings window — no TOML to edit

The file holds everything else:

[hotkey]
binding = "auto"              # "auto", or <Ctrl>/<Alt>/<Shift>/<Super> + a key

[model]
name = "auto"                 # auto | tiny | base | small | medium | large-v3 | large-v3-turbo
device = "auto"               # auto | cuda | cpu
language = "fr"               # ISO code, or "auto" for detection
initial_prompt = ""           # vocabulary to favour (proper nouns, jargon)
corrections = true            # "mardi, non, plutôt mercredi" is written "mercredi"
hesitations = true            # "euh", "um" and stuttered words left out

[recording]
backend = "auto"              # auto | arecord | parec | rec | sox | ffmpeg
streaming = true              # insertion as you go, sentence by sentence
segment_silence_seconds = 0.6 # pause that splits a sentence
silence_seconds = 2.0         # silence that ends the dictation
max_seconds = 120

[output]
mode = "cursor"               # cursor | clipboard | stdout — combinable: "cursor+stdout"
paste_shortcut = "auto"       # "shift+insert" if you mostly dictate in a terminal
keyboard = "auto"             # auto | uinput | windows | applescript | none
restore_clipboard = true      # hands your original clipboard back at the end
notify = false
history = true               # keeps every dictation: whisper-desk history
history_days = 0             # dictations older than this are deleted; 0 = kept forever

[overlay]
enabled = true
accent = "#e46212"
position = "bottom-center"    # bottom-center | top-center | center
margin = 96

[snippets]
"mon adresse perso" = "12 rue des Lilas, 75011 Paris"   # cue said -> text typed

After a change:

$ whisper-desk reload            # for everything but the shortcut
$ whisper-desk hotkey install    # to apply a new shortcut

Choosing a model

To shorten the delay between the end of a sentence and its insertion even further, lower beam_size to 1 in [model].

Super + J  ─→  whisper-desk toggle  ─→  Unix socket  ─→  daemon (model in memory)
                                                              │
                              X11 overlay ←── audio level ─────┤
                                                              │
 mic capture ─→ silence detection ─→ sentence ─→ faster-whisper ─→ text
                                                              │
                          clipboard + Ctrl+V (simulated keystroke) ─→ cursor

The daemon keeps the model loaded at all times, and transcribes one sentence while the microphone is already recording the next. Only the two ends of that chain — capture and keystroke — change from one host to another; the rest is shared.

The two other hosts follow the same idea with their own tools: on WSL, the keystroke goes to Windows through SendKeys (a Linux virtual keyboard would only reach WSLg windows); on macOS, it goes through System Events, which is what earns the program the accessibility permission prompt.

The code, module by module

Development

$ git clone https://github.com/SalvadorCardona/whisper-desk
$ cd whisper-desk
$ WD_SRC="$PWD" sh install.sh     # installs from the local clone, without network access

The test suite depends on the standard library alone — no virtual environment, no model to download. The WD_HOST variable (linux, wsl, macos) forces the detection, which makes it possible to test all three hosts from any of them.

$ python3 -m unittest discover -s tests -t .

$ whisper-desk status                      # is the daemon answering?
$ whisper-desk hotkey show                 # is the shortcut registered?
$ journalctl --user -u whisper-desk -f     # the logs (systemd)
$ tail -f ~/.local/state/whisper-desk/daemon.log   # the logs (launchd)

$ whisper-desk doctor          # "the microphone picks up sound" must be ticked
$ wpctl status                 # lists the sources; spot the real microphone
$ wpctl set-default <id>       # switch to it

The cases specific to WSL and macOS (no sound captured, the shortcut without skhd, microphone gain…) are detailed in the repository README.