Paste and clipboard
hyprwhspr copies dictated text to the clipboard, sends a paste shortcut, then restores your clipboard. Wayland uses wl-clipboard; Hyprland prefers its native shortcut dispatcher, while other Wayland sessions prefer wtype, with ydotool key as a fallback. Sway XWayland apps use ydotool, then xdotool. X11 uses python-pyperclip with xclip, and xdotool/xprop for focused-window and terminal detection. xsel is also accepted as a clipboard fallback when installed. Most setups need no configuration. GNOME/Mutter and KDE Plasma need the AT-SPI bridge for window detection — see GNOME and KDE.
Paste mode
Section titled “Paste mode”The paste shortcut is auto-detected from the focused window:
- Terminals (Ghostty, Kitty, WezTerm, Alacritty, foot, …) → Ctrl+Shift+V
- Everything else (editors, browsers, chat apps) → Ctrl+V
Override with paste_mode if needed:
{ "paste_mode": "ctrl_shift" // "ctrl_shift" (terminal paste) | "ctrl" (GUI paste) | "super" | "alt"}The default is null, which auto-detects the appropriate paste chord from the
focused application. The legacy shift_paste setting also accepts null for
the same auto-detection behavior.
App-specific paste keys
Section titled “App-specific paste keys”Some apps use non-standard paste shortcuts — GUI Emacs, for example, uses Ctrl+Y while Ctrl+V scrolls. Set per-app behavior with applications, keyed by window identifier:
{ "applications": { "emacs": { "auto_paste": "ctrl+y" }, // custom paste chord "some-app": { "auto_paste": false } // disable: nothing pasted, clipboard untouched }}Run hyprwhspr config focused-window to see the identifiers for the active window. Run straight from a terminal it just reports the terminal, so add a delay and focus the target window before it fires — the output still lands in your terminal:
sleep 3; hyprwhspr config focused-window # then click into the app you wantPrefer stable app classes over window titles, which change with the open document.
not detected means no identifier is available, so applications rules can’t match — the command says why and what to do about it.
Terminal Emacs (
emacs -nw,emacsclient -t): hyprwhspr sees the terminal, not Emacs, so terminal paste (Ctrl+Shift+V) is normally correct.
Hyprland NumLock workaround
Section titled “Hyprland NumLock workaround”If pasting makes the focused app treat NumLock as off, try the optional ydotool backend for issue #283:
{ "hyprland_paste_backend": "ydotool"}This sends paste shortcuts and auto-submit Enter through ydotool exclusively.
The default, "auto", keeps Hyprland’s native shortcut dispatcher and its existing
fallbacks. The setting is ignored outside Hyprland. Restart hyprwhspr after changing
configuration; set it back to "auto" to revert. Invalid values warn and use "auto".
Both ydotool and ydotoold must be installed, with access to /dev/uinput as
configured by setup. hyprwhspr starts its own private daemon lazily, so the first
paste can take a few extra seconds. See ydotool troubleshooting.
If ydotool reports a paste failure, hyprwhspr reports failed delivery, leaves the
text on the clipboard, and skips both fallback and auto-submit. In live typing,
the clipboard may contain only the failed chunk; use hyprwhspr record copy-last
to recover the retained dictation. A failed auto-submit Enter is logged without
retrying the paste or Enter.
This is a workaround, not a keyboard-state repair. Test NumLock and CapsLock in your target apps, including the first paste after starting hyprwhspr. ydotool sends physical keycodes: non-QWERTY layouts and modifier remaps may require the overrides below. Non-Latin layouts are not automatically switched on Hyprland. A successful command cannot guarantee that the focused app accepted the shortcut.
COSMIC paste compatibility
Section titled “COSMIC paste compatibility”wtype chords with modifiers start with an Insert release, so COSMIC keeps the modifiers (#288). Applies everywhere, needs no config. Apps that track key releases may see it.
Non-QWERTY layouts
Section titled “Non-QWERTY layouts”ydotool sends physical Linux keycodes, so Ctrl+KEY_V may not be Ctrl+v on layouts like bepo or dvorak. To fix on Wayland: run wev, press the key that types v, and copy the printed keycode into paste_keycode_wev:
{ "paste_keycode_wev": 55 // `wev` keycode for the key that types 'v' on your layout}If you already know the Linux evdev keycode, set paste_keycode directly. Non-Latin layouts (Thai, Russian, Arabic, …) are a special case handled on GNOME/Mutter — see GNOME and KDE.
Remapped modifier keys
Section titled “Remapped modifier keys”ydotool sends physical keycodes, so desktop-level remaps can change the
generated paste shortcut. For example, with Ctrl and Caps Lock swapped:
{ "ydotool_modifier_overrides": { "ctrl": "capslock" }}Supported modifiers are ctrl, shift, alt, and super. Key names are
case-insensitive and may include the KEY_ prefix; Linux evdev keycodes are
also accepted. The usual control, meta, cmd, and logo aliases work here
as they do in paste chords. This setting affects ydotool, whether selected
explicitly or used as a fallback.
Auto-submit
Section titled “Auto-submit”Automatically press Enter after pasting — aka Dictation YOLO. Handy for chat boxes and search fields; careful elsewhere.
{ "auto_submit": true // Send Enter key after paste (default: false)}Clipboard behavior
Section titled “Clipboard behavior”clipboard_settle_delay controls the wait between a successful clipboard copy and
the paste shortcut (default 0.15 seconds). It accepts finite nonnegative numbers;
0 skips the wait. Lower values are an advanced compatibility tradeoff: some
applications may paste stale clipboard contents. Direct typing is unaffected.
hyprwhspr saves your clipboard before injection and restores it afterward — dictated text never permanently overwrites it. To instead clear the clipboard a few seconds after pasting:
{ "clipboard_behavior": true, // true = clear clipboard after a delay (default: false = restore previous contents) "clipboard_clear_delay": 5.0 // seconds to wait before clearing (only when clipboard_behavior is true)}Recover the last dictation
Section titled “Recover the last dictation”The daemon keeps the last prepared dictation in memory — text only, no audio or disk history — so you can recover it when a paste does not land.
hyprwhspr record copy-last # Copy to clipboard for manual pastehyprwhspr record paste-last # Deliver to the currently focused applicationhyprwhspr record clear-last # Forget the retained textBind these through your compositor so the destination keeps focus — in Hyprland,
bind = SUPER ALT, V, exec, hyprwhspr record paste-last. Recovery reuses the
exact prepared text without rerunning hooks, and never sends the auto-submit
Enter. Continuous mode retains the latest segment, not the whole session.
Dictation into an app with injection disabled is never retained.
Sway focus and recovery
Section titled “Sway focus and recovery”The service finds Sway through SWAYSOCK. Setup imports it.
After upgrading, run these from inside Sway:
systemctl --user import-environment SWAYSOCK XDG_CURRENT_DESKTOPsystemctl --user restart hyprwhspr.serviceIf focus is unknown, nothing is pasted. If focus moves before paste, nothing is
sent and your clipboard is restored. In live typing, a focus change stops the
rest of the dictation. copy-last recovers all of it.
An app rule with auto_paste: false blocks recovery when focus is unknown.
Sway paste needs exactly one seat. A named seat beside seat0 counts as two.
XWayland apps like Steam and Wine paste through ydotool, then xdotool.
Native windows use wtype or ydotool.
Restart the service after changing sessions.