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.

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
• dokustreams_plugin.py – Doku-Streams
• _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. Nutzt Plugin = <Klasse> als bevorzugten Einstiegspunkt (falls vorhanden)
5. Fallback: instanziert Klassen, die von BasisPlugin erben (deterministisch sortiert)
6. 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]
• optional metadata_for(title: str) -> (info_labels, art, cast)

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
• new_titles: neue Titel verfügbar
• alpha: A-Z Index verfügbar
• series_catalog: Serienkatalog 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)
• new_titles_page(page: int = 1) -> list[str] (wenn angeboten)
• alpha_index() -> list[str] (wenn angeboten)
• series_catalog_page(page: int = 1) -> list[str] (wenn angeboten)

Metadaten:

• prefer_source_metadata = True bedeutet: Plugin-Metadaten gehen vor TMDB, TMDB dient nur als Fallback.

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
• metadata_for() optional für Plot/Poster aus der Quelle
• 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 über Instanzen hinweg überrascht
• Provider-spezifische Parser in Helper-Funktionen kapseln
• Reproduzierbare Reihenfolge: Plugin-Alias nutzen oder Klassenname eindeutig halten

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.