whisper-local/README.md

# whisper-local

Lokales Speech-to-Text mit globalem Hotkey. Hotkey halten → Sprechen → loslassen → faster-whisper transkribiert lokal → Text wird ins aktive Textfeld eingefügt. Kein Netzwerk, kein Cloud-Service.

Läuft als Hintergrunddienst mit Tray-Icon auf **Linux (KDE Plasma / Wayland)** und **Windows 10/11**.

## Features

- Systemweiter Hotkey (Standard: `F12`), konfigurierbar über den Einstellungs-Dialog im Tray
- Einfügen ins aktive Textfeld unabhängig von der Anwendung (Browser, Terminal, IDE …)
- Mikrofon-Auswahl über Tray-Einstellungen
- Mikrofon-Verbindungsüberwachung: automatischer Fallback auf Standard-Mikrofon wenn das konfigurierte Gerät getrennt wird, Toast-Benachrichtigung + Tray-Warnung
- Lokale Transkription via [faster-whisper](https://github.com/SYSTRAN/faster-whisper)
- Tray-Icon mit drei Zuständen: warten / aufnehmen / transkribieren

## Systemabhängigkeiten

### Linux (Arch / CachyOS)

```bash
sudo pacman -S ydotool wl-clipboard libayatana-appindicator gobject-introspection
```

- `ydotool` — simuliert Tastatureingaben unter Wayland (Text-Einfügen via `Ctrl+V`)
- `wl-clipboard` — Clipboard-Zugriff unter Wayland (`wl-copy`)
- `libayatana-appindicator` + `gobject-introspection` — Tray-Icon über StatusNotifierItem (KDE/Wayland)

Damit `ydotool` ohne `sudo` funktioniert, muss der `ydotoold`-Daemon laufen und der Benutzer in der `input`-Gruppe sein:

```bash
sudo systemctl enable --now ydotool
sudo usermod -aG input $USER
# Neu-Login nötig
```

Der Benutzer braucht außerdem Lesezugriff auf `/dev/input/event*`, was die `input`-Gruppen-Mitgliedschaft abdeckt.

### Windows

Keine System-Dependencies. `pynput` und `pywin32` werden automatisch via uv installiert.

## Installation

Voraussetzung: [uv](https://github.com/astral-sh/uv) (Python-Paketmanager).

```bash
git clone <repo-url> whisper-local
cd whisper-local
uv sync
```

`uv sync` installiert plattformspezifisch:

- **Linux**: `evdev`, `PyGObject`, `pystray`, `Pillow`, `sv-ttk`, `darkdetect`, `notify-py`
- **Windows**: `pynput`, `pywin32`, `comtypes`, `pystray`, `Pillow`, `sv-ttk`, `darkdetect`, `notify-py`

## Konfiguration

Die Konfigurationsdatei wird beim ersten Start angelegt. Vorlage: [config.example.toml](config.example.toml).

- **Linux**: `~/.config/whisper-local/config.toml`
- **Windows**: `%APPDATA%\whisper-local\config.toml`

Hotkey und Mikrofon lassen sich auch direkt über den Einstellungs-Dialog im Tray ändern (Rechtsklick aufs Tray-Symbol → „Einstellungen"). Änderungen greifen sofort ohne Neustart.

Key-Namen folgen dem evdev-Format (`KEY_F12`, `KEY_LEFTSHIFT`, …) — auch unter Windows.

## Starten

```bash
uv run whisper-local
```

Beim ersten Start lädt faster-whisper das Whisper-Modell (Standard: `small`) herunter. Danach erscheint das Tray-Icon und der Hotkey ist aktiv.

### Autostart unter Linux (systemd user unit)

```bash
mkdir -p ~/.config/systemd/user
cp systemd/whisper-local.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now whisper-local.service
```

Das `whisper-local`-Executable muss dafür in `~/.local/bin` verfügbar sein (`uv tool install .` oder Pfad in der Unit anpassen).

## Entwicklung

```bash
uv run pytest                    # Tests
uv run python -m whisper_local   # Direkt starten
```

Plattform-spezifische Tests werden über `@pytest.mark.skipif(sys.platform != ...)` übersprungen.

Architektur- und Designdokumente liegen unter [docs/superpowers/](docs/superpowers/).

## Lizenz

TBD