# Local STT (Whisper) Setup on ZimaOS

Setting up local voice-to-text transcription on ZimaOS/CasaOS requires redirecting the cache directory. The default `HF_HOME` falls on a root-owned path.

## Problem

When a Telegram voice message arrives, Hermes tries to load the `faster-whisper` model. By default:
- `HF_HOME` resolves to `~/.cache/huggingface` → `/DATA/AppData/.cache/huggingface`
- `/DATA/AppData/.cache` is owned by `root`
- The model download fails with `PermissionError: [Errno 13]`

## Solution

Redirect all cache directories into the Hermes writable tree.

### 1. Create directories

```bash
mkdir -p /DATA/AppData/hermes/.cache/huggingface
mkdir -p /DATA/AppData/hermes/.cache/whisper
```

### 2. Update `.env`

Add to `~/.hermes/.env` (or `/DATA/AppData/hermes/.env` on ZimaOS):
```
HF_HOME=/DATA/AppData/hermes/.cache/huggingface
WHISPER_CACHE_DIR=/DATA/AppData/hermes/.cache/whisper
XDG_CACHE_HOME=/DATA/AppData/hermes/.cache
```

### 3. Ensure faster-whisper is importable

```bash
/DATA/AppData/hermes/venv/bin/python3 -c "import faster_whisper; print('OK')"
```

If missing: `pip install faster-whisper`

### 4. Pre-download the model

```python
from faster_whisper import WhisperModel
import os

os.environ["HF_HOME"] = "/DATA/AppData/hermes/.cache/huggingface"
model = WhisperModel("base", device="cpu", compute_type="int8",
                     download_root="/DATA/AppData/hermes/.cache/whisper")
```

### 5. Config stanza

```yaml
stt:
  enabled: true
  provider: local
  local:
    model: base
```

### 6. Restart gateway

The `HF_HOME` env var is read at process startup.

## Pitfalls

- **Sandbox PATH**: Python `os.makedirs()` works; shell `mkdir` may not be in PATH. Always use Python for file ops.
- **Model choice**: `base` is the sweet spot for DE/EN/TR on CPU.