System-Architektur

Revision: r2 Source: CLAUDE.md, Code-Analyse Last updated: 2026-04-10 14:00

Betriebsmodi

Modus	Beschreibung	Einstiegspunkt
Server	Zentrale Steuerung: Satellites, Plugins, Events, ML-Inferenz	`python3 main.py server`
Client	Leichtgewichtiger Satellite mit Wakeword-Erkennung	`python3 main.py client`
Standalone	All-in-One ohne Server	`python3 main.py standalone`
Train	ML-Trainer fuer Wakeword/Voice-Recognition/Intent	`python3 main.py train`

Service Container Pattern

Alle Hauptkomponenten erben von IService:

class IService(ABC):
    PRIORITY: ServicePriority  # CRITICAL, CORE, NETWORK, MANAGER, PLUGIN, OPTIONAL
    GROUP: ServiceGroup        # Kategorisierung
    DEPENDENCIES: list[str]    # Erforderliche Services

    # Lifecycle Hooks
    async def on_pre_start() -> None
    async def on_post_start() -> None
    async def on_pre_stop() -> None
    async def on_post_stop() -> None
    async def on_dependency_ready(name: str) -> None

    # Abstrakte Methoden
    @abstractmethod
    async def start() -> None
    @abstractmethod
    async def stop() -> None

    # Optional
    async def health_check() -> bool

Startreihenfolge: Prioritaetsbasiert (niedrigerer Wert = frueher), mit Abhaengigkeitsaufloesung.

Event-Driven System

Zentrales Pub/Sub mit Prioritaeten:

Prioritaet	Wert	Verwendung
SYSTEM	0	Kann Events abbrechen
HIGHEST	10	Hoechste Benutzer-Prioritaet
HIGH	20	Hohe Prioritaet
NORMAL	30	Standard
LOW	40	Niedrige Prioritaet
LOWEST	50	Niedrigste Prioritaet
MONITOR	100	Nur beobachten, empfaengt auch abgebrochene Events

@TrixyEvent(["wakeword_received", "satellite_connected"])
def on_events(self, event_name: str, event_data: EventData):
    pass

EventManager: register() fuer Callbacks, emit() fuer dict-basierte Events, trigger() fuer EventData-basierte Events.

Netzwerk-Architektur

Trixy-Protokoll (5 Ports)

Port	Socket	Richtung	Format
2101	Command	Bidirektional	AES-256-GCM verschluesselt
2102	Audio In	Satellite -> Server	16KHz mono PCM
2103	Audio Out	Server -> Satellite	16KHz mono PCM
2104	Music	Server -> Satellite	48KHz stereo
2105	Config	Config-Tool -> Server	AES-256-GCM verschluesselt

Config-Tool (Port 2105)

Separates TUI-Programm (trixy_core/config_app.py) das sich remote mit dem Server verbindet:

ConfigApplication — Eigenstaendige Textual-App (erbt NICHT von IApplication)
ConfigListener (IService) — Server-seitig, nimmt Config-Tool-Verbindungen an
Ermoeglicht: Status abfragen, Config aendern, Satellite-Audio steuern, Geraete auflisten

Audio-Architektur

Volume-Control (ALSA)

trixy_core/audio/volume.py — System-weite Lautstaerke via ALSA amixer
Quellenbasierte Persistenz: nur "user"/"hid" Aenderungen werden in Config gespeichert
Unterstuetzt Playback und Capture Channels

Multi-Speaker (PulseAudio/PipeWire)

trixy_core/audio/pulse_combined.py — Virtueller Combined-Sink
module-combine-sink vereint mehrere Lautsprecher zu einem Ausgang
Kompatibel mit Linux Pulse/PipeWire und WSL2-WSLg

Multi-Microphone (PulseAudio/PipeWire)

trixy_core/audio/pulse_mic_mix.py — Virtueller Mic-Mix
Null-Sink + Loopback-Module mischen mehrere Mikrofone zu einer Quelle
Fuer Wakeword-Erkennung: alle Mics gleichzeitig abhoeren

Tech Stack

Sprache: Python 3.10+
ML Framework: PyTorch, ONNX Runtime (Inferenz auf Pi)
Audio: 16KHz, 16-bit PCM mono; ALSA + PulseAudio/PipeWire
Features: Log-Mel-Spectrogram
Verschluesselung: AES-256-GCM
TUI: Textual (Server-TUI + Config-Tool + Installer)
Installer: Textual-basierte TUI mit Bookworm-kompatiblem Setup

See also: modules.md, integrations.md

architecture.md 4.0 KB Lịch sử Raw