118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
# Mikrofon-Monitor – Design-Spec
|
||
|
||
**Datum:** 2026-05-14
|
||
**Status:** Genehmigt
|
||
|
||
## Ziel
|
||
|
||
Die Anwendung soll erkennen, wenn Mikrofone im System hinzugefügt oder entfernt werden (USB, Bluetooth). Wenn das konfigurierte Mikrofon nicht mehr vorhanden ist, fällt die App automatisch auf das Standard-Mikrofon zurück und benachrichtigt den Nutzer.
|
||
|
||
## Verhalten
|
||
|
||
- **Konfiguriertes Mikrofon verschwindet:** Automatischer Fallback auf Standard-Mikrofon (`device = None`), Toast-Benachrichtigung + Tray-Tooltip-Warnung.
|
||
- **Konfiguriertes Mikrofon kehrt zurück:** Stellt das konfigurierte Gerät wieder her, Toast „Mikrofon wieder verbunden", Tray-Tooltip-Warnung entfernen.
|
||
- **Konfiguriertes Mikrofon fehlt bereits beim Start:** `on_configured_missing` sofort auslösen, nicht erst nach dem ersten Poll-Intervall.
|
||
- **Kein konfiguriertes Mikrofon (`device = None`):** Monitor läuft trotzdem, meldet nur `on_device_added` / `on_device_removed` (für zukünftige Erweiterungen), keine Fehlerbehandlung nötig.
|
||
|
||
## Neue Dateien
|
||
|
||
```
|
||
whisper_local/
|
||
microphone/
|
||
__init__.py # Protocol + create_monitor() Factory
|
||
_poll.py # Polling-Implementierung (Linux + Fallback)
|
||
_win32.py # IMMNotificationClient-Implementierung (Windows)
|
||
tray/
|
||
_notification.py # notify-py Toast-Wrapper
|
||
```
|
||
|
||
## Protocol
|
||
|
||
```python
|
||
class MicrophoneMonitor(Protocol):
|
||
on_device_added: Callable[[str], Awaitable[None]] | None
|
||
on_device_removed: Callable[[str], Awaitable[None]] | None
|
||
on_configured_missing: Callable[[], Awaitable[None]] | None
|
||
|
||
async def start(self) -> None: ...
|
||
def stop(self) -> None: ...
|
||
```
|
||
|
||
## Factory
|
||
|
||
```python
|
||
def create_monitor(configured_device: str | None) -> MicrophoneMonitor:
|
||
...
|
||
```
|
||
|
||
- Windows: versucht `Win32Monitor`; fällt bei COM-Fehler auf `PollMonitor` zurück.
|
||
- Alle anderen Plattformen: `PollMonitor`.
|
||
|
||
## Erkennungsmechanismus
|
||
|
||
### Windows: `Win32Monitor` (`_win32.py`)
|
||
|
||
- Registriert `IMMNotificationClient` bei `IMMDeviceEnumerator` via `comtypes`.
|
||
- Empfängt `OnDeviceAdded`, `OnDeviceRemoved`, `OnDeviceStateChanged` als COM-Callbacks.
|
||
- Übergibt Events per `loop.call_soon_threadsafe` in den asyncio-Loop (identisches Muster wie pynput-Hotkey-Callbacks).
|
||
- Wenn COM-Initialisierung fehlschlägt: transparenter Fallback auf `PollMonitor`.
|
||
|
||
### Cross-Platform: `PollMonitor` (`_poll.py`)
|
||
|
||
- Asyncio-Task mit `asyncio.sleep(2.5)` zwischen Prüfungen.
|
||
- Vergleicht aktuelle `sd.query_devices()`-Liste mit letztem Snapshot (Set aus Gerätenamen).
|
||
- Erkennt hinzugekommene und verschwundene Geräte, löst entsprechende Callbacks aus.
|
||
- Exceptions in `sd.query_devices()` werden geloggt und übersprungen — Loop läuft weiter.
|
||
|
||
## Benachrichtigung (`_notification.py`)
|
||
|
||
- Nutzt `notify-py` (cross-platform, aktiv gepflegt).
|
||
- Funktion `notify(title: str, message: str) -> None` — bei Fehler wird geloggt, nie blockierend.
|
||
- Neue Abhängigkeit: `notify-py` in `pyproject.toml` eintragen.
|
||
|
||
## Tray-Integration
|
||
|
||
`PystrayApp` erhält neue Methode:
|
||
|
||
```python
|
||
def set_warning(self, msg: str | None) -> None: ...
|
||
```
|
||
|
||
- `msg = None`: Icon-Titel zurück auf `"whisper-local"`.
|
||
- `msg = "..."`: Icon-Titel auf `"whisper-local ⚠ <msg>"`.
|
||
|
||
## App-Integration (`__main__.py`)
|
||
|
||
- `App.__init__`: erstellt `self.monitor = create_monitor(config.microphone)`.
|
||
- Callbacks registrieren:
|
||
- `on_configured_missing` → `recorder.device = None` + `notify(...)` + `tray.set_warning(...)`
|
||
- `on_device_added` → prüft ob konfiguriertes Gerät zurückgekehrt → `recorder.device = config.microphone` + `notify(...)` + `tray.set_warning(None)`
|
||
- `App.run()`: startet `monitor.start()` als asyncio-Task parallel zum Hotkey-Listener.
|
||
- `_on_config_reload`: stoppt alten Monitor, erstellt neuen mit aktualisierten Gerätedaten.
|
||
|
||
## Fehlerbehandlung
|
||
|
||
| Situation | Verhalten |
|
||
|-----------|-----------|
|
||
| COM-Init schlägt fehl (Windows) | Transparenter Fallback auf `PollMonitor` |
|
||
| `sd.query_devices()` wirft Exception | Loggen + überspringen, Loop läuft weiter |
|
||
| `notify-py` wirft Exception | Loggen + ignorieren, nie blockierend |
|
||
| Konfiguriertes Mikrofon fehlt beim Start | Sofort `on_configured_missing` auslösen |
|
||
|
||
## Tests
|
||
|
||
- `tests/test_microphone_monitor.py`:
|
||
- `PollMonitor` mit gemocktem `sd.query_devices()`.
|
||
- Prüft: `on_device_added` wird ausgelöst wenn Gerät erscheint.
|
||
- Prüft: `on_device_removed` wird ausgelöst wenn Gerät verschwindet.
|
||
- Prüft: `on_configured_missing` wird sofort beim Start ausgelöst wenn Gerät fehlt.
|
||
- `Win32Monitor`-Tests nur auf Windows (`@pytest.mark.skipif(sys.platform != "win32", ...)`), COM-Interface gemockt.
|
||
- `_notification.py`: kein eigener Test (trivialer Wrapper).
|
||
|
||
## Abhängigkeiten
|
||
|
||
| Paket | Zweck | Plattform |
|
||
|-------|-------|-----------|
|
||
| `notify-py` | Desktop-Toast-Benachrichtigungen | alle |
|
||
| `comtypes` | COM-Interface für IMMNotificationClient | Windows (bereits transitiv vorhanden via pywinrt) |
|