ProjectBreakdown-101

Troubleshooting

7 min read

Audio version — Estimated duration: 9 min 45 sec

Troubleshooting

This page covers common problems you might encounter while running Whisper Dictate. Each issue is organized by symptom — what you see, what’s causing it, and how to fix it.

Permission Issues

”No keyboard devices found”

What you see:

[whisper-dictate] ERROR: No keyboard devices found.
  You need to be in the 'input' group:
    sudo usermod -aG input $USER
  Then log out and log back in (or reboot).

Why this happens: The script reads raw keyboard events from /dev/input/event* files. These files are owned by the input group. If your user isn’t in that group, you get PermissionError for every device, and the script finds zero keyboards.

Fix:

sudo usermod -aG input $USER

Then log out completely and log back in. A terminal restart is not enough — the group membership check only happens at login.

Verify:

groups $USER

You should see input in the output.

Quick test without logout: You can test with sudo (not recommended for regular use):

sudo python whisper-dictate-v2.py

“PermissionError: [Errno 13] Permission denied: ‘/dev/input/event*’”

What you see: A Python traceback mentioning PermissionError on an event device.

Why this happens: Same as above — you’re not in the input group.

Fix: Same as above — add yourself to the input group and log back in.

”ydotoold permission denied”

What you see:

[whisper-dictate] ydotool failed: [Errno 13] Permission denied

Why this happens: ydotool writes to /dev/uinput to inject keystrokes. By default, this device is root-only. Either ydotoold isn’t running (the script starts it automatically) or it doesn’t have permissions.

Fix 1 — Start ydotoold manually with sudo:

sudo ydotoold &

Then run the script normally. The background daemon holds the permissions until you reboot.

Fix 2 — Permanent permission fix:

sudo chmod 666 /dev/uinput

This makes /dev/uinput world-writable. It resets on reboot unless you set up a udev rule:

echo 'KERNEL=="uinput", MODE="0666"' | sudo tee /etc/udev/rules.d/99-uinput.rules

Startup Issues

”ModuleNotFoundError: No module named ‘evdev’”

What you see:

ModuleNotFoundError: No module named 'evdev'

Why this happens: You haven’t installed the Python package for evdev.

Fix:

pip install evdev

“ModuleNotFoundError: No module named ‘faster_whisper’”

What you see:

ModuleNotFoundError: No module named 'faster_whisper'

Why this happens: You haven’t installed the faster-whisper package.

Fix:

pip install faster-whisper

“PortAudioError: Error opening InputStream”

What you see:

sounddevice.PortAudioError: Error opening InputStream

Why this happens: PortAudio (the audio library behind sounddevice) can’t open your microphone. Possible causes:

  • No microphone connected
  • Microphone is muted or blocked by another application
  • ALSA/PulseAudio configuration issue

Fixes:

  1. Check available audio devices: 
    python3 -c "import sounddevice; print(sounddevice.query_devices())"
  2. Test your microphone with a simple recording: 
    arecord -d 3 test.wav && aplay test.wav
  3. Install portaudio development files and reinstall sounddevice: 
    sudo apt install libportaudio2
pip install sounddevice --force-reinstall
  4. Check PulseAudio volume levels: 
    pavucontrol  # GUI mixer — check Input Devices tab

Model Issues

”Model not downloading”

What you see: The script hangs at “Loading Whisper model…” or shows network errors.

Why this happens: The first time you run the script, it downloads the Whisper model from Hugging Face Hub. This requires an internet connection. The model file is ~6GB for medium.

Fixes:

  1. Check your internet connection: 
    curl https://huggingface.co
  2. Check disk space — the model needs:
    • tiny: 300 MB free
    • base: 600 MB
    • small: 2 GB
    • medium: 6 GB
    • large-v3: 12 GB
  3. The model is cached in ./models/. Delete this directory and re-run to retry.
  4. Manually download from Hugging Face: https://huggingface.co/Systran/faster-whisper-medium

”CUDA out of memory”

What you see:

RuntimeError: CUDA out of memory. Tried to allocate ... MiB

Why this happens: Your GPU doesn’t have enough VRAM for the selected model size. For example, medium needs ~5GB VRAM, large-v3 needs ~10GB.

Fixes:

  1. Use a smaller model: 
    MODEL_SIZE = "small"   # 2GB VRAM
# or
MODEL_SIZE = "tiny"    # 1GB VRAM
  2. Use int8 quantization: 
    COMPUTE_TYPE = "int8"  # Lowest VRAM usage
  3. Switch to CPU: 
    DEVICE = "cpu"         # Slower but works on any system
  4. Close other GPU applications (browsers, other ML tools, games).

Check current VRAM usage:

nvidia-smi
# Look at "Memory-Usage" for your GPU

“NaN” or infinity errors

What you see:

RuntimeError: value cannot be converted to type float16 without overflow

Or garbled/wrong transcription output.

Why this happens: Some GPUs (including RTX 3050) have issues with full float16 precision when running certain layers of Whisper. The int8_float16 mixed precision avoids this.

Fix: Use int8_float16 compute type (this is the default):

COMPUTE_TYPE = "int8_float16"

Model is too slow

What you see: Transcription takes 30+ seconds.

Fixes:

  1. Check if GPU is being used: 
    nvidia-smi
# Look for Python process in the "Processes" section
  2. Restart after GPU usage: If you just ran another GPU task, the GPU may be throttled. Wait a minute and try again.
  3. Use a smaller model: 
    MODEL_SIZE = "tiny"
  4. Set language (skips auto-detection): 
    LANGUAGE = "en"

Text Injection Issues

Nothing appears in the window

What you see: “Typed” notification appears, but no text in your application.

Why this happens: ydotool injected keystrokes but the window wasn’t focused, or the application doesn’t accept text input.

Fixes:

  1. Make sure your target window is focused before releasing the hotkey. Click into the text field first.
  2. Check if ydotoold is running: 
    pgrep ydotoold
  3. Test ydotool manually: 
    ydotool type "hello world"

Wrong characters appear

What you see: The typed text has wrong characters — e.g., “screenshot” appears instead of your dictation, or symbols like @#$ are wrong.

Why this happens: The hotkey (Right Alt) was still held or pressed again while ydotool was typing. The keystrokes are being sent with the Alt modifier active, which changes what characters they produce (AltGr combinations).

This was a known bug (Bug 2) that has been fixed. If you’re still seeing it, make sure you have the latest version of the script — the fix ensures:

  1. Stream previews never type (terminal only)
  2. Final transcription checks _hotkey_held before calling ydotool
  3. If Alt is pressed again, text goes to clipboard instead

Clipboard fallback keeps triggering

What you see: “Copied to clipboard” notification every time.

Why this happens: ydotool is failing consistently. Possible causes:

  • ydotoold not running
  • Permission denied on /dev/uinput
  • ydotool not installed

Fixes:

  1. Install ydotool: 
    sudo apt install ydotool
  2. Start the daemon: 
    sudo ydotoold &
  3. Check permissions (see permission section above).

Audio Issues

No sound is recorded

What you see: “Nothing detected” or “Too short” for every dictation attempt.

Why this happens: Your microphone isn’t picking up sound.

Fixes:

  1. Check OS microphone settings: 
    pavucontrol   # Check Input Devices tab — make sure mic isn't muted
  2. Test recording: 
    arecord -d 3 test.wav && aplay test.wav
  3. Check default audio device: The script uses the system default. Change it in PulseAudio settings.
  4. Check microphone hardware: Is it plugged in? Is it on mute?

Background noise transcribed as speech

What you see: Random words or gibberish appear when you’re not speaking.

Fixes:

  1. Use a better microphone — headset mics are better than built-in laptop mics.
  2. Reduce background noise — close windows, move away from fans.
  3. Speak closer to the mic.
  4. Increase MIN_DURATION: 
    MIN_DURATION = 1.0   # Filters short noises

Race Condition Symptoms

Transcription is sometimes empty

What you see: Recording works (terminal shows >> previews), but final -> line is missing and nothing is typed.

Why this happens: This was Bug 1 — the transcription worker sometimes got an empty audio buffer if the hotkey was pressed again quickly. Fixed in current version.

Ensure you have the latest code with the snapshot fix in on_key_up().

Log Messages Reference

This table explains every log message the script produces, so you can understand what’s happening:

MessageMeaning
Loading Whisper model...First-run or startup — model is being loaded into GPU
Ready. Hold {key} to dictate.All systems operational, waiting for hotkey
Found {N} keyboard device(s).N physical keyboards detected
Watching: {name} ({path})Monitoring a specific keyboard device
Recording...Hotkey pressed, microphone active
>> {text}Stream preview — partial transcription during recording
-> {text}Final transcription result (this is what gets typed)
ydotool failed: {error}ydotool couldn’t type — falling back to clipboard
Device lost: {path}A keyboard was disconnected or removed
Stopped.Program exited cleanly

Still Having Issues?

If none of these solutions work, try:

  1. Run with verbose output: Check all terminal output, look for error messages
  2. Check system logs: 
    journalctl -xe | grep whisper
  3. File a GitHub issue: Include the full terminal output and description of what you were doing

See variables for available settings to tune, or components to understand how the system works internally.

Graph View

Backlinks