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
• Tray-Icon mit drei Zuständen: warten / aufnehmen / transkribieren

Systemabhängigkeiten

Linux (Arch / CachyOS)

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:

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 (Python-Paketmanager).

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.

• 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

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)

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

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/.

Lizenz

TBD