ViewIT/docs/PLUGIN_SYSTEM.md

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.

Aktuelle Plugins

• serienstream_plugin.py – Serienstream (s.to)
• topstreamfilm_plugin.py – Topstreamfilm
• einschalten_plugin.py – Einschalten
• aniworld_plugin.py – Aniworld
• _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.