Text Insertion

Text Insertion

Text insertion controls how transcribed text reaches the application you are dictating into. TypeWhisper lets you pick a strategy per application and includes a Smart Auto mode that adapts to browsers, terminals, and Wayland sessions.

Per-app strategies

You set an insertion strategy per application, keyed by process name:

Strategy	Behavior
Auto	Smart per-target selection (see below).
Clipboard Paste	Copies the text and pastes it into the target.
Direct Typing	Types the text character by character.
Copy Only	Copies the text to the clipboard without inserting it.

Auto-paste includes retry handling and clipboard preservation so your existing clipboard contents are restored after a paste.

How a clipboard paste is sequenced

Clipboard paste on Wayland is asynchronous — the target reads the selection when it gets around to it, not when the keystroke arrives — so the paste path is ordered explicitly rather than by fixed delays:

1. The clipboard is read back before Ctrl+V is sent, confirming it actually serves the dictated text (and re-setting it once if not). This makes the target process the selection offer before the keystroke, and it also catches a silently-failed clipboard write, which would otherwise paste your previous clipboard contents into the document.
2. Auto-enter waits for the paste to land before sending Enter. Otherwise Enter can overtake an in-flight paste and submit an empty or stale field, with the dictated text arriving in the next message or being lost.
3. Your previous clipboard is restored only after the paste is confirmed, watched through an AT-SPI text-changed signal armed before Ctrl+V rather than after a fixed delay that could overwrite a transfer still in progress. An ownership check avoids clobbering a clipboard you changed yourself in the meantime.

When AT-SPI isn't running, steps 2 and 3 fall back to the previous floor delay. No extra delay is introduced by this ordering — the floor simply moves ahead of Enter.

Multi-line text going into a terminal is routed through clipboard paste rather than direct typing, so embedded newlines can't be delivered as a series of Enter keystrokes that execute each line.

The per-app strategy editor (process name → Auto / Clipboard Paste / Direct Typing / Copy Only) lives in the App insertion strategies row on the Dictation settings page.

Smart Auto behavior

When a target uses the Auto strategy, TypeWhisper picks per-target:

• Types directly into supported browsers — but falls back to clipboard paste when the window title looks like a webmail composer.
• Types directly into terminals and the Codex CLI, where a synthesized Ctrl+V is not interpreted as paste.
• On Wayland sessions where the focused app can't be identified, prefers direct typing for ASCII text and clipboard paste for non-ASCII text.

Backend chain and setup

The resolved backend chain and the one-click ydotool / input-group setup are shown in the screenshot at the top of this page.

The Text-insertion settings panel surfaces the current backend chain for your session and offers a one-click setup flow for the ydotool daemon and input-group membership when those are needed.

The privileged part of ydotool setup refuses to modify files it does not own. Both of its targets — the /dev/uinput udev rule and the uinput module-load file — are checked inside the privileged script immediately before writing: a symlink, a non-regular file, or a regular file lacking TypeWhisper's ownership marker causes setup to abort with an explanation rather than truncate whatever was there. If an existing file already achieves the goal, it's left alone and setup reports success.

Tools

Text insertion relies on session-appropriate desktop tools:

Purpose	Tools
Clipboard (X11)	xclip
Clipboard (Wayland)	wl-copy / wl-paste
Typing / paste backend	wtype, ydotool, xdotool

The right typing backend is selected per session. See Wayland notes for which backend is tried first on wlroots compositors versus GNOME / KDE Wayland, and for the ydotool daemon and input-group requirements.

Related pages

• Wayland notes — typing backend selection and Wayland setup.
• Profiles — per-app and per-URL matching that pairs with insertion strategies.
• Dictation — where auto-paste fits in the dictation workflow.

---

Changelog

Date	Change
2026-06-17	Initial version.
2026-06-17	Added Text insertion screenshot.
2026-07-27	v0.13.0: documented the clipboard-paste ordering (read-back before Ctrl+V, auto-enter gated on delivery, confirmed clipboard restore), terminal multi-line routing, and the fail-closed ydotool privileged setup.