Troubleshooting

Troubleshooting & FAQ

Common symptoms and what to check, drawn from TypeWhisper's documented Linux behavior. If a control is disabled, the UI usually shows the reason and an install hint — read that first.

A control is disabled and shows a reason

Linux-specific checks disable unavailable controls and explain the missing tool. Depending on the feature you may be prompted to install one of:

Tool	Used for
pactl	Audio ducking
playerctl	Media pause during recording
pw-play / paplay / aplay	Sound feedback (PipeWire / PulseAudio / ALSA)
CUDA 12 libraries	The GPU backend (libcudart.so.12, libcublas.so.12)

Install the named tool through your distribution, then revisit the setting.

The tray icon isn't showing on GNOME

GNOME Shell does not show AppIndicator/KStatusNotifier tray icons by default. Install and enable the AppIndicator extension:

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

If the enable command says the extension does not exist right after install, log out and back in, then enable again. Restart TypeWhisper afterward. See Wayland notes.

The global hotkey doesn't fire on Wayland

The evdev backend that makes the hotkey fire regardless of focus needs your user to be in the input group. Also confirm the backend is enabled in Settings → Shortcuts (it can be toggled off, which falls back to focused-only behavior). See Global hotkeys and Wayland notes.

App-name / active-window matching isn't working

Profile matching by process name needs a window provider for your session:

• GNOME Wayland — install the Window Calls extension, then restart TypeWhisper.
• KDE Plasma — install kdotool; without it, app-name matching is unavailable in that session.

See Wayland notes and Profiles.

Browser URL profile rules aren't matching

URL rules read the browser's address bar, which on Wayland goes through AT-SPI:

1. Use the Enable browser URL detection button in the Profiles section.
2. For Firefox, also flip accessibility.force_disabled from 0 to -1 in about:config and restart Firefox (verify via about:support).
3. Check the Error Log on the About page for the AT-SPI walk diagnostic. 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.

See Wayland notes.

CUDA isn't loading

The GPU backend needs CUDA 12 runtime/toolkit libraries providing libcudart.so.12 and libcublas.so.12, plus an NVIDIA GPU and driver. CUDA currently applies only to the bundled whisper.cpp engine. See GPU & CUDA.

Short or quiet clips are being dropped

A short-speech policy with peak-level and duration thresholds drops accidental taps and silent clips before they reach the engine. For short, quiet utterances you still want transcribed, turn on the aggressive short-clip transcription option. See Dictation.

Where the logs live

Logs are stored under Logs/ in the user data directory (~/.local/share/TypeWhisper on typical setups). The Error Log on the About page also records per-state AT-SPI walk diagnostics for URL detection. See Data and file paths.

Filing an issue

If you hit a setup-specific issue, please create an issue or pull request including your distribution, desktop environment, display server, reproduction steps, and any relevant logs (including the Error Log's AT-SPI walk diagnostics). See Contributing.

Related pages

• Wayland notes — the Wayland-specific causes behind most of these symptoms.
• GPU & CUDA — CUDA backend requirements.
• About — the Error Log and update checks.
• Data and file paths — where logs and data live.
• Contributing — how to file an issue or PR.

---

Changelog

Date	Change
2026-06-17	Initial version.
2026-06-17	Corrected the Sound feedback tool to pw-play / paplay / aplay (not canberra-gtk-play).