whisper-desk

Offline voice dictation for Linux, WSL and macOS. You press Super + J, a small overlay appears — a microphone and an equalizer dancing to your voice — and the text is typed straight where your cursor is, sentence after sentence, while you speak.

Each bar tracks a frequency band, from lows on the left to highs on the right: you see the voice, not just its volume. The scale is in decibels and the fall is slower than the rise, like a VU meter — silence leaves the bars at rest, an ordinary voice sits in the middle of the range.

The overlay says at every moment what whisper-desk is doing, without opening a terminal:

State	What you see
loading	the model is being loaded or downloaded — the equalizer turns into a gauge, with the percentage
listening	the equalizer follows your voice; below it, how to finish (Super+J) and to cancel (Esc or a click)
live text	in streaming mode, the sentence just transcribed appears under the equalizer, cut on the left
working	the last sentence is being transcribed
done	a tick and the beginning of the text inserted, for about a second
error	a short, readable reason — microphone unavailable or silent, nothing heard, text that could not be inserted — and what to do
cancelled	the dictation was cut off: nothing more is inserted

It fades in and out — unless animations are turned off on your desktop — and follows the accent colour of the configuration.

No data leaves the machine: transcription runs on your GPU (or your CPU) with faster-whisper.

📖 The documentation, online — the same text, but you can watch it work: a demo that dictates itself, the equalizer in motion, and every table on a page that is pleasant to read.

---

Installation

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

That's all. The script recognises the host — Linux, WSL or macOS — and adapts every step:

1. checks the system dependencies (microphone, clipboard, notifications, GTK) and offers to install them, with apt or brew as appropriate;
2. creates an isolated Python environment and installs faster-whisper in it — plus the CUDA libraries if an NVIDIA card is detected;
3. installs the whisper-desk command in ~/.local/bin;
4. enables the user service — systemd on Linux and WSL, launchd on macOS — started automatically at login;
5. registers the global shortcut with the host's shortcut manager;
6. adds Settings and History to the applications menu, and the tray icon to the programs started at login (Linux);
7. on a first installation, opens the welcome window.

The Whisper model (a few hundred MB) is downloaded the first time the service starts. A dictation started before it has arrived shows the download on the overlay, and the microphone only opens once the model is ready.

First launch

The welcome window walks through four steps: the microphone, with a gauge that must move when you speak; the language and the model; the download, with its progress; then your shortcut, and a first dictation into a text box. It opens once, after the first installation (WD_NO_WELCOME=1 skips it); whisper-desk welcome opens it again.

Once installed, updates go through the command itself: whisper-desk update.

What each host uses

	Linux	WSL	macOS
microphone capture	arecord (ALSA)	parec (PulseAudio/WSLg)	rec (sox) or ffmpeg
clipboard	wl-copy / xclip	clip.exe	pbcopy
paste keystroke	/dev/uinput, else GNOME remote desktop (Mutter)	SendKeys (PowerShell)	System Events (osascript)
global shortcut	GNOME (gsettings)	Start menu shortcut	skhd, or by hand
service	systemd	systemd, otherwise on demand	launchd
notifications	notify-send	notify-send (WSLg)	osascript

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

Requirements — a microphone, and depending on the host:

• Linux: GNOME (Wayland or X11), systemd in the user session.
• WSL: WSL 2 with WSLg (Windows 11, or an up-to-date Windows 10) for the microphone, and Windows interoperability enabled. Text is inserted into Windows windows.
• macOS: 12 or newer. The first paste asks for accessibility permission (System Settings → Privacy & Security → Accessibility), and the first dictation asks for microphone permission.

An NVIDIA GPU is a bonus, not a requirement; on macOS transcription runs on the CPU, since CTranslate2 does not use Metal.

Check that everything is in place

whisper-desk doctor

Each line is ✓ (fine), ✗ (to fix) or ⚠ (optional: whisper-desk works without), and every failure comes with the line that fixes it:

System — Linux
  ✓ microphone capture — arecord, ffmpeg
  ✗ the microphone picks up sound ('default') — average level 0, peak 0
      → check the default source: wpctl status — or pick another one in whisper-desk settings
  ✓ clipboard — wl-copy
  ⚠ tray indicator — GNOME shows no tray icon without an extension
      → install and enable gnome-shell-extension-appindicator — meanwhile, Settings and History are in the applications menu

1 problem to fix — the → lines above say how.

---

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.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗