# Design: Tray-Icon mit Einstellungs-Dialog

**Datum:** 2026-04-10  
**Plattform:** Windows (Linux-Support folgt später)

## Übersicht

whisper-local erhält ein Tray-Icon in der Windows-Taskleiste, das den aktuellen App-Zustand anzeigt. Per Rechtsklick-Menü kann der Nutzer Einstellungen öffnen oder die App beenden.

## Zustände & Icons

Drei Zustände werden über ein Mikrofon-Symbol mit Farbe unterschieden:

| Zustand | Farbe | Bedeutung |
|---|---|---|
| `WAITING` | Grau | Warte auf Hotkey-Druck |
| `RECORDING` | Rot | Aufnahme läuft |
| `TRANSCRIBING` | Gelb | Transkription läuft |

Icons werden programmatisch via `Pillow` generiert — keine Bilddateien im Repository.

## Modulstruktur

Neues Package `whisper_local/tray/`:

```
whisper_local/tray/
├── __init__.py        # create_tray() Factory
├── _icon.py           # Icon-Generierung (Pillow, 3 Zustände)
├── _tray.py           # Win32TrayApp: pystray-Integration, AppState-Enum, Menü
├── _settings.py       # SettingsDialog: tkinter + sv-ttk
└── _theme.py          # System-Theme-Erkennung (darkdetect) + sv-ttk anwenden
```

`create_tray()` gibt auf Linux ein No-Op-Stub zurück, sodass der Rest der App plattformunabhängig bleibt.

## AppState-Enum

```python
class AppState(enum.Enum):
    WAITING      = "waiting"
    RECORDING    = "recording"
    TRANSCRIBING = "transcribing"
```

## Tray-Integration (`_tray.py`)

- `pystray.Icon` läuft in einem eigenen Thread (Pflicht bei pystray).
- Rechtsklick-Menü: **Einstellungen** | **Beenden**
- „Beenden" ruft `loop.call_soon_threadsafe(loop.stop)` auf, um den asyncio-Loop sauber zu stoppen.
- `set_state(AppState)` tauscht das Icon aus; thread-sicher via `icon.icon = ...`.

## Einstellungs-Dialog (`_settings.py`)

Der Dialog öffnet sich in einem dedizierten Thread. Änderungen werden erst bei „Speichern" übernommen.

### Felder

**Hotkey**
- Button „Aufzeichnen": Klick aktiviert Lausch-Modus; nächste Tastenbetätigung wird als neuer Hotkey übernommen und im evdev-Format (`KEY_F12`) gespeichert.
- Direkt darunter: Konflikt-Warnung (oranges Label), falls die Taste bereits von einer anderen App via Win32-`RegisterHotKey` belegt ist.
- Hinweis: Apps mit Low-Level-Hooks (wie whisper-local selbst) können nicht erkannt werden.

**Mikrofon**
- Dropdown, befüllt via `sounddevice.query_devices()`.
- Zeigt Gerätename + Index; speichert den Gerätenamen in `config.toml`.

### Buttons

`Speichern` — übernimmt Änderungen in `config.toml` und löst Config-Reload aus  
`Abbrechen` — verwirft Änderungen

### Konflikt-Erkennung

`ctypes.windll.user32.RegisterHotKey(None, id, 0, vk)` wird kurz aufgerufen und sofort mit `UnregisterHotKey` rückgängig gemacht. Schlägt `RegisterHotKey` fehl, ist die Taste belegt.

## Theme-Support (`_theme.py`)

- `darkdetect.theme()` liest das aktive Windows-System-Theme (`"Light"` / `"Dark"`).
- `sv_ttk.set_theme("light"/"dark")` wird beim Öffnen des Dialogs angewendet.
- Das Theme wird bei jedem Dialog-Öffnen neu gelesen (kein Live-Update während die App läuft).

## Abhängigkeiten

Neue Einträge in `pyproject.toml` (alle Windows-only):

```toml
"pystray>=0.19.0; sys_platform == 'win32'",
"Pillow>=10.0.0; sys_platform == 'win32'",
"sv-ttk>=2.6.0; sys_platform == 'win32'",
"darkdetect>=0.8.0; sys_platform == 'win32'",
```

## Integration in `App` (`__main__.py`)

```python
self.tray = create_tray(on_settings=self._open_settings, on_quit=self._quit)

async def on_press(self):
    self.tray.set_state(AppState.RECORDING)
    self.recorder.start()

async def on_release(self):
    audio = self.recorder.stop()
    self.tray.set_state(AppState.TRANSCRIBING)
    text = self.transcriber.transcribe(audio)
    await self.inserter.insert(text)
    self.tray.set_state(AppState.WAITING)

async def run(self):
    self.tray.start()
    await self.hotkey.listen()
```

## Config-Reload

Nach „Speichern" im Dialog ruft `SettingsDialog` einen übergebenen Callback auf. `App` initialisiert daraufhin `PynputHotkeyListener` und `Recorder` mit den neuen Werten neu — kein Neustart der App erforderlich.

## Testing

- `_icon.py`: Unit-Test prüft, dass für jeden `AppState` ein PIL-Image zurückgegeben wird.
- `_tray.py`: `set_state()` mit gemocktem `pystray.Icon` testen.
- `_settings.py`: Konflikt-Erkennung mit gemocktem `ctypes.windll` testen; Config-Reload-Callback testen.
- Tray-Tests mit `@pytest.mark.skipif(sys.platform != "win32", ...)` markieren.