Skip to content

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.

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.

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:

Terminal window
sleep 3; hyprwhspr config focused-window # then click into the app you want

Prefer 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.

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.

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.

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.

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.

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_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)
}

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.

Terminal window
hyprwhspr record copy-last # Copy to clipboard for manual paste
hyprwhspr record paste-last # Deliver to the currently focused application
hyprwhspr record clear-last # Forget the retained text

Bind 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.

The service finds Sway through SWAYSOCK. Setup imports it. After upgrading, run these from inside Sway:

Terminal window
systemctl --user import-environment SWAYSOCK XDG_CURRENT_DESKTOP
systemctl --user restart hyprwhspr.service

If 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.