116 lines
4.2 KiB
Markdown
116 lines
4.2 KiB
Markdown
## 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)
|
||
- `docs/PLUGIN_MANIFEST.json` (zentraler Überblick über Plugins, Versionen, Capabilities)
|
||
|
||
### 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.
|
||
|
||
### Plugin-Manifest (Audit & Repro)
|
||
`docs/PLUGIN_MANIFEST.json` listet alle Plugins mit Version, Capabilities und Basis-Settings.
|
||
Erzeugung: `python3 scripts/generate_plugin_manifest.py`
|
||
|
||
### 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`.
|