Troubleshooting¶

Mouse grid: "Failed to show grid — is extension enabled?"¶

You don't install the extension yourself — EasySpeak does it automatically on startup, copying it to ~/.local/share/gnome-shell/extensions/easyspeak@local/ and keeping it up to date (look for an easyspeak: installed ... or easyspeak: updated ... message). On Wayland, GNOME Shell only scans for new extensions at login, so you typically have to log out and back in before it becomes loadable.

After re-login, enable it from the command line:

gnome-extensions enable easyspeak@local

…or open the Extensions GNOME app and toggle EasySpeak on.

To remove it later:

gnome-extensions disable easyspeak@local
rm -rf ~/.local/share/gnome-shell/extensions/easyspeak@local

…or click the trash icon next to EasySpeak in the Extensions app.

Dictation not working¶

EasySpeak enables the GNOME accessibility bridge on first run; log out and back in after seeing the dictation: enabled GNOME toolkit-accessibility message. If the auto-config printed a WARNING instead (e.g. on a non-GNOME or locked-down desktop), run it manually:

gsettings set org.gnome.desktop.interface toolkit-accessibility true
# Log out and back in

Browser plugin: link numbers don't work¶

EasySpeak appends two required lines to ~/.config/qutebrowser/config.py on first run (you'll see a browser: wrote ... or browser: updated ... message). If you see a browser: note: ... is read-only or a similar error instead, add these lines to the config module yourself:

config.load_autoconfig(False)
c.hints.chars = '0123456789'

Wake word not detecting¶

Check the microphone: arecord -d 3 test.wav && aplay test.wav
Adjust WAKE_THRESHOLD (lower = more sensitive) — see core.config

Wake word triggers multiple times¶

Mic gain too high. Lower the capture level:

alsamixer
# Press F6 to select your mic device
# Press Tab to switch to Capture
# Lower to ~70

Commands misheard¶

Adjust SILENCE_THRESHOLD — see core.config
Speak clearly after the beep

Piper permission denied¶

chmod +x ~/.local/bin/piper/piper
chmod +x ~/.local/bin/piper/espeak-ng

pip install fails with PyAV/Cython errors¶

You're on Python 3.14 or 3.13. Use python3.12 with a venv instead:

sudo dnf install python3.12 python3.12-devel
python3.12 -m venv ~/easyspeak-venv
source ~/easyspeak-venv/bin/activate
pip install faster-whisper openwakeword numpy pyaudio
cd ~/easyspeak
pip install -e .