main: consolidate integrated changes after v0.1.54
This commit is contained in:
@@ -1,109 +1,85 @@
|
||||
# ViewIT – Entwicklerdoku Plugins (`addon/plugins/*_plugin.py`)
|
||||
# ViewIT Plugin Entwicklung (`addon/plugins/*_plugin.py`)
|
||||
|
||||
Diese Doku beschreibt, wie Plugins im ViewIT‑Addon aufgebaut sind und wie neue Provider‑Integrationen entwickelt werden.
|
||||
Diese Datei zeigt, wie Plugins im Projekt aufgebaut sind und wie sie mit dem Router zusammenarbeiten.
|
||||
|
||||
## 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.
|
||||
- Ein Plugin ist eine Python Datei in `addon/plugins/`.
|
||||
- Dateien mit `_` Prefix werden nicht geladen.
|
||||
- Plugin Klasse erbt von `BasisPlugin`.
|
||||
- Optional: `Plugin = <Klasse>` als klarer Einstiegspunkt.
|
||||
|
||||
## Pflicht‑Methoden (BasisPlugin)
|
||||
Jedes Plugin muss diese Methoden implementieren:
|
||||
## Pflichtmethoden
|
||||
Jedes Plugin implementiert:
|
||||
- `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.
|
||||
## Wichtige optionale Methoden
|
||||
- `stream_link_for(...)`
|
||||
- `resolve_stream_link(...)`
|
||||
- `metadata_for(...)`
|
||||
- `available_hosters_for(...)`
|
||||
- `series_url_for_title(...)`
|
||||
- `remember_series_url(...)`
|
||||
- `episode_url_for(...)`
|
||||
- `available_hosters_for_url(...)`
|
||||
- `stream_link_for_url(...)`
|
||||
|
||||
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
|
||||
- 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
|
||||
## Film Provider Standard
|
||||
Wenn keine echten Staffeln existieren:
|
||||
- `seasons_for(title)` gibt `['Film']`
|
||||
- `episodes_for(title, 'Film')` gibt `['Stream']`
|
||||
|
||||
Standard für Film-Provider (ohne echte Staffeln):
|
||||
- `seasons_for(title)` gibt `["Film"]` zurück
|
||||
- `episodes_for(title, "Film")` gibt `["Stream"]` zurück
|
||||
## Capabilities
|
||||
Ein Plugin kann Features melden ueber `capabilities()`.
|
||||
Bekannte Werte:
|
||||
- `popular_series`
|
||||
- `genres`
|
||||
- `latest_episodes`
|
||||
- `new_titles`
|
||||
- `alpha`
|
||||
- `series_catalog`
|
||||
|
||||
## 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)`
|
||||
## Suche
|
||||
Aktuelle Regeln fuer Suchtreffer:
|
||||
- Match auf Titel
|
||||
- Wortbasiert
|
||||
- Keine Teilwort Treffer im selben Wort
|
||||
- Beschreibungen nicht fuer Match nutzen
|
||||
|
||||
## 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
|
||||
## Settings
|
||||
Pro Plugin meist `*_base_url`.
|
||||
Beispiele:
|
||||
- `serienstream_base_url`
|
||||
- `aniworld_base_url`
|
||||
- `einschalten_base_url`
|
||||
- `topstream_base_url`
|
||||
- `filmpalast_base_url`
|
||||
- `doku_streams_base_url`
|
||||
|
||||
## 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
|
||||
## Playback Flow
|
||||
1. Episode oder Film auswaehlen.
|
||||
2. Optional Hosterliste anzeigen.
|
||||
3. `stream_link_for` oder `stream_link_for_url` aufrufen.
|
||||
4. `resolve_stream_link` aufrufen.
|
||||
5. Finale URL an Kodi geben.
|
||||
|
||||
## 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`
|
||||
|
||||
## 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. **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:
|
||||
## Logging
|
||||
Nutze Helper aus `addon/plugin_helpers.py`:
|
||||
- `log_url(...)`
|
||||
- `dump_response_html(...)`
|
||||
- `notify_url(...)`
|
||||
|
||||
## Template
|
||||
`addon/plugins/_template_plugin.py` dient als Startpunkt für neue Provider.
|
||||
## Build und Checks
|
||||
- ZIP: `./scripts/build_kodi_zip.sh`
|
||||
- Addon Ordner: `./scripts/build_install_addon.sh`
|
||||
- Manifest: `python3 scripts/generate_plugin_manifest.py`
|
||||
- Snapshot Checks: `python3 qa/run_plugin_snapshots.py`
|
||||
|
||||
## Build & Test
|
||||
- ZIP bauen: `./scripts/build_kodi_zip.sh`
|
||||
- Addon‑Ordner: `./scripts/build_install_addon.sh`
|
||||
|
||||
## 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.
|
||||
## Kurze Checkliste
|
||||
- `name` gesetzt und korrekt
|
||||
- `*_base_url` in Settings vorhanden
|
||||
- Suche liefert nur passende Titel
|
||||
- Playback Methoden vorhanden
|
||||
- Fehler und Timeouts behandelt
|
||||
- Cache nur da, wo er Zeit spart
|
||||
|
||||
Reference in New Issue
Block a user