Voice Overlay Lifecycle auf macOS meistern

Kennst du das? Du baust ein UI-Element, das auf verschiedene Inputs gleichzeitig reagiert, und plötzlich überschreiben sich die Zustände gegenseitig. Besonders bei Voice-Interfaces ist das frustrierend: Ein Wake-Word öffnet das Overlay, aber sobald du eine Taste für Push-to-Talk drückst, verschwindet der bisherige Text oder die Session verhält sich unvorhersehbar.

Diese Inkonsistenzen entstehen oft durch Callbacks, die zu spät eintreffen oder den aktuellen Kontext nicht kennen. Hier erfährst du, wie du den Lifecycle des Voice Overlays stabil hältst.

Voraussetzungen

• macOS App Codebase (für Contributors)
• Zugriff auf SwiftUI-Komponenten
• Berechtigung für CLI-Logging

Schnellstart

Das Ziel ist ein vorhersehbares Verhalten, wenn Wake-Word und Push-to-Talk (PTT) überlappen. Seit dem Update vom 9. Dezember 2025 nutzen wir dafür ein Token-basiertes System.

1. Token-Management: Jede Capture-Session erhält ein eindeutiges Token. Wenn der VoiceSessionCoordinator ein Update (Partial/Final) erhält, dessen Token nicht mehr aktuell ist, wird der Callback verworfen.
2. Session Adoption: Wenn das Overlay bereits durch ein Wake-Word aktiv ist und du den Hotkey für PTT drückst, übernimmt die PTT-Session den vorhandenen Text. Das Overlay bleibt sichtbar, solange du den Hotkey hältst.
3. Unified Send Path: Beim Loslassen der Taste (endCapture) wird geprüft: Ist Text vorhanden? Falls ja, wird performSend ausgeführt. Falls der Text leer ist, wird das Overlay ohne Aktion geschlossen.
4. Cooldown: Nach Abschluss einer PTT-Session wird ein kurzer Cooldown auf die Wake-Word-Erkennung angewendet, um ein sofortiges erneutes Triggern zu verhindern.

Fehlerbehebung

Wenn das Overlay “klebt” oder sich seltsam verhält, kannst du die Logs in Echtzeit streamen. Nutze diesen Befehl im Terminal, um die Events zu analysieren:

sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"' --level info --style compact

Achte auf folgende Punkte:

• Prüfe, ob nur ein Session-Token gleichzeitig aktiv ist.
• Stelle sicher, dass das Loslassen von Push-to-Talk immer endCapture mit dem aktiven Token aufruft.
• Verifiziere, dass bei leerem Text dismiss ohne Chime oder Send-Aktion erfolgt.

AI Setup Assistant

Nächste Schritte

• VoiceSessionCoordinator (actor): Zentrale Instanz für das Session-Management.
• VoiceSession (model): Speichert Token, Source und Text-Status.
• Overlay binding: Synchronisation mit SwiftUI über den VoiceSessionPublisher.
• Logging: Details zu voicewake.overlay und voicewake.chime.