Troubleshooting

Find the failing part of the local voice pipeline.

QuillSpeak is intentionally explicit: triggers, audio capture, local model inference, scripts, clipboard copy, and paste shortcuts are separate steps. Most issues are one missing tool or one unavailable model.

Quick Checks

  1. Start QuillSpeak from a terminal so logs are visible: QUILLSPEAK_DEV_LOG=1 quillspeak.
  2. Open Settings and check the Status page.
  3. Make sure at least one model is ready on the Models page.
  4. Make sure the shortcut is enabled and has a trigger that matches your session.
  5. Turn off script and paste temporarily, then test plain copy-to-clipboard.

Model Issues

Symptom Check
No model appears in shortcut dropdowns Download and verify a model on the Models page. Shortcut pages show only ready models as normal choices.
Selected model is marked missing The config references a model that is not installed. Download it or choose a ready model.
GPU backend fails Use compute_backend = "auto" for CPU fallback, or select cpu explicitly.
First transcription is slow Model loading can dominate the first run. Enable Keep model loaded for faster later runs.

Trigger Issues

Symptom Check
X11 keyboard shortcut does not fire Confirm this is a pure X11 session: DISPLAY is set and WAYLAND_DISPLAY is not set.
Wayland shortcut does not fire Configure the compositor or hotkey tool to call quillspeak trigger Default start and stop.
quillspeak trigger cannot connect Make sure the main app is already running and that $XDG_RUNTIME_DIR/quillspeak/command.sock exists.
Signal does nothing Make sure an enabled shortcut uses that exact signal. Supported names are SIGUSR1, SIGUSR2, SIGALRM, and SIGWINCH.
Same-signal shortcut starts but does not stop Send the same signal again while the same shortcut is active. Signals for other shortcuts are ignored while processing.

Clipboard and Paste Issues

Install the runtime tools for your session:

sudo apt install wl-clipboard xclip xdotool ydotool
Symptom Check
Copy fails on Wayland Install wl-clipboard. QuillSpeak uses wl-copy and wl-paste with a text MIME type.
Copy fails on X11 Install xclip.
Paste fails on X11 Install xdotool and make sure the focused app accepts the selected paste shortcut.
Paste fails on Wayland Install and configure ydotool. It may need a daemon and input permissions outside QuillSpeak.
Terminal receives nothing Use Ctrl+Shift+V instead of Ctrl+V for many terminal apps.

Audio and Mute Issues

Symptom Check
No microphone audio Try System Default first, then select a specific input device from Settings > General.
Speaker mute fails Install wireplumber and pipewire-bin. The fallback package for pactl is often pulseaudio-utils.
Very short recording is skipped Speak for a longer capture. Unusable short captures do not load Whisper or run output actions.

Script Issues

The script receives the transcript as $1, not on stdin. It must be executable and should print final text to stdout. 

chmod +x ~/bin/translate-to-english.sh
~/bin/translate-to-english.sh "Привіт, як справи?"

If a script fails, temporarily disable Run script and test plain clipboard copy. Then run the script manually with a short sample string.

Logs and Debug Audio

Useful runtime commands:

QUILLSPEAK_DEV_LOG=1 quillspeak
QUILLSPEAK_DEBUG_SAVE_AUDIO=1 QUILLSPEAK_DEV_LOG=1 quillspeak

QUILLSPEAK_DEV_LOG=1 enables debug logs for QuillSpeak crates while keeping dependency logs quieter than a global RUST_LOG=debug. Debug audio is written under /tmp/quillspeak-audio-debug unless the variable is a directory path.

Build Failures

Install the GTK/libadwaita development packages before building from source:

sudo apt install build-essential pkg-config cmake clang libclang-dev \
  libasound2-dev libpulse-dev libpipewire-0.3-dev \
  libgtk-4-dev libadwaita-1-dev

If a build fails because gtk4.pc, libadwaita-1.pc, or related pkg-config files are missing, install the system development packages instead of replacing the GTK4/libadwaita app stack.