# Trixy Events — Referenz

Vollstaendige Uebersicht aller Events im Trixy-System.
Plugins koennen sich auf beliebige Events registrieren:

```python
@TrixyEvent(["event_name"])
async def on_event(self, event_name, event_data):
    pass
```

---

## System-Lifecycle

Events fuer den Start, Betrieb und Shutdown des Systems.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `application_starting` | System startet, Services werden geladen | `mode`, `version` | server/client/standalone |
| `application_ready` | Alle Services gestartet, System betriebsbereit | `mode`, `version`, `services_count` | server/client/standalone |
| `application_stopping` | Shutdown eingeleitet | `reason` | server/client/standalone |
| `system_shutdown` | System wird heruntergefahren (EventData) | `reason`, `source` | server/client/standalone |
| `service_started` | Ein Service wurde gestartet | `service_name`, `priority`, `group` | ServiceContainer |
| `service_stopped` | Ein Service wurde gestoppt | `service_name`, `reason` | ServiceContainer |
| `service_error` | Ein Service hat einen Fehler | `service_name`, `error`, `traceback` | ServiceContainer |

---

## Konnektivitaet (Online-Service)

Ueberwachung der Internet-Verbindung.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `online_status_changed` | Online-Status hat sich geaendert | `online`, `since`, `previous` | OnlineService |
| `connection_online` | Verbindung wiederhergestellt (war offline) | `online`, `since`, `offline_duration_seconds` | OnlineService |
| `connection_offline` | Verbindung verloren (war online) | `online`, `since`, `online_duration_seconds` | OnlineService |

---

## Satellite-Verwaltung

Events rund um Satellite-Verbindungen und -Verwaltung.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `satellite_connected` | Satellite hat sich verbunden (EventData) | `satellite_id`, `mac_address`, `room`, `alias` | NetworkService |
| `satellite_disconnected` | Satellite hat sich getrennt (EventData) | `satellite_id`, `room`, `reason` | NetworkService |
| `satellite_registered` | Neuer Satellite wurde registriert | `satellite_id`, `mac_address`, `alias` | SatelliteManager |
| `satellite_unregistered` | Satellite wurde entfernt | `satellite_id`, `alias` | SatelliteManager |
| `satellite_heartbeat_lost` | Heartbeat eines Satellites ausgefallen | `satellite_id`, `alias`, `last_seen` | SatelliteManager |
| `satellite_recording_started` | Server-gesteuerte Aufnahme gestartet (EventData) | `satellite_id`, `recording_id` | Satellite |
| `satellite_recording_stopped` | Server-gesteuerte Aufnahme beendet (EventData) | `satellite_id`, `recording_id`, `duration` | Satellite |
| `satellite_stream_started` | Audio-Stream gestartet (EventData) | `satellite_id`, `target_id` | Satellite |
| `satellite_stream_stopped` | Audio-Stream beendet (EventData) | `satellite_id`, `target_id` | Satellite |
| `client_connected` | Client hat sich zum Server verbunden | `host`, `port` | ClientApplication |
| `client_disconnected` | Client hat Verbindung verloren | `reason` | ClientApplication |

---

## Wakeword-Erkennung

Events rund um Wakeword-Detection und Aufnahme.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `wakeword_detected` | Wakeword erkannt | `satellite_id`, `model_name`, `confidence`, `audio_level`, `forced` | WakewordService |
| `wakeword_manual_trigger` | Manueller Trigger (HID Hook-Taste) | `device`, `forced` | HIDService |
| `wakeword_listening` | Wakeword-Erkennung ist aktiv | `satellite_id` | WakewordService |
| `wakeword_paused` | Wakeword-Erkennung pausiert | `satellite_id`, `reason` | WakewordService |
| `recording_started` | Audio-Aufnahme gestartet | `session_id`, `satellite_id` | WakewordService |
| `recording_stopped` | Audio-Aufnahme beendet | `session_id`, `satellite_id`, `duration_seconds`, `ended_by` | WakewordService |
| `raw_audio_received` | Roh-Audio empfangen (nach Aufnahme) | `session_id`, `audio_data`, `wakeword_type`, `duration_seconds` | WakewordService/AudioAccumulator |
| `recording_config_override` | Temporaere Aufnahme-Konfiguration | `silence_timeout`, `max_duration` | Plugin |

---

## Conversation (Dialog-Steuerung)

Events fuer Conversation-Sessions zwischen Satellite und Server.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `conversation_started` | Neue Conversation-Session begonnen | `satellite_id`, `conversation_id`, `arbitration_id` | Arbitrator |
| `conversation_ended` | Conversation-Session beendet | `conversation_id`, `satellite_id`, `duration_seconds`, `reason` | ConversationManager |
| `conversation_timeout` | Keine Antwort, Timeout | `conversation_id`, `satellite_id`, `timeout_seconds` | ConversationManager |
| `conversation_followup` | Rueckfrage gestartet | `conversation_id`, `satellite_id`, `followup_count` | WakewordService |
| `followup_expected` | System erwartet eine Rueckfrage-Antwort | `conversation_id` | IntentDispatcher |

---

## Sprache (STT — Speech-to-Text)

Events fuer die Spracherkennung.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `speech_recognized` | Sprache erkannt und transkribiert (EventData) | `text`, `confidence`, `language`, `satellite_id` | STT-Plugin |
| `stt_completed` | STT-Verarbeitung abgeschlossen | `text`, `confidence`, `provider`, `duration_ms` | STT-Plugin |
| `stt_error` | STT-Fehler | `error`, `provider` | STT-Plugin |

---

## NLP (Intent-Erkennung)

Events fuer die Verarbeitung natuerlicher Sprache.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `intent_received` | Intent erkannt (EventData) | `intent_name`, `confidence`, `text`, `slots` | NLP-Plugin |
| `intent_handled` | Intent wurde von Handler verarbeitet | `intent_name`, `handler`, `success`, `response_text` | IntentDispatcher |
| `create_output_text` | Antwort-Text soll generiert werden | `text`, `satellite_id` | IntentDispatcher |
| `output_text_created` | Antwort-Text wurde generiert (EventData) | `text`, `satellite_id` | NLP-Plugin |

---

## TTS (Text-to-Speech)

Events fuer die Sprachausgabe.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `tts_request` | TTS-Anfrage (EventData) | `text`, `satellite_id`, `voice` | Satellite/Plugin |
| `tts_completed` | TTS-Audio generiert | `audio_data`, `sample_rate`, `duration_seconds`, `provider` | TTS-Plugin |
| `tts_error` | TTS-Fehler | `error`, `provider`, `text` | TTS-Plugin |
| `tts_stop` | TTS-Wiedergabe stoppen | `satellite_id` | MusicService |

---

## Audio-Pipeline

Events fuer Audio-Ein-/Ausgabe und Verarbeitung.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `audio_input_received` | Audio-Daten vom Mikrofon empfangen | `session_id`, `audio_data` | NetworkService |
| `audio_output_received` | Audio-Daten fuer Lautsprecher | `audio_data`, `sample_rate` | Client |
| `audio_input_started` | Mikrofon-Aufnahme gestartet | `satellite_id`, `source` | AudioService |
| `audio_input_stopped` | Mikrofon-Aufnahme gestoppt | `satellite_id` | AudioService |
| `audio_level_changed` | Lautstaerke wurde geaendert | `volume`, `previous_volume`, `source` | AudioService |
| `audio_muted` | Audio stummgeschaltet | `source` | AudioService |
| `audio_unmuted` | Stummschaltung aufgehoben | `source` | AudioService |

---

## HID (Hardware-Eingabe)

Events von USB-HID-Geraeten (Konferenzmikrofone, Headsets).

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `volume_change` | Lautstaerke-Taste gedrueckt | `direction` (up/down), `step`, `device` | HIDService |
| `mute_toggle` | Stumm-Taste gedrueckt | `device` | HIDService |
| `playback_toggle` | Play/Pause-Taste gedrueckt | `device` | HIDService |

---

## Musik-Wiedergabe

Events fuer den Musik-Player.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `stream_start` | Musik-Stream gestartet (EventData) | `satellite_id`, `source`, `track` | MusicService |
| `stream_update` | Stream-Metadaten aktualisiert (EventData) | `satellite_id`, `position_ms` | MusicService |
| `stream_stop` | Musik-Stream gestoppt (EventData) | `satellite_id`, `reason` | MusicService |
| `music_play_pause` | Play/Pause umschalten | — | Client |
| `music_stop` | Musik stoppen | — | Client |
| `music_stopped` | Musik wurde gestoppt | — | Client |
| `music_next` | Naechster Track | `use_crossfade` | Client |
| `music_previous` | Vorheriger Track | — | Client |
| `music_paused` | Musik pausiert | — | Client |
| `music_resumed` | Musik fortgesetzt | — | Client |
| `music_volume_change` | Musik-Lautstaerke geaendert | `volume` | Client |
| `music_output_received` | Musik-Audio-Daten empfangen | `audio_data`, `sample_rate` | Client |
| `media_stop_all` | Alle Medien stoppen | — | Client |
| `media_stopped` | Alle Medien gestoppt | — | Client |

---

## Plugin-System

Events fuer den Plugin-Lifecycle.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `plugin_loaded` | Plugin wurde geladen (EventData) | `plugin_name`, `version` | PluginManager |
| `plugin_unloaded` | Plugin wurde entladen (EventData) | `plugin_name` | PluginManager |
| `plugin_error` | Plugin-Fehler (Exception) | `plugin_name`, `error`, `traceback` | PluginManager |
| `plugin_config_changed` | Plugin-Config geaendert (Hot-Reload) | `plugin_name`, `changes` | ConfigManager |

---

## Konfiguration

Events fuer Konfigurations-Aenderungen.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `config_loaded` | Konfigurationsdatei geladen | `path`, `config_type` | ConfigManager |
| `config_changed` | Konfigurationswert geaendert | `path`, `key`, `old_value`, `new_value` | ConfigManager |
| `config_saved` | Konfiguration gespeichert | `path` | ConfigManager |
| `config_error` | Konfigurationsfehler | `path`, `error` | ConfigManager |

---

## Scheduler

Events fuer geplante Aufgaben.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `scheduler_job_started` | Geplanter Job gestartet | `job_id`, `job_name` | SchedulerService |
| `scheduler_job_completed` | Geplanter Job abgeschlossen | `job_id`, `job_name`, `status`, `duration_ms` | SchedulerService |

---

## Downloads

Events fuer Datei-Downloads und -Extraktion.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `before_download` | Vor einem Download (abbrechbar) | `url`, `target_path` | DownloadUtils |
| `download_progress` | Download-Fortschritt | `url`, `downloaded_bytes`, `total_bytes` | DownloadUtils |
| `download_completed` | Download abgeschlossen | `url`, `target_path`, `size_bytes` | DownloadUtils |
| `download_failed` | Download fehlgeschlagen | `url`, `error` | DownloadUtils |
| `before_extract` | Vor dem Entpacken (abbrechbar) | `archive_path`, `target_dir` | DownloadUtils |
| `extract_completed` | Entpacken abgeschlossen | `archive_path`, `target_dir` | DownloadUtils |

---

## Sync / Daten

Events fuer Daten-Synchronisation.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `sync_completed` | Daten-Sync abgeschlossen | `data_type`, `count` | SyncService |
| `sync_item_received` | Einzelnes Sync-Item empfangen | `data_type`, `item_id` | SyncService |
| `sync_push_received` | Push-Sync empfangen | `data_type`, `source` | SyncService |

---

## Benutzer-Interaktion

Events fuer Benutzer-bezogene Aktionen.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `user_login` | Benutzer hat sich angemeldet | `username`, `satellite_id` | AdminPlugin |
| `user_identified` | Stimme wurde erkannt (Speaker Recognition) | `user_name`, `confidence`, `satellite_id` | VoiceRecognition |
| `notification_sent` | Benachrichtigung an Satellite gesendet | `satellite_id`, `text`, `sound` | NotificationService |
| `alarm_triggered` | Timer/Reminder ausgeloest | `alarm_id`, `type`, `satellite_id` | Timer/Reminder Plugin |

---

## Netzwerk

Events fuer Netzwerk-Kommunikation.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `network_message_received` | Netzwerk-Nachricht empfangen | `class_name`, `data` | Client/NetworkService |

---

## Monitoring / Fehler

Events fuer System-Ueberwachung.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `error_occurred` | Allgemeiner Fehler | `component`, `error`, `severity`, `traceback` | Beliebig |
| `health_check_failed` | Service Health-Check fehlgeschlagen | `service_name`, `error` | ServiceContainer |
| `disk_space_low` | Festplattenspeicher knapp (<500MB) | `free_mb`, `path` | OnlineService |
| `memory_high` | RAM-Nutzung kritisch (>90%) | `used_percent`, `used_mb`, `total_mb` | OnlineService |

---

## Training (ML)

Events fuer ML-Training.

| Event | Beschreibung | Daten | Quelle |
|-------|-------------|-------|--------|
| `training_started` | Training gestartet | `trainer_name`, `model_name` | TrainerService |
| `training_progress` | Training-Fortschritt | `trainer_name`, `epoch`, `loss`, `progress` | TrainerService |
| `training_completed` | Training abgeschlossen | `trainer_name`, `model_name`, `accuracy` | TrainerService |
| `training_failed` | Training fehlgeschlagen | `trainer_name`, `error` | TrainerService |
| `model_loaded` | ML-Modell geladen | `model_name`, `model_type`, `path` | ModelService |
| `model_unloaded` | ML-Modell entladen | `model_name`, `reason` | ModelService |

---

## Event-Typen

Trixy verwendet zwei Event-Mechanismen:

### emit() — Dict-basiert
```python
await events.emit("event_name", {"key": "value"})
```
Einfache Events mit freien Daten-Dicts. Koennen nicht abgebrochen werden.

### trigger() — EventData-basiert
```python
await events.trigger(EventDataObject)
```
Typisierte Events mit Dataclass-Objekten. Unterstuetzen:
- Abbrechbarkeit (cancellable)
- Prioritaets-basierte Handler-Reihenfolge
- Typsichere Felder

### Handler registrieren

```python
# Via Decorator (in Plugins)
@TrixyEvent(["speech_recognized", "stt_completed"])
async def on_speech(self, event_name, event_data):
    text = event_data.get("text", "")

# Via EventManager direkt
events.register("connection_online", self._on_back_online)
```

### Handler-Prioritaeten

| Prioritaet | Wert | Verwendung |
|-----------|------|------------|
| SYSTEM | 0 | Interne System-Handler |
| HIGHEST | 100 | Kritische Handler (z.B. STT-Korrektur) |
| HIGH | 200 | Vor-Verarbeitung |
| NORMAL | 500 | Standard (Plugins) |
| LOW | 800 | Nach-Verarbeitung |
| LOWEST | 900 | Logging, Monitoring |
| MONITOR | 1000 | Nur beobachten (nicht abbrechbar) |