STT-Assistant/docs/TROUBLESHOOTING.md

Troubleshooting

Common failure modes and their fixes.

"Device not found"

Error: Device 'VirtualMicSink.monitor' not found. Available sources: [...]
To create VirtualMicSink, run: scripts/audio-sink.sh start

Fix:

scripts/audio-sink.sh start

Then route audio into VirtualMicSink and try again.

"Can't select or copy text in the TUI"

Cause: Textual enables terminal mouse reporting, so mouse events are consumed by the app instead of the terminal, and native drag-selection never starts.

Fix: hold Shift while dragging to force your terminal's native selection, then copy as usual. (Alternatively, launching the app with mouse support disabled — app.run(mouse=False) — restores plain selection but loses in-app scrolling/clicks.)

High latency / slow transcription

By default, the daemon uses compute_type = "int8" and device = "cpu", which trades speed for accuracy. To speed up:

1. Pin cpu_threads to the physical core count: cpu_threads = 16 in [whisper] (CTranslate2's automatic choice is often slower than an explicit count on many-core CPUs)
2. Reduce model size: --model base or --model tiny
3. Enable GPU (if you have CUDA): --device cuda with compute_type float16
4. Reduce beam_size: Edit config to beam_size = 1 (already default, very fast)

Example:

uv run stt-daemon --model base --device cuda

"Transcription backlog reached N of M"

This warning means the single transcription worker is falling behind: utterances are arriving faster than they are being transcribed, and once the queue is full the oldest ones get dropped. The worker is serial by design (faster-whisper's model isn't thread-safe), so fix it by making transcription faster rather than by queueing more:

1. Smaller/faster model: --model base or tiny
2. GPU: --device cuda with compute_type float16
3. Raise backlog_warn_at or queue_size in [daemon] only to make the warning/dropping less likely — it hides the symptom, not the cause.

Spanish / English / Other languages

The Faster-Whisper model is multilingual by default. It auto-detects language or can be forced:

uv run stt-daemon --language es   # Force Spanish
uv run stt-daemon --language en   # Force English
uv run stt-daemon --language auto # Auto-detect (default)

The output includes the detected language tag: [14:23:45] (es) ....

Recognizing Spanish vs. English better

• Force the language: Use --language es or --language en
• Use a larger model: --model medium or --model large (slower, more accurate)
• Tune VAD aggressiveness: Lower values (0–1) capture more, higher values (2–3) are stricter

Audio device not responding / parec hangs

If parec seems stuck:

1. Check if the source exists: pactl list short sources
2. Kill the daemon (Ctrl+C)
3. Verify PulseAudio is running: systemctl status pulseaudio or check journalctl
4. Restart PulseAudio if needed: systemctl restart pulseaudio
5. Re-run the daemon

Sounddevice backend issues

If using --backend sounddevice and getting import errors:

uv sync --extra portaudio

Then verify available devices:

python -c "import sounddevice as sd; print(sd.query_devices())"

Use the device index or name as --device 0 or --device "Microphone (...).

No transcriptions appearing

1. Check VAD is firing: uv run stt-daemon -v (verbose logging)
2. Verify audio is loud enough: uv run stt-daemon --check (check RMS)
3. Reduce aggressiveness (0–1 instead of 2–3) to detect quieter speech
4. Check min_utterance_ms isn't too high (default 300ms should be fine)

Whisper model not loading

Error loading model: ...

The model is downloaded on first run (~1.5 GB for small). Check:

1. Disk space: df -h (needs ~2 GB free)
2. Internet: Model is downloaded from Hugging Face
3. HF cache location: Models go to ~/.cache/huggingface/hub/ by default

You can override the cache:

export HF_HOME=/path/to/cache
uv run stt-daemon --model small