# 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:**
```bash
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:

```bash
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:

```bash
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:

```bash
uv sync --extra portaudio
```

Then verify available devices:

```bash
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:

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