events.md 15 KB
Trixy Events — Referenz
Vollstaendige Uebersicht aller Events im Trixy-System. Plugins koennen sich auf beliebige Events registrieren:
@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
await events.emit("event_name", {"key": "value"})
Einfache Events mit freien Daten-Dicts. Koennen nicht abgebrochen werden.
trigger() — EventData-basiert
await events.trigger(EventDataObject)
Typisierte Events mit Dataclass-Objekten. Unterstuetzen:
- Abbrechbarkeit (cancellable)
- Prioritaets-basierte Handler-Reihenfolge
- Typsichere Felder
Handler registrieren
# 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) |