Unhush delivers fast, system-wide voice input for Linux.
For the longest time, computer input has been quiet. Just keyboard and mouse. No longer! Unlock the power of your voice with Unhush, for at least 3x faster input.
Unhush provides seamless speech-to-text using AI transcription, allowing you to dictate anywhere and have text delivered instantly. It offers functionality comparable to Wispr Flow (a commercial voice dictation app for Windows and macOS).
- Global Hotkey - Press hotkey to start/stop recording from anywhere
- Flexible Output - Choose how transcribed text is delivered: Paste (default, instant, clipboard-based), Type (character-by-character via ydotool), or Clipboard (copy only, paste manually)
- AI Transcription - Transcribe audio using the OpenAI Whisper model, via Groq, OpenAI, or any compatible local/custom endpoint
- Unlimited Recording Length - Voice Activity Detection (VAD) segments long dictations at natural pauses; each segment is sent to Whisper concurrently, so there is no time limit on recordings
- LLM Formatting Pass - Optional post-processing by an LLM to fix punctuation, remove filler words, and clean up speech artefacts
- Multilingual - Supports 99+ languages with automatic detection
- Minimal UI - Slim, transparent recording bar with real-time audio waveform
- System Tray - Quick access to settings and app controls
- Wayland & X11 Support - Works on both display servers (Wayland may require more setup)
- Privacy First - Records locally before sending to API. Both the transcription and formatting API endpoints can be local for total privacy — see Using Local Models
- Auto-start & Warm-up - Unhush can start local servers automatically on first use and pre-load models into GPU memory to reduce first-request latency
- Attenuate Background Audio - Optionally lowers other apps' volume while recording, so ambient music or notifications don't compete with your voice
- Linux (Debian 10+ / Ubuntu 22.04+ / Fedora 32+ / Arch Linux) with native packages, or anything with AppImage and glibc 2.29+ (which includes Ubuntu 18.04+)
- Microphone access
- Internet connection (for cloud API calls) or a local Whisper server (see below)
As a system package
Download the latest release from the Releases page and install using the applicable command:
sudo apt install ./unhush_*.deb # Debian / Ubuntu / Mint
sudo dnf install ./unhush-*.rpm # Fedora / RHEL
sudo pacman -U unhush-*.pacman # Arch / Manjaro / etcTo verify your download against the SHA256 checksums:
sha256sum -c SHA256SUMS.txt --ignore-missingThe .deb, .rpm, and .pacman packages automatically:
- Install ydotool: as a dependency for
.deband.pacman, but only as a recommended package for.rpm, since not every RPM-based distribution carries it (see Manual Setup if it's missing) - Configure
/dev/uinputaccess (required by ydotool) via a udev rule — no manual steps or re-login needed
Two more tools are optional: pactl (lowers other apps' audio while recording) is recommended; xprop is only suggested.
wl-clipboard is a dependency of the .pacman package, recommended by the .rpm and suggested by the .deb. It is only used under Niri (or any other desktop whose XWayland is xwayland-satellite); see Wayland Setup.
AppImage
Download and run the AppImage, no installation needed (after making it executable with chmod +x unhush-*.AppImage).
Unhush uses ydotool to send transcribed text to the active input field, so is normally required, unless you want to instead manually paste using the clipboard.
AppImage users need to install it (and optionally xprop) themselves. See Manual Setup below for further instructions.
From Source
# Clone the repository
git clone https://github.com/propriaworks/unhush.git
cd unhush
# Install dependencies
pnpm install
# Run in development mode
pnpm run electron:devYou may need to install or set up dependencies as described below.
If you're not using an installer, here's how to set up:
ydotool and the ydotoold daemon
ydotool allows Unhush to write the transcription output to whatever window you are currently using. It is required for Paste (default) and Type output modes. In Clipboard mode, you are responsible for pasting the output where you want it, so ydotool is not needed.
At startup Unhush checks for everything it needs to paste — the ydotool binary, /dev/uinput access, and the ydotoold daemon — and if anything is missing it opens a setup window naming the specific problem, with the commands to fix it and a Re-check button. If you haven't used an installer, this is where you'll be told what to do.
As a first step, install ydotool manually (it's called ydotool in most major packaging systems).
Once ydotool package is installed and your user has permission to write to /dev/uinput, you normally have nothing else to do for the ydotoold daemon to run — Unhush will handle this. ydotool 1.x is only a client: it forwards keystrokes over a unix socket to the ydotoold daemon, which is what actually holds /dev/uinput open. At startup Unhush looks for a daemon it can use and, finding none, starts its own as a child process on a socket private to Unhush ($XDG_RUNTIME_DIR/unhush-ydotool.sock). It exits with the app.
If a ydotoold is already running on ydotool's default socket — because you started one yourself, or enabled Debian's or Arch's ydotool.service — Unhush adopts that one instead of starting a second.
In case of trouble (see Troubleshooting), you may want to use the latest ydotool release.
Keyboard layouts are a reason to prefer 1.x. If you use a layout other than US-QWERTY, and run X11, or Wayland with sway or hyperland, you should use 1.x if you want Type mode output. Paste mode is unaffected on every version, since the text travels through the clipboard instead.
ydotool types by sending key positions from a fixed US-QWERTY table, which your desktop then maps through whatever layout you actually use — so on AZERTY, QWERTZ, Dvorak, a Spanish layout and so on, Type mode produces the wrong characters. On AZERTY, asking for q gives a and 1 gives &; on a Spanish layout ; becomes ñ, and the apostrophe becomes a dead key that swallows the following letter, so it's is typed itś.
With ydotool 1.x, Unhush fixes this automatically: ydotoold keeps one virtual keyboard open for as long as it runs, so Unhush gives that device its own US layout and leaves your real keyboard alone. Nothing to configure. It needs a display server that supports per-device keyboard configuration — currently X11 (any desktop), sway, or Hyprland. Under GNOME or KDE on Wayland there is no such mechanism, and so Type mode only works properly on US-QWERTY.
With ydotool 0.x it cannot be fixed on any desktop: the client opens /dev/uinput for each keystroke and closes it again, so there is no lasting device to configure. If you want to use a non-QWERTY layout with Type mode, upgrade to ydotool 1.x.
Two distro notes:
- Ubuntu 22.04 (and Linux Mint 22) ships ydotool 0.1.8, which predates the client/daemon split and writes
/dev/uinputdirectly. There is no daemon to run (although the 0.1.8 package does still install aydotooldbinary), and it uses key names rather than the keycodes 1.x wants. This version cannot support non-QWERTY layouts, as explained above. - As of now, Fedora's
ydotoolpackage shipsydotool.serviceas a system service. Enabling it does not help: a system service has noXDG_RUNTIME_DIR, so root's ydotoold binds/tmp/.ydotool_socketat mode 0600 owned by root, while your client looks in/run/user/<uid>/and finds nothing. Leave it disabled.
xprop
xprop allows Unhush to identify the destination window where the transcription is being sent, for informational purposes. This is optional, and only useful for X11 sessions. If it's installed, it enables the "sent ➜ <app>" tray indicator (see System Tray). If it's absent, or if we're running Wayland, the tray just won't show a destination
On X11, xprop is usually already installed (it's a base X11 utility). The packages only suggest it, which no package manager installs automatically, so install it manually if missing (also for the AppImage) — x11-utils (Debian/Ubuntu), xprop (Fedora/RHEL/openSUSE), xorg-xprop (Arch)
- Right-click the system tray icon and select Settings
- Choose your transcription provider:
- Groq: Free, fast Whisper models
- OpenAI: Official Whisper API, good if you have a subscription
- Custom: Any OpenAI transcription-API-compatible endpoint (e.g. recommended locally-served for those who can)
- Enter your API key from Groq or OpenAI (optional for custom)
- Optionally configure a Formatting (LLM) provider for post-processing
- On the Usability tab, choose your Output method (default: Paste):
- Paste: Text is pasted instantly via clipboard — works in terminals and GUI apps, atomic, no cursor-move corruption
- Type: Characters typed one-by-one via ydotool — slower, lets you watch text appear as it's written
- Clipboard: Text is copied to clipboard only — paste manually with Ctrl+V; no
ydotoolrequired
- On the Usability tab, choose Unhush's hotkey (
Ctrl+Alt+Spaceby default)
- Press your hotkey or click the systray icon to start recording (bar appears)
- When the chime sounds and the bar turns red, speak into your microphone — there is no time limit
- Press your hotkey or the icon again to stop — a second chime plays and a thinking indicator appears while your speech is transcribed
- Text is delivered to your cursor — pasted instantly by default (see Output mode in Settings)
Unhush records from your system default input device. To use a different microphone, change the default in your desktop's sound settings (GNOME: Settings → Sound → Input; KDE: System Settings → Sound), with pavucontrol (Input Devices → set fallback), or from a terminal:
pactl list sources short # list input devices
pactl set-default-source <name> # set the defaultThe change takes effect on the next recording — no restart needed.
-
Left-click: Toggle recording (same as hotkey-press)
-
Right-click: Open menu (Settings, Copy last transcript, Quit)
-
After a Paste/Type output, the menu shows which app/window received it (e.g. "sent ➜ firefox — some title"), right under "Copy last". This is tray-only and never written to the log file, to preserve privacy. Platform support varies:
Platform Support X11 Works via xprop(see Requirements)Sway / Hyprland Works natively, no extra setup GNOME (Wayland) Requires the Focused Window D-Bus extension — install it if you want this; otherwise no destination is shown, which is expected KDE Plasma (Wayland) Not yet supported — no destination shown (KDE X11 sessions work via the xproppath above) -
A ⚠ badge appears on the tray icon for transcription failures, missing settings (API key, custom URL/model), or repeated LLM warm-up failures. Hover the icon or open the menu for details; each cause clears independently, and the badge itself clears once none remain.
On a Wayland session Unhush runs itself under XWayland. Using native Wayland would interfere with core features, such as being able to write seemlessly to the clipboard, put the recording indicator above other windows and place it at the bottom of the screen. But the use of XWayland should be transparent to users, with one exception: if your primary display uses fractional dpi scaling (like 125%), Unhush may appear slightly blurry.
The global shortcut key still works: on first run Unhush asks the desktop (through the XDG GlobalShortcuts portal over D-Bus) to assign it the shortcut Ctrl+Alt+Space, with your permission (modifiable at that time or later, see below) so as to toggle dictation.
Changing the shortcut on Wayland
The key is controlled by your desktop environment, not Unhush — Unhush can only make a suggestion when it first registers, and after that only your desktop can change it. Settings → Usability shows the key that is live and a Change shortcut… button, which opens your desktop's own shortcut editor focused on Unhush's entry. Add whichever key you prefer there; on KDE at least, you can also untick the default one, so just your own (added) key keeps working.
Two things worth knowing:
- The entry stays in your desktop's shortcut settings after uninstalling Unhush. The portal has no way to remove a binding — delete the Unhush entry by hand if you want it gone.
- If you untick every key for Unhush, the shortcut is registered but can't fire.
Manual Shortcut Key setup
Unhush can make use of the GlobalShortcuts interface implemented by KDE Plasma, GNOME and Hyprland (it can also fully manage it from X11). But the wlroots-based compositors (sway, river, Wayfire) don't have it, so you'll need to bind the key yourself, to:
unhush-toggle
That helper is installed by the deb/rpm/pacman packages. It toggles recording on/off, or, if Unhush isn't running, starts it. On an AppImage or custom build, there's no installer to place the helper, so use the command it wraps instead — Unhush shows the exact line to use in Settings → Usability, and in the setup window on first run.
Where to add it: your compositor's config file (~/.config/sway/config and friends), or the "custom shortcuts" page of whatever settings app your desktop provides.
Niri quirks
On **Niri**, or any desktop whose XWayland is provided by `xwayland-satellite`, Unhush also needs `wl-clipboard` (`wl-copy`/`wl-paste`). There, XWayland's clipboard reaches native Wayland apps only while an XWayland window has focus, so without wl-clipboard, **Paste** mode pastes whatever was copied before into Wayland apps. Unhush detects this setup and, if wl-clipboard is missing, says so in its setup window. AppImage users need to install it themselves.Niri also needs a window rule for the recording bar. Niri manages the bar like any other window. The rule is needed to keep it floating at the bottom of the screen, and to stop it from taking keyboard focus from the app you're dictating into, which would make pasting unreliable. Add this to ~/.config/niri/config.kdl (Niri will reload it automatically):
window-rule {
match title="^Unhush - Voice Input$"
open-floating true
open-focused false
default-floating-position x=0 y=45 relative-to="bottom"
focus-ring { off; }
border { off; }
shadow { off; }
}Unhush checks for this at startup by briefly showing its (empty) recording bar, and shows the rule in its setup window if it's missing.
Unhush listens on a named pipe at $XDG_RUNTIME_DIR/unhush.fifo on every session type, X11 included — this is the method used by unhush-toggle. If you don't have unhush-toggle, you can do it yourself:
printf 'toggle\n' > "$XDG_RUNTIME_DIR/unhush.fifo"This is useful beyond Wayland — it lets you bind a key the Settings dropdown doesn't offer, or start and stop dictation from a script. The pipe is created mode 0600 inside your own runtime directory, and is removed when Unhush exits.
Commands, one per line:
| Command | Effect |
|---|---|
toggle |
Start recording, or stop it and output the transcript |
cancel |
Cancel the dictation in progress. While recording, it is discarded: nothing more is sent for transcription and nothing is output. After recording has stopped, transcription and formatting are abandoned; a transcript that had already finished is still offered by the tray's Copy last |
Unhush has no cancel keyboard shortcut of its own but you can add one by binding a key in your desktop's shortcut settings to:
sh -c 'printf "cancel\n" > "$XDG_RUNTIME_DIR/unhush.fifo"'To have Unhush start up automatically
This can be done in several ways, depending partly upon how you installed:
-
Package install — Settings toggle (recommended): open Settings → Usability and turn on Start at login. The package ships a systemd
--userunit (disabled by default); this just enables it. -
Package install — XDG autostart (works on GNOME, KDE, XFCE, and most DEs):
mkdir -p ~/.config/autostart cp /usr/share/applications/com.propriaworks.unhush.desktop ~/.config/autostart/
-
Desktop Environment settings:
- GNOME: open Settings → Apps → Startup Applications and add Unhush
- KDE Plasma: open System Settings → Autostart and add
/usr/local/bin/unhush - Other: most have an Autostart or Session Startup settings configuration; add Unhush as
/usr/local/bin/unhush
-
AppImage: no installer, so no systemd service is provided — use the Desktop Environment approach (preferred), or write a systemd
--userunit by hand, substituting/path/to/Unhush.AppImageas the command. Service unit notes:--no-sandboxis AppImage-specific: Chromium's sandbox helper needs to be root-owned with the setuid bit, but an AppImage extracts to a FUSE mount owned by you, so the bit can never take effect there.- Keep the default
Type=simplehere — there is only ever one parent process for the app's whole life, on both session types, soExecStart='s process is always the one systemd tracks. --ozone-platform=x11picks XWayland on a Wayland session and is a no-op on X11, so it's safe to include unconditionally. Leaving it off also works — Unhush falls back to re-execing itself in place (same PID) if it's missing, but including it saves time.KillMode=mixed, sendsSIGTERMto only the main process for shutdownRestartSec=5with a relaxed start limit: a unit pulled in bydefault.targetstarts when the login session opens, which can be a few seconds before anything exportsDISPLAY. Unhush exits straight away in that case, and these settings let systemd keep retrying for about two and a half minutes instead of giving up after five tries in ten seconds.
cat > ~/.config/systemd/user/unhush.service << 'EOF' [Unit] Description=Unhush Voice Dictation StartLimitIntervalSec=300 StartLimitBurst=30 [Service] KillMode=mixed ExecStart=/path/to/Unhush.AppImage --no-sandbox --ozone-platform=x11 Restart=on-failure RestartSec=5 [Install] WantedBy=default.target EOF systemctl --user enable --now unhush
| Provider | Model | Cost | Get API Key |
|---|---|---|---|
| Groq | whisper-large-v3-turbo |
Free tier for most, then paid | console.groq.com |
| OpenAI | whisper-1 |
Paid | platform.openai.com |
| Custom | Any OpenAI-compatible transcriptions endpoint | Free if local | — |
For the Custom provider, set the server's base URL (e.g. http://localhost:8000) and the model name as the server expects it. See Using Local Models for setup guides and recommended configuration.
After transcription, Unhush can send the raw transcript to an LLM to clean it up: fixing punctuation, removing filler words ("um", "uh"), and correcting verbal course corrections. The system prompt is fully editable in Settings.
| Provider | Default model | Cost | Notes |
|---|---|---|---|
| Groq | llama-3.3-70b-versatile |
Free tier, then paid | Uses your Groq API key from the transcription tab |
| OpenAI | gpt-4.1-mini |
Paid | Uses your OpenAI API key from the transcription tab |
| Custom | — | Free if local | Default URL: http://localhost:11434 (ollama) |
For the Custom provider, see Using Local Models for setup, model recommendations, and auto-start configuration.
Settings Reference
| Setting | Where | Description |
|---|---|---|
| Provider | Transcription tab | Groq, OpenAI, or Custom |
| API Key | Transcription tab | Provider API key |
| API URL | Transcription tab (Custom) | Server base URL (no /v1/... path — Unhush appends it) |
| Model name | Transcription tab (Custom) | Model identifier as the server expects |
| Start Command | Transcription tab (Custom) | Shell command to launch the server if not running (e.g. speaches serve). Re-run automatically the first time, every 2 minutes while the server stays unreachable, whenever it's gone unreached for a while after being up (see provider_restart_stale_min below), or right after you close Settings having changed a related field. Must be safe to run more than once |
| Warm up model before recording | Transcription tab (Custom) | On (default) or Off. While on, Unhush sends a short silent clip at the start of a recording (at most every warmup_interval_sec) so a server that unloads idle models has it re-loaded by the time you finish. Turn off for hosted APIs, which keep models loaded and bill each request |
| Output | Usability tab | How text is delivered: Paste (default), Type, or Clipboard |
| Shortcut | Usability tab | Global hotkey. On X11 pick it from the list; on Wayland the tab shows the key your desktop holds, with a button to change it |
| Chimes | Usability tab | Play a short chime when recording starts and stops: On (default) or Off |
| Attenuate other audio | Usability tab | Lowers other apps' volume while recording, then ramps back up when you stop: Off, 40%, 60%, or Mute (default 40%). Your own start/stop chimes are never attenuated. Requires PulseAudio or PipeWire (i.e. virtually all Linux desktops) |
| Keep microphone warm | Usability tab | Keeps the microphone open between recordings so the next one starts instantly: On or Off (default). Useful for microphones that are slow to wake from power saving (common with USB webcam mics). While on, your system's microphone-in-use indicator stays lit, though audio isn't processed or saved except while transcribing |
| Formatting provider | Formatting tab | None, Groq, OpenAI, or Custom |
| Language Model | Formatting tab | LLM model name |
| API URL | Formatting tab (Custom) | Server base URL (no /v1/... path — Unhush appends it) |
| API Key | Formatting tab (Custom) | Optional bearer token |
| Start Command | Formatting tab (Custom) | Shell command to launch the LLM server (e.g. ollama serve). Re-run automatically the first time, every 2 minutes while the server stays unreachable, whenever it's gone unreached for a while after being up (see provider_restart_stale_min below), or right after you close Settings having changed a related field. Must be safe to run more than once |
| Warm up model before recording | Formatting tab (Custom) | On (default) or Off. While on, Unhush sends a one-token request at the start of a recording (at most every llm_warmup_interval_sec), and uses the raw transcript until that has succeeded. This insures LLM formatting is available as soon as possible. Turn off for hosted APIs, which keep models loaded and bill each request |
| System Prompt | Formatting tab | Instructions sent to the LLM; editable |
Resetting everything. Settings (including your API keys) live in a Chromium LevelDB store, not
in an editable file, so there's nothing to hand-edit — to wipe them, quit Unhush and run
rm -rf ~/.config/unhush. Uninstalling the package deliberately leaves that directory alone, so
this is also how you purge your data afterwards (also including logs and debug info).
Advanced Settings
These settings are not exposed in the UI. Set them by adding keys to ~/.config/unhush/settings.json (create the file if it doesn't exist). Keys use the setting name without the unhush_ prefix from the code:
{
"debug_audio": "true",
"warmup_interval_sec": "600"
}| Key | Description | Default |
|---|---|---|
debug_audio |
Save each recording's audio segments and transcripts to ~/.config/unhush/debug/ for inspection. Be aware these may build up over time if set to true. |
false |
debug_logging |
Include "debug"-level messages in ~/.config/unhush/logs/unhush.log (normally suppressed, since nothing currently filters log levels otherwise — see Troubleshooting) |
false |
warmup_interval_sec |
Seconds between warm-up requests to the custom transcription server (when its warm-up is on) | 240 |
llm_warmup_interval_sec |
Seconds between warm-up requests to the custom LLM server (when its warm-up is on) | 240 |
provider_restart_stale_min |
Minutes since a custom server (transcription or LLM) was last successfully reached, after which Unhush will re-check it and, if unreachable, re-run its Start Command. Also triggers immediately after editing the Start Command, regardless of this interval | 60 |
llm_keep_alive |
For Ollama LLM servers: how long to request the model be kept loaded in VRAM after each dictation. Accepts Ollama duration strings ("2h", "30m") or seconds as a number; "-1" pins forever; "" disables this feature. Not applied if the server's own keep-alive (OLLAMA_KEEP_ALIVE) is already longer. Has no effect on non-Ollama servers. |
"2h" |
llm_length_multiplier |
Max LLM output length as a multiple of the input length; output exceeding this is discarded and the raw transcript used instead | 1.1 |
llm_excess_length_floor |
Minimum character headroom above input length regardless of multiplier | 20 |
llm_final_instructions |
Instruction appended to the user message sent to the LLM, after the transcript | "Output the cleaned transcript only. No commentary, no explanations, no preamble." |
Settings in this file are loaded at startup and take precedence over any previously saved values.
Unhush logs to ~/.config/unhush/logs/unhush.log. When something goes wrong, check there first.
Text not being typed / ydotool not working
If you're using Paste (default) or Type output mode, Unhush depends on ydotool. Switch to Clipboard mode in Settings to eliminate this dependency entirely (you will need to paste the result yourself).
Unhush diagnoses this itself: it checks the paste path at startup and opens a setup window naming
whatever is broken, with the commands to fix it and a Re-check button. If you dismissed that
window with "Don't show again", delete ~/.config/unhush/.setup-dialog-muted to get it back.
The checks it runs, if you'd rather do them by hand:
-
Test manually:
YDOTOOL_SOCKET=$XDG_RUNTIME_DIR/unhush-ydotool.sock ydotool type "hello"— the word should appear in your terminal -
Ensure ydotool is installed (
.deb/.pacmaninstalls it automatically, and so does.rpmunless your package manager skips recommended packages or your distribution doesn't carry it; AppImage users need to install it manually) -
Ensure the daemon runs. Unhush starts its own
ydotooldand stops it on exit, so check while Unhush is running:ydotool debugexits 0 when it can reach a daemon. See Theydotoolddaemon — in particular, do not expect Fedora's packagedydotool.serviceto help. -
/dev/uinputnot accessible:.deb/.rpm/.pacmaninstalls configure this automatically via a udev rule. AppImage users need to do it themselves:echo 'KERNEL=="uinput", TAG+="uaccess", GROUP="input", MODE="0660", OPTIONS+="static_node=uinput"' \ | sudo tee /etc/udev/rules.d/70-unhush-uinput.rules sudo udevadm control --reload-rules && sudo udevadm trigger --name-match=uinput
If
/dev/uinputdoesn't exist at all, the kernel module isn't loaded —sudo modprobe uinput, andecho uinput | sudo tee /etc/modules-load.d/uinput.confto make it stick across reboots.In case this should fail, you can also explicitly add yourself to the input group:
usermod -aG input <USER>— but note that a running process can't pick up new group membership, so log out and back in afterwards.
Type mode produces the wrong characters on my keyboard layout
Typed output is wrong but plausible — q comes out a, ; comes out ñ, or it's comes out itś — while Paste mode is fine.
ydotool sends key positions, not characters, so what arrives depends on your keyboard layout. Unhush corrects this by giving ydotool's own virtual keyboard a US layout, but that needs ydotool 1.x and X11, sway or Hyprland. See ydotool and the ydotoold daemon for what to do — in short, upgrade to ydotool 1.x, or use Paste mode, which is never affected.
The Settings window says which applies to you: under Type, "Only the QWERTY keyboard layout is supported" means the correction is not available in this session. With debug_logging on, the startup log says so too — look for virtual keyboard: pinned device ... to the us layout.
Text with accents or non-Latin scripts is a separate matter: it can't be typed at all, so it is always pasted instead, whatever your layout.
I'm getting weird characters like 4114 / Unhush isn't using the right `ydotoold`
**If you have more than one ydotool installed** — say your distribution's package in `/usr/bin` plus a newer build in `~/.local/bin` — Unhush picks one deliberately rather than taking whatever `PATH` happens to resolve to. It looks along `PATH` and then in `~/.local/bin`, `/usr/local/bin`, `/usr/bin` and `/bin`, asks each `ydotool` it finds which generation it is, and prefers a complete 1.x install (a `ydotool` with a `ydotoold` in the *same* directory) over a 0.x one; a 0.x install wins only if there is no complete 1.x. Client and daemon are always taken from the same directory, since the two generations cannot talk to each other. The startup log line says which was chosen and what else was found. We need to search beyond `PATH` because at login a `systemd --user` unit often starts before your session's `PATH` reaches systemd. If the wrong version is being used you may need to uninstall one or move the right one to one of these locations. If a v0.x ydotool is errantly sent commands from v1.x, it will produce gibberish. Ensure a consistent version is available in these paths.Global shortcut not working on Wayland
On Wayland the key binding is controlled by your desktop environment, not Unhush. See Wayland Setup.
- Settings → Usability says which mechanism is in play: a key with a Change shortcut… button means your desktop holds the binding; a command with no key means it couldn't, and you have to bind one yourself.
- Check your desktop's shortcut settings for an Unhush entry, and that at least one key for it is ticked — unticking them all leaves it registered but silent.
- If you bound the key yourself, check it runs
unhush-toggle(or, for an AppImage, the command shown in Settings → Usability). - Test the pipe directly:
printf 'toggle\n' > "$XDG_RUNTIME_DIR/unhush.fifo"while Unhush is running should start or stop recording. If that works but your key doesn't, the problem is the desktop shortcut, not Unhush. - If the pipe doesn't exist, check the log for
command fifo listening(~/.config/unhush/logs/).
Microphone access denied
- Grant microphone permission in system settings
- Check if another application has exclusive microphone access
No output or bogus output
- In your system sound settings, ensure that the correct microphone is selected, working, and sensitive enough.
- Sometimes nearly silent input will lead to voice models trying too hard to divine what you said, leading it to output nonsense.
Sometimes text doesn't appear
- If the cursor is not in an active text box, terminal, or other place that can accept text input, the pasted / typed text may be dropped by the target app. In case this happens, you can right click on the system try icon to find out to which window it was sent (where possible -- not all Wayland compositors support this), and copy the transcription text to clipboard yourself so you can paste again where you need it.
My clipboard wasn't put back after a paste
In Paste mode, Unhush puts whatever you had copied back on the clipboard a few seconds after pasting. It deliberately leaves two kinds of copy alone, so the transcript stays on the clipboard instead:
- passwords copied from a password manager, which Unhush doesn't read;
- copied files, which can't be put back exactly (e.g. a cut could come back as a copy).
It also skips the restore if you copy something else in the meantime. Also, due to a limitation of wl-paste, on Niri (xwayland-satellite), rich text such as formatted text from a browser will come back as plain text.
Pasting into a remote desktop or virtual machine pastes old text
If the window you dictate into is a remote-desktop client or a virtual-machine viewer, Paste mode may paste whatever was on the other machine's clipboard before, not your transcript.
Why: the other machine has its own clipboard, which the viewer keeps in step with yours.
- Unhush puts the transcript on your clipboard and presses the paste key a moment later.
- The key reaches the other machine straight away, but the clipboard may not have been copied across yet.
- Some viewers copy your clipboard across only when their window gains focus or takes the keyboard back, however long you wait. NoMachine is one example: a transcript copied while you are already working in its window isn't sent until you switch away and back.
Workaround: use Clipboard mode. Once the transcript is on your clipboard, click out of the viewer window and back in, then paste by hand.
Type mode avoids the clipboard, so might also work. But many viewers (NoMachine, for one) send key positions, which the other machine reads through its own keyboard layout. In that case, typed text is right only if the other machine uses a US layout.
- Unhush's own layout correction (see Type mode produces the wrong characters) applies to your machine only.
- Text with accents or non-Latin scripts is pasted even in Type mode, so it runs into the clipboard problem above.
Keyboard grab: if the viewer grabs the keyboard (a remote-desktop client's keyboard-grab option, a virtual machine's keyboard capture), every key goes to it while it has focus, so Unhush's shortcut doesn't fire. Either:
- start and stop recording from the tray icon, or
- release the keyboard with the viewer's release key, then use Unhush's shortcut.
Recording is slow to start (sometimes)
The chime and red bar appear only once the microphone is actually delivering audio, so a slow start means the device itself is slow to wake. Most systems suspend an idle microphone a few seconds after its last use, and USB mics (especially webcams) may then also be put into USB power saving — waking one can take a second or more. You'd notice that starts are instant when recordings are very close together but slower after a pause.
-
Enable Keep microphone warm on the Usability tab: Unhush holds the microphone open between recordings so it never gets suspended. Your system's microphone-in-use indicator will stay lit.
-
Each start is timed in the log (
Recording start: mic=…ms, …in~/.config/unhush/logs/unhush.log); themic=stage is the device wake. -
Alternatively (advanced), you can prevent the kernel from USB-suspending a specific microphone. Find its vendor/product ID with
lsusb(e.g.ID 046d:0825for a Logitech C270), then install a udev rule with your IDs substituted:echo 'ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="046d", ATTR{idProduct}=="0825", ATTR{power/control}="on"' \ | sudo tee /etc/udev/rules.d/50-mic-no-autosuspend.rules sudo udevadm control --reload-rules
Then unplug and replug the device (or reboot). This disables USB power saving for that one device only; the extra idle draw of a microphone is negligible. See the Arch wiki on USB autosuspend for background.
Transcription errors
When transcription fails, Unhush plays a buzzer sound, displays the error message in the recording pill for ~3.5 seconds, then dismisses. Nothing is typed. The tray icon also shows a ⚠ badge until a transcription succeeds again. Common messages:
| Message | Likely cause |
|---|---|
Transcription server unreachable |
Custom (Whisper) STT server is down, its URL is wrong, or there's no network connection. For a local server, set a Start Command in Settings, or start it manually |
Network error |
No internet connection (Groq/OpenAI), or blocked by IP address |
Bad API key |
API key is missing or invalid — check Settings |
Rate limited |
Hit the provider's rate limit — wait a moment and retry |
Bad endpoint URL |
Custom URL is wrong — it should be just the server's base URL, e.g. http://localhost:8000 (no /v1/... path) |
Transcription server error |
Server returned 5xx — check the server's own logs |
Custom server: health check, warm-up, or slow first transcription
LLM formatting not working
- Ensure the Formatting provider is set (not "Off") in the Formatting tab
- For Custom: verify the API URL is the server's base URL (not a full endpoint path) and the model name is correct
- Check
~/.config/unhush/logs/unhush.logforLLM post-processing failederrors - The raw transcript is used as fallback if the LLM call fails, so dictation still works
- For Custom: if the tray icon shows a ⚠ badge, the formatter's warm-up has failed on two dictations in a row — check that the server is running and reachable at the configured API URL
Diagnosing transcription quality or pipeline issues
Enable debug audio to capture each recording session in detail:
// ~/.config/unhush/settings.json
{ "debug_audio": "true" }Then after each recording, Unhush writes to ~/.config/unhush/debug/<timestamp>/:
| File | Contents |
|---|---|
full-recording.wav |
Complete raw audio for the session |
segment-NNN.wav |
Individual VAD-segmented audio chunks sent to Whisper |
transcript.txt |
Per-segment transcription with timing and latency |
llm-pass.json |
LLM formatting input/output, status, and latency (if LLM enabled) |
This is actively maintained; your contributions and feedback are most welcome.
A diagram of the recording, processing, chunking, postprocessing pipeline workflow is available here.
Some aspects of Wayland and many Linux distributions have not been tested directly. Please share your experiences in the discussions.
Most Wayland testing has been on KDE. Your experience with GNOME and Hyprland on Wayland is particularly interesting, especially whether the shortcut registers through their portals as it does on KDE (the manual unhush-toggle command works regardless), and the paste-destination tray indicator on Sway, Hyprland, and GNOME Wayland with the Focused Window D-Bus extension installed. KDE Plasma Wayland support for that indicator isn't implemented yet.
Developer notes
Run pnpm install to install dependencies, or update them based upon a changed package.json (changes to lockfile are limited to what's needed to match package.json). pnpm update will also change the package.json, bumping versions to the newest matching versions (subject to minimum age from the workspace file). pnpm up --latest -i updates dependencies in packages.json to their latest major versions, ignoring prior version constraints; do rarely, in interactive mode to avoid disruptive upgrades and aptknow what needs to be tested/changed.
Before committing check typescript with pnpm tsc and run tests with pnpm test.
To try the app against a slow custom server (cancelling, the "loading model" hint, timeout retries), put scripts/slow-proxy.py between Unhush and the server: it holds real transcription and formatting requests for a set time, passes health checks and warm-ups straight through, and reports when the app aborts a held request. Usage is in its header.
Updating after incorporating PRs to packages.json from dependabot will often will fix issues here. If the flagged package is transitive (e.g. esbuild, pulled in by vite), bumping the top-level package won't help. Instead: pnpm why <package> to find what requires it. Usually you can update just that package with pnpm up [--latest] <pkg> to fix it. Worst case, one can then pnpm add -D <package>@<fixed-version> to pin it directly, though this isn't ideal, as it will need to be maintained and will later not match. Then pnpm why <package> again to confirm it deduped to one version. Sometimes pnpm dedupe, which re-resolves shared transitive dependencies to the highest commonly acceptable version, is needed too.
Cross-format building is supported with native system tools:
| Host | Extra setup | Builds |
|---|---|---|
| Ubuntu / Debian | sudo apt install rpm fakeroot |
AppImage, .deb, .rpm |
| Fedora / RHEL | sudo dnf install dpkg fakeroot |
AppImage, .deb, .rpm |
| Arch Linux | (none — base-devel sufficient) | AppImage, .pacman |
# Production
pnpm run build # Build React app
pnpm run package # Create distributables for all targets supported on this hostThe .pacman package is built in CI using an Arch Linux container and is not cross-buildable from other distributions.
Merge PR into main. Then from the main branch, pull and update version in package.json, update download links with node scripts/sync-docs.mjs, and add the modified files. Finally commit, tag it, and push the commit along with the tag:
git commit -m "bump version"
git tag v3.1.1 && git push origin main v3.1.1CI will be launched by github to build it, save release builds and update docs/index.html with version correct download links (if not already done). To test the CI, open a draft PR or do Actions -> CI -> Run workflow, and pick a branch (to rebuild a release, pick the tag instead).
Screen recording created using byzanz cli.
MIT License - see LICENSE file for details
Unhush was based upon a predecessor of wisper, but is now independently maintained.
- Improved usability, configuration, and consistency
- Enhanced logging and error visibility+handling
- Support for custom/local models, including startup and warmup
- Support for unlimited dictation time (overcoming Whisper-model limitation)
- Added LLM-based post-processing
- Seamless installation and Wayland support
- Justin Briggs - @jtbr — Current maintainer
- Tarak Shaw - @taraksh01 — Original creator; implemented core architecture and visualizations