Wayland Notes

Wayland Notes

Wayland locks down the synthetic input and window introspection that desktop dictation relies on, so TypeWhisper uses compositor-native paths and a few one-click setup helpers. This page consolidates the Wayland-specific guidance for hotkeys, typing, window detection, browser URL detection, and tray icons.

Global hotkeys

On Wayland the global dictation shortcut uses an evdev backend that reads /dev/input/event* directly, so the configured shortcut fires regardless of which window has focus.

• It is enabled by default.
• It requires your user to be in the input group.
• If the evdev path is unavailable, TypeWhisper falls back to the XDG portal, then to focused-only SharpHook.
• You can turn it off in Settings → Shortcuts to keep focused-only behavior.

See Global hotkeys for the activation modes and shortcut details.

Keyboard input / typing backends

TypeWhisper selects a typing/paste backend per session:

Session	Backend tried first	Notes
wlroots (Hyprland, Sway)	wtype	Native virtual-keyboard protocol.
GNOME / KDE Wayland	ydotool	These compositors omit the wtype virtual-keyboard protocol; wtype and xdotool are later fallbacks.
X11 / XWayland	xdotool	Used for X11 apps.

ydotool requires its daemon to be running and your user to be in the input group. The Text insertion panel surfaces the current backend chain and offers a one-click setup flow for the ydotool daemon and input-group membership when needed.

Active-window detection

Profile matching by process name (for example firefox, code, soffice.bin) needs TypeWhisper to know which window has focus. It picks a compositor-native provider per session:

Session	Window provider
X11 / XWayland	xdotool
Hyprland	hyprctl
Sway	swaymsg
KDE Plasma	kdotool
GNOME Wayland	Window Calls extension

On GNOME Wayland there is no built-in way for an unprivileged app to ask "what's the active window." Install the user-level Window Calls GNOME Shell extension from https://extensions.gnome.org/extension/4974/window-calls/ (the Profiles section has an Install Window Calls extension button that opens this page when the extension is missing), then restart TypeWhisper — no logout required.

Without the extension, GNOME Wayland users can still use URL-only profile rules and any global (no-match) profile, but app-name matching will not fire.

Browser URL detection for profile rules

URL-based profile rules (mail.google.com, *.github.com, etc.) need TypeWhisper to read the browser's address bar. On Wayland synthetic-input shortcuts are blocked by the compositor, so TypeWhisper walks the browser's AT-SPI accessibility tree — which only works if the browser is exposing it.

The Profiles section has an Enable browser URL detection button that:

• Writes ~/.config/environment.d/typewhisper-accessibility.conf setting MOZ_ENABLE_ACCESSIBILITY=1 and GTK_MODULES=gail:atk-bridge for Firefox-family browsers.
• Patches user-local .desktop launchers, setting MOZ_ENABLE_ACCESSIBILITY=1 for Firefox-family browsers and --force-renderer-accessibility for Chromium-family browsers.
• Backs up any non-owned user .desktop files under ~/.local/share/typewhisper/launcher-backups/ so the integration can be removed cleanly without losing customizations.

Firefox additionally needs the lazy-init gate flipped. Modern Firefox refuses to register on AT-SPI until accessibility is forced on:

1. Open about:config and accept the warning.
2. Search for accessibility.force_disabled.
3. Change the value from 0 to -1.
4. Restart Firefox. Verify via about:support — the Accessibility section should say Activated: Yes.

Diagnostics

The Error Log on the About page records a one-line AT-SPI walk diagnostic per unique state, for example:

AT-SPI URL walk: process=firefox matched-app='Firefox' nodes-walked=N best-score=... result=...

matched-app=none means the browser isn't exposing AT-SPI; result=null with a non-null best-score means the walker reached the address bar but didn't recognize it.

GNOME tray icons

GNOME Shell does not show AppIndicator/KStatusNotifier tray icons by default. Install and enable the AppIndicator extension if you want TypeWhisper's tray menu/icon in the top bar:

sudo dnf install -y gnome-shell-extension-appindicator
gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com

If gnome-extensions enable reports that the extension does not exist right after installation, log out and back in so GNOME Shell reloads system extensions, then run the enable command again. Restart TypeWhisper after the extension is loaded. See Desktop integration for more on the tray.

Related pages

• Global hotkeys — activation modes and the evdev backend.
• Text insertion — typing/paste backends and the one-click setup flow.
• Profiles — app-name and URL rules that depend on the providers above.
• Desktop integration — tray, autostart, and single-instance behavior.
• Troubleshooting — symptom-based fixes for Wayland issues.

---

Changelog

Date	Change
2026-06-17	Initial version.