voice-agent/windows-dictate/README.md

Voice-Agent — Windows-Diktat

Kleiner Push-to-Talk-Client für Windows. Hotkey halten = aufnehmen, loslassen = an den Mac-Worker schicken, Text wird am Cursor eingefügt.

Läuft als Tray-Icon (blau = Idle, rot = Aufnahme, orange = sende, grau = Fehler). Nutzt direkt den bestehenden POST /api/transcribe-Endpoint vom Mac-Worker — keine Server-Änderung nötig.

Voraussetzungen

• Windows 10/11
• Python 3.11+ (tomllib und neuere numpy)
• Erreichbarkeit des Mac-Workers im internen Netz (Standard: http://10.172.100.44:8080)

Schnellstart (entwickeln)

cd windows-dictate
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy config.example.toml config.toml
notepad config.toml
python dictate.py

Im Tray erscheint ein blauer Punkt. Cursor in ein Eingabefeld setzen, F8 halten, sprechen, loslassen — nach 1–3 s steht der Text drin.

Standalone-EXE bauen

pip install pyinstaller
build.bat

Ergebnis: dist\VoiceAgentDictate.exe. Daneben eine config.toml ablegen.

Konfig (config.toml)

Key	Default	Bedeutung
mac_url	http://10.172.100.44:8080	URL des Mac-Workers
hotkey	f8	Push-to-Talk-Taste (einzelne Taste, halten)
language	de	Whisper-Sprache
timeout	120	Sekunden für den Mac-Call
suppress_hotkey	false	Hotkey vor anderen Apps abfangen

Tray-Menü

Rechtsklick auf das Tray-Icon → Beenden.

Hotkey-Hinweise

• keyboard unterstützt einzelne Tasten für press/release sauber. Kombis wie Ctrl+Win+Space brauchen eine andere Logik (Toggle statt Push-to-Talk).
• Falls F8 mit etwas kollidiert (z.B. Browser-Slideshow), in der Konfig auf pause, scroll lock, f9, f12 o.ä. wechseln.
• suppress_hotkey = true schluckt die Taste vollständig — nur einschalten, wenn die Taste sonst nicht gebraucht wird.

Was es nicht macht

• Kein Live-Streaming Wort-für-Wort. Du sprichst einen Block, dann erscheint der Block. Realistisch sind 3–8 s pro Diktat-Block.
• Keine Authentifizierung — der Mac-Worker hat selbst keine. Nur im internen Netz nutzen.
• Keine Audio-Vorverarbeitung. Mikro-Auswahl macht Windows selbst (Standard-Aufnahmegerät).

Upgrade-Pfad: echtes Streaming

Wenn Du später Wort-für-Wort willst, müsste der Mac-Worker lightning-whisper-mlx durch eine Streaming-Variante ersetzen — Kandidaten:

• whisper-streaming (https://github.com/ufal/whisper_streaming) — Wrapper um faster-whisper mit LocalAgreement-Policy. Gibt partielle Transkripte alle 0.5–2 s.
• whisper.cpp --stream — sehr leichtgewichtig, aber CPU statt MLX.
• wav2vec2 / Vosk — echtes Streaming, schwächer als Whisper bei deutschem Audio.

Auf Client-Seite würde sich dann WebSocket statt POST anbieten, plus eine „partial vs final"-Logik (partial löschen + neuen Text einfügen). Größerer Umbau — aktuell bewusst nicht gemacht, weil der Push-to-Talk-Workflow für Diktat in Office/Mail/Chat in der Praxis sehr gut funktioniert.

Troubleshooting

• Hotkey reagiert nicht: keyboard braucht keine Admin-Rechte zum Lesen, aber suppress_hotkey = true schon. Erst mit false testen.
• OSError: PortAudio bei Start: Standard-Aufnahmegerät in Windows-Sound-Settings setzen.
• Fehler-Icon (grau) + Log Mac-Fehler: ConnectionError: Mac aus, falsche IP in config.toml, oder Firewall blockt 8080.
• Text erscheint nicht im Zielfenster: einige Apps (manche Terminals) blocken simuliertes Strg+V. Test in Notepad.
• Sonderzeichen verstümmelt: Ziel-App unterstützt Unicode-Paste nicht. Workaround: in dictate.py keyboard.send("ctrl+v") durch keyboard.write(text) ersetzen (langsamer, aber tastenweise).