ViewIT/docs/PLUGIN_DEVELOPMENT.md

ViewIT – Entwicklerdoku Plugins (addon/plugins/*_plugin.py)

Diese Doku beschreibt, wie Plugins im ViewIT‑Addon aufgebaut sind und wie neue Provider‑Integrationen entwickelt werden.

Grundlagen

• Jedes Plugin ist eine einzelne Datei unter addon/plugins/.
• Dateinamen ohne _‑Prefix werden automatisch geladen.
• Jede Datei enthält eine Klasse, die von BasisPlugin erbt.
• Optional: Plugin = <Klasse> als expliziter Einstiegspunkt (bevorzugt vom Loader).

Pflicht‑Methoden (BasisPlugin)

Jedes Plugin muss diese Methoden implementieren:

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

Vertrag Plugin ↔ Hauptlogik (default.py)

Die Hauptlogik ruft Plugin-Methoden auf und verarbeitet ausschließlich deren Rückgaben.

Wesentliche Rückgaben an die Hauptlogik:

• search_titles(...) → Liste von Titel-Strings für die Trefferliste
• seasons_for(...) → Liste von Staffel-Labels
• episodes_for(...) → Liste von Episoden-Labels
• stream_link_for(...) → Hoster-/Player-Link (nicht zwingend finale Media-URL)
• resolve_stream_link(...) → finale/spielbare URL nach Redirect/Resolver
• metadata_for(...) → Info-Labels/Art (Plot/Poster) aus der Quelle
• Optional available_hosters_for(...) → auswählbare Hoster-Namen im Dialog
• Optional series_url_for_title(...) → stabile Detail-URL pro Titel für Folgeaufrufe
• Optional remember_series_url(...) → Übernahme einer bereits bekannten Detail-URL

Standard für Film-Provider (ohne echte Staffeln):

• seasons_for(title) gibt ["Film"] zurück
• episodes_for(title, "Film") gibt ["Stream"] zurück

Optionale Features (Capabilities)

Über capabilities() kann das Plugin zusätzliche Funktionen anbieten:

• popular_series → popular_series()
• genres → genres() + titles_for_genre(genre)
• latest_episodes → latest_episodes(page=1)
• new_titles → new_titles_page(page=1)
• alpha → alpha_index() + titles_for_alpha_page(letter, page)
• series_catalog → series_catalog_page(page=1)

Empfohlene Struktur

• Konstanten für URLs/Endpoints (BASE_URL, Pfade, Templates)
• requests + bs4 optional (fehlt beides, Plugin sollte sauber deaktivieren)
• Helper‑Funktionen für Parsing und Normalisierung
• Caches für Such‑, Staffel‑ und Episoden‑Daten

Suche (aktuelle Policy)

• Nur Titel‑Matches
• Wortbasierter Match nach Normalisierung (Lowercase + Nicht‑Alnum → Leerzeichen)
• Keine Teilwort-Treffer innerhalb eines Wortes (Beispiel: hund matcht nicht thunder)
• Keine Beschreibung/Plot/Meta für Matches

Namensgebung

• Plugin‑Klassenname: XxxPlugin
• Anzeigename (Property name): mit Großbuchstaben beginnen (z. B. Serienstream, Einschalten)

Settings pro Plugin

Standard: *_base_url (Domain / BASE_URL)

• Beispiele:
  • serienstream_base_url
  • aniworld_base_url
  • einschalten_base_url
  • topstream_base_url
  • filmpalast_base_url
  • doku_streams_base_url

Playback

• stream_link_for(...) implementieren (liefert bevorzugten Hoster-Link).
• available_hosters_for(...) bereitstellen, wenn die Seite mehrere Hoster anbietet.
• resolve_stream_link(...) nach einheitlichem Flow umsetzen:
  1. Redirects auflösen (falls vorhanden)
  2. ResolveURL (resolveurl_backend.resolve) versuchen
  3. Bei Fehlschlag auf den besten verfügbaren Link zurückfallen
• Optional set_preferred_hosters(...) unterstützen, damit die Hoster-Auswahl aus der Hauptlogik direkt greift.

Standard‑Flow (empfohlen)

1. Suche: nur Titel liefern und Titel→Detail-URL mappen.
2. Navigation: series_url_for_title/remember_series_url unterstützen, damit URLs zwischen Aufrufen stabil bleiben.
3. Auswahl Hoster: Hoster-Namen aus der Detailseite extrahieren und anbieten.
4. Playback: Hoster-Link liefern, danach konsistent über resolve_stream_link finalisieren.
5. Metadaten: metadata_for nutzen, Plot/Poster aus der Quelle zurückgeben.
6. Fallbacks: bei Layout-Unterschieden defensiv parsen und Logging aktivierbar halten.

Debugging

Global gesteuert über Settings:

• debug_log_urls
• debug_dump_html
• debug_show_url_info

Plugins sollten die Helper aus addon/plugin_helpers.py nutzen:

• log_url(...)
• dump_response_html(...)
• notify_url(...)

Template

addon/plugins/_template_plugin.py dient als Startpunkt für neue Provider.

Build & Test

• ZIP bauen: ./scripts/build_kodi_zip.sh
• Addon‑Ordner: ./scripts/build_install_addon.sh
• Plugin‑Manifest aktualisieren: python3 scripts/generate_plugin_manifest.py

Beispiel‑Checkliste

• name korrekt gesetzt
• *_base_url in Settings vorhanden
• Suche matcht nur Titel und wortbasiert
• stream_link_for + resolve_stream_link folgen dem Standard-Flow
• Optional: available_hosters_for + set_preferred_hosters vorhanden
• Optional: series_url_for_title + remember_series_url vorhanden
• Fehlerbehandlung und Timeouts vorhanden
• Optional: Caches für Performance

Hinweis zur Erstellung

Teile dieser Dokumentation wurden KI‑gestützt erstellt und bei Bedarf manuell angepasst.