Skip to content

paste

Jump to bottom
github-actions[bot] edited this page Oct 3, 2026 · 1 revision

Pasting Dictation

By default VoxCtrl delivers dictated text to the focused window as one paste rather than one key press per character. This is what the inject target does (see Routing); this page explains how it works, what each platform needs, and how to diagnose it.

Why paste: typing sends hundreds of key events, so if focus is somewhere that is not a text field — a game, a file manager, a terminal running a program that reads single keys — every character is a stray key press. A paste is a single shortcut. Typing remains the fallback.

What happens on every dictation

  1. Choose the shortcut for the focused window (below).
  2. Back up the whole clipboard — every format it offers, not just text.
  3. Put the dictation on the clipboard, asking clipboard managers and cloud history not to record it.
  4. Send the paste shortcut.
  5. Wait for the application to read it (at least 300 ms; on X11 VoxCtrl can see the read and waits for slow applications, up to 2 s).
  6. Restore the clipboard — but only if it still holds the dictation. If you copied something else in the meantime, that is yours and is left alone.

If any step cannot be done, the text is typed instead, so a dictation is never silently dropped. Every step has a time limit, so one stalled clipboard owner cannot hang dictation. Dictations are delivered one at a time, so two in quick succession cannot share the clipboard.

Text longer than 2,000 characters is pasted on Windows even when the setting is off (typing it makes the target process one message per character).

Settings

Settings → Features → Text Delivery, or config.json (see Configuration):

Key Default
features.paste_instead_of_typing true Paste instead of typing. Off = always type.
features.paste_shortcut "auto" auto, ctrl+v, ctrl+shift+v or shift+insert. Force one only for a window VoxCtrl cannot identify.

Disabled where it does not work

Linux Mint is detected (/etc/os-release, ID=linuxmint, which also covers LMDE) and pasting is switched off there: the setting is greyed out with the reason, and text is always typed. Set VOXCTRL_FORCE_PASTE=1 to override this when testing.

Choosing the paste shortcut

auto uses Ctrl+V, except where a window needs something else:

Window Shortcut How it is recognised
Linux terminal emulators (GNOME Terminal, Konsole, Alacritty, kitty, foot, WezTerm, xterm, …) Ctrl+Shift+V X11: WM_CLASS of the active window. Wayland: Hyprland (hyprctl), sway (swaymsg) or KDE (kdotool) if installed
Windows console, mintty, PuTTY, ConEmu Shift+Insert Window class
Everything else Ctrl+V

On a Wayland desktop that cannot say which window is focused (GNOME), terminals cannot be recognised: set paste_shortcut to ctrl+shift+v if that is what you paste into.

The clipboard backup

Everything is held in memory for the length of one paste and is never written to disk or logged.

Platform What is saved
Windows Every format backed by a memory block: text, HTML, RTF, images (CF_DIB/CF_DIBV5), file lists (CF_HDROP), registered and private formats. Formats that are GDI handles (CF_BITMAP, metafiles, palettes) are skipped; Windows rebuilds them from the memory formats.
X11 Every target the owner offers, including large ones sent in chunks (INCR). X11 has no clipboard store, so after a restore VoxCtrl itself serves the saved formats until something else takes the clipboard — if VoxCtrl exits and no clipboard manager holds them, they are gone.
Wayland Every MIME type, through the data-control protocol (wlroots compositors, KDE). GNOME has no such protocol, so it goes through XWayland like X11.

An item larger than 256 MB, or a format an application never finishes sending, is skipped (the others are kept). If nothing could be read, the clipboard is treated as unreadable, not as empty — an empty-clipboard restore would clear it.

Sending the shortcut

Session Tried in order
Windows SendInput
X11 XTEST key events (no helper needed), then xdotool
Wayland wtype, ydotool, the RemoteDesktop portal, then X11 (reaches XWayland windows only — VoxCtrl logs a warning)

Held modifier keys (typically the dictation hotkey) are released first, so they cannot turn Ctrl+V into a different shortcut.

The RemoteDesktop portal (Wayland)

GNOME and KDE offer no virtual-keyboard protocol for wtype, and X11 key events reach only XWayland windows. The sanctioned route is the org.freedesktop.portal.RemoteDesktop portal:

  • The first dictation shows your desktop's permission dialog ("allow VoxCtrl to control the keyboard"). It appears before the clipboard is touched.
  • The grant is remembered in ~/.config/voxctrl/portal-keyboard-token, so later launches do not ask again. Revoke it in your desktop's settings, or delete that file.
  • If you decline, or the portal is missing, VoxCtrl remembers that until it is restarted and falls back; the log says so. Installing ydotool is the alternative.

See Privacy for what this permits.

Troubleshooting

VoxCtrl logs each stage. The default log filter includes the paste crates; for more detail:

RUST_LOG=voxctrl_inject=debug,voxctrl_clipboard=debug,voxctrl_routing=info voxctrl
Log line Meaning
clipboard backed up backend=… formats=N Backup worked. formats=0 means the clipboard was genuinely empty
clipboard format … could not be backed up One format never finished sending and was skipped; it will not be restored
could not back up the clipboard … it will not be restored The backup failed entirely; the dictation is still pasted, but your previous clipboard is lost
paste shortcut sent shortcut=… ok=… Which shortcut was sent, and whether the sender reported success
nothing could send the paste shortcut to native Wayland windows No wtype/ydotool/portal; only XWayland windows will receive it
RemoteDesktop portal unavailable Permission declined, or no portal on this desktop
clipboard restored formats=N Restored
the clipboard changed during the paste … left alone You copied something meanwhile; nothing was overwritten
paste failed (…); typing instead The paste could not be done; the text was typed

Common problems:

  • Nothing pastes into a terminal — set paste_shortcut to ctrl+shift+v.
  • Nothing pastes into a native Wayland window — install ydotool, or accept the portal permission dialog.
  • Your clipboard comes back after a delay, not immediately — expected: the restore waits for the application to read the dictation.

Manual test matrix

Automated tests cover the X11 path end to end (a stand-in application receives the shortcut and reads the clipboard; multi-format backup/restore; a stalled owner; a clipboard manager taking over; concurrent dictations), the Wayland backend on a headless sway, and the RemoteDesktop portal flow against a stand-in portal. Windows and the real desktop portals are checked by hand:

Check Expect
Copy text, dictate into a text editor, press Ctrl+V The copied text, not the dictation
Copy an image (screenshot), dictate, paste the image into an image editor The image is intact
Copy files in a file manager, dictate, paste into the file manager The files
Dictate into a terminal Pasted, no ^V
Dictate with a game or file manager focused Nothing is typed
Dictate twice quickly Both appear, in order
Dictate with a clipboard manager running The dictation is not in its history; your copy is restored
(Wayland) First dictation The permission dialog appears once, before anything is pasted
(Linux Mint) Settings → Features The paste toggle is greyed out with the reason

Clone this wiki locally