## ViewIt Plugin-System

Dieses Dokument beschreibt, wie das Plugin-System von **ViewIt** funktioniert und wie die Community neue Integrationen hinzufügen kann.

### Überblick

ViewIt lädt Provider-Integrationen dynamisch aus `addon/plugins/*.py`. Jede Datei enthält eine Klasse, die von `BasisPlugin` erbt. Beim Start werden alle Plugins instanziiert und nur aktiv genutzt, wenn sie verfügbar sind.

Weitere Details:
- `docs/DEFAULT_ROUTER.md` (Hauptlogik in `addon/default.py`)
- `docs/PLUGIN_DEVELOPMENT.md` (Entwicklerdoku für Plugins)

### Aktuelle Plugins

- `serienstream_plugin.py` – Serienstream (s.to)
- `topstreamfilm_plugin.py` – Topstreamfilm
- `einschalten_plugin.py` – Einschalten
- `aniworld_plugin.py` – Aniworld
- `filmpalast_plugin.py` – Filmpalast
- `_template_plugin.py` – Vorlage für neue Plugins

### Plugin-Discovery (Ladeprozess)

Der Loader in `addon/default.py`:

1. Sucht alle `*.py` in `addon/plugins/`
2. Überspringt Dateien, die mit `_` beginnen
3. Lädt Module dynamisch
4. Instanziert Klassen, die von `BasisPlugin` erben
5. Ignoriert Plugins mit `is_available = False`

Damit bleiben fehlerhafte Plugins isoliert und blockieren nicht das gesamte Add-on.

### BasisPlugin – verpflichtende Methoden

Definiert in `addon/plugin_interface.py`:

- `async search_titles(query: str) -> list[str]`
- `seasons_for(title: str) -> list[str]`
- `episodes_for(title: str, season: str) -> list[str]`

### Optionale Features (Capabilities)

Plugins können zusätzliche Features anbieten:

- `capabilities() -> set[str]`
  - `popular_series`: liefert beliebte Serien
  - `genres`: Genre-Liste verfügbar
  - `latest_episodes`: neue Episoden verfügbar
- `popular_series() -> list[str]`
- `genres() -> list[str]`
- `titles_for_genre(genre: str) -> list[str]`
- `latest_episodes(page: int = 1) -> list[LatestEpisode]` (wenn angeboten)

ViewIt zeigt im UI nur die Features an, die ein Plugin tatsächlich liefert.

### Plugin-Struktur (empfohlen)

Eine Integration sollte typischerweise bieten:

- Konstante `BASE_URL`
- `search_titles()` mit Provider-Suche
- `seasons_for()` und `episodes_for()` mit HTML-Parsing
- `stream_link_for()` optional für direkte Playback-Links
- Optional: `available_hosters_for()` oder Provider-spezifische Helfer

Als Startpunkt dient `addon/plugins/_template_plugin.py`.

### Community-Erweiterungen (Workflow)

1. Fork/Branch erstellen
2. Neue Datei unter `addon/plugins/` hinzufügen (z. B. `meinprovider_plugin.py`)
3. Klasse erstellen, die `BasisPlugin` implementiert
4. In Kodi testen (ZIP bauen, installieren)
5. PR öffnen

### Qualitätsrichtlinien

- Keine Netzwerkzugriffe im Import-Top-Level
- Netzwerkzugriffe nur in Methoden (z. B. `search_titles`)
- Fehler sauber abfangen und verständliche Fehlermeldungen liefern
- Kein globaler Zustand, der across instances überrascht
- Provider-spezifische Parser in Helper-Funktionen kapseln

### Debugging & Logs

Hilfreiche Logs werden nach `userdata/addon_data/plugin.video.viewit/logs/` geschrieben.
Provider sollten URL-Logging optional halten (Settings).

### ZIP-Build

```
./scripts/build_kodi_zip.sh
```

Das ZIP liegt anschließend unter `dist/plugin.video.viewit-<version>.zip`.