Troubleshooting

Choose what you see, then open the likely causes. Each cause matches a check in make doctor, so you can confirm the fix.

From the Whispy source folder, run the full diagnostic at any time:

make doctor

Pressing the trigger does nothing

No start sound and no recording. Work through the likely causes below.

Input Monitoring

Whispy detects the Fn key through an event tap, which needs Input Monitoring. Open System Settings → Privacy & Security → Input Monitoring, enable Whispy, then restart it from the menu bar (Restart).

Run make doctor to confirm.

X11 session

The trigger key is captured from an X11 session. If DISPLAY is not set, no X server is available to listen on. Run Whispy from your graphical session, or restart the service with systemctl --user restart whispy.service. Under Wayland, see the Wayland entry below.

Run make doctor to confirm.

Daemon

Start the service with systemctl --user start whispy.service and read ~/.whispy-error.log if it stops again. If the doctor reports a token mismatch, restart it with systemctl --user restart whispy.service.

The daemon is not answering on its local port. Open /Applications/Whispy.app (menu bar icon should appear) and check ~/.whispy-error.log. If the doctor reports a token mismatch, quit and reopen the app.

Run make doctor to confirm.

A custom trigger is set. If you changed trigger in the config, press that key instead of the default (Fn on macOS, Right Ctrl on Linux). See trigger and trigger_mode. In toggle mode a single press starts and a second press stops.

Recording works but no text appears

You hear the sounds, but nothing is typed into the focused field.

Accessibility

Whispy types through osascript, which needs Accessibility. Open System Settings → Privacy & Security → Accessibility and enable Whispy. A look at ~/.whispy.log showing osascript timeout or error (1002) confirms it.

Upgrading from an older build? macOS keys grants to the app identity. Reset and re-grant:

tccutil reset Accessibility com.whispy
tccutil reset AppleEvents com.whispy

Then relaunch Whispy and accept the prompts.

Run make doctor to confirm.

Xdotool

Text injection on Linux uses xdotool. Install it, then restart the service:

sudo apt install xdotool      # Debian/Ubuntu
sudo dnf install xdotool      # Fedora
sudo pacman -S xdotool        # Arch

Run make doctor to confirm.

Clipboard tool

copy_to_clipboard is on by default and needs xclip or xsel. Without one, delivery silently falls back to typing key by key. Install one:

sudo apt install xclip        # Debian/Ubuntu
sudo dnf install xclip        # Fedora
sudo pacman -S xclip          # Arch

In a terminal emulator, clipboard paste uses Ctrl+V, which most terminals do not treat as paste. If you mostly dictate into a terminal, set copy_to_clipboard to false.

Run make doctor to confirm.

Microphone

Whispy needs microphone access. Open System Settings → Privacy & Security → Microphone and enable Whispy. If you clicked Don't Allow earlier, reset it and relaunch:

tccutil reset Microphone com.whispy

Run make doctor to confirm.

Audio backend

The PortAudio runtime is missing. Install it, then restart the service:

sudo apt install libportaudio2   # Debian/Ubuntu
sudo dnf install portaudio       # Fedora
sudo pacman -S portaudio         # Arch

The audio library (sounddevice/PortAudio) failed to load. Reinstall with the one-line installer, or rebuild with make app.

Run make doctor to confirm.

The clip was discarded. A recording is dropped when it is shorter than min_recording_duration (a tap rather than a hold), near-silent, or has almost no detected voice. ~/.whispy.log says which: Recording too short, near-silent (RMS ...) or No speech detected. Very short or quiet clips are dropped on purpose, so a stray filler word is never typed; see how the model and its silence gates work. Also check the input device and your distance from the microphone.

Text appears garbled / accents wrong

Characters such as é or , come out wrong, for example commas typed as full stops.

Keystroke delivery on a non-US keyboard. With copy_to_clipboard set to false, Whispy synthesizes keystrokes, which are only correct on a US layout. Set it back to true (the default) so text is pasted byte-exact whatever your layout. See the configuration page to build the change.

Clipboard tool

Clipboard delivery on Linux needs xclip or xsel; without one the text is typed key by key and may be garbled. Install one:

sudo apt install xclip

Run make doctor to confirm.

Whispy doesn't start / no menu bar or tray icon

The app does not appear, or exits right after launching.

Daemon

Check the service with systemctl --user status whispy.service and read ~/.whispy-error.log. A port in use (9090 by default) prevents startup. Restart with systemctl --user restart whispy.service.

Open /Applications/Whispy.app and wait a few seconds. If nothing appears, read ~/.whispy-error.log. A port in use (9090 by default) prevents startup. A build older than your source also looks like a missing fix: run make reinstall to rebuild and relaunch.

Run make doctor to confirm.

Audio backend

Install the PortAudio runtime (libportaudio2 on Debian/Ubuntu, portaudio on Fedora and Arch), then restart the service.

If the audio library cannot load, Whispy cannot start recording. Reinstall with the one-line installer, or rebuild with make app.

Run make doctor to confirm.

First dictation is slow or fails (model)

The first run downloads the speech model, about 639 MB, once.

Model

Wait for the download to finish: it needs a network connection once and is then cached under ~/.cache/huggingface/hub/models--istupakov--parakeet-tdt-0.6b-v3-onnx. The doctor shows a warning, not a failure, until the model is cached. If it never finishes, check ~/.whispy-error.log and your connection, then run systemctl --user restart whispy.service.

Run make doctor to confirm.

Linux: nothing works under Wayland

Whispy supports X11 sessions only. Wayland restricts global hotkeys and synthetic keyboard input.

X11 session

Log out and choose an Xorg or X11 session at your display manager (usually under a gear icon on the login screen), then log back in. Wayland support is planned for a later release.

Run make doctor to confirm.

Still stuck? Read ~/.whispy.log and ~/.whispy-error.log, or open an issue.