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.

Check that everything is in place

$ whisper-desk doctor

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

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.

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 config     # open the configuration in $EDITOR
$ whisper-desk reload     # reload the configuration without restarting
$ whisper-desk quit       # stop the daemon

[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)

[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               # log in ~/.local/state/whisper-desk/history.log

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

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.