viewit/ViewIT
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 37 Wiki Activity
Files
7f5924b8504661c81bb8b81c16e1835ccf333078
ViewIT/docs/PLUGIN_DEVELOPMENT.md

5.2 KiB
Raw Blame History

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
  • Live-Snapshot-Checks: python3 qa/run_plugin_snapshots.py (aktualisieren mit --update)

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.