whisper-local/CLAUDE.md

whisper-local

Lokales Speech-to-Text-Tool: Hotkey halten → Audio aufnehmen → faster-whisper transkribieren → Text einfügen.

Entwicklungsumgebung

• Python 3.13+, Paketmanager: uv (Lock-File: uv.lock)
• Python-Scripts direkt ausführen: uv run python <script.py>
• Tests: uv run pytest (mit pytest-asyncio für async-Tests)
• Starten: uv run whisper-local

Sprache

• Entwicklungs- und Dokumentationssprache: Deutsch (Code-Bezeichner bleiben Englisch)

Architektur

• Plattform-Dispatch via Factory-Funktionen: create_listener() / create_inserter()
• Linux: evdev (Hotkey) + ydotool/wl-copy (Wayland-Inserter)
• Windows: pynput (Hotkey) + pywin32 Clipboard + Ctrl+V (Win32-Inserter)
• Interfaces als typing.Protocol — keine abstrakte Basisklasse

Wichtige Muster

• Hotkey-Key-Namen im evdev-Format (KEY_F12), auch auf Windows — _pynput.py übersetzt intern
• Key-Repeat-Unterdrückung im pynput-Backend: _pressed-Flag verhindert Doppelevents
• Async-Callbacks (on_press, on_release) via asyncio.get_running_loop().call_soon_threadsafe

Konfiguration

• Linux: ~/.config/whisper-local/config.toml
• Windows: %APPDATA%\whisper-local\config.toml
• Vorlage: config.example.toml

Tests

• Plattform-spezifische Tests mit @pytest.mark.skipif(sys.platform != "linux", ...)
• Async-Callbacks mit unittest.mock.AsyncMock mocken