docs: rewrite README and docs to concise ASCII style
This commit is contained in:
@@ -1,115 +1,71 @@
|
||||
## ViewIt Plugin-System
|
||||
# ViewIT Plugin System
|
||||
|
||||
Dieses Dokument beschreibt, wie das Plugin-System von **ViewIt** funktioniert und wie die Community neue Integrationen hinzufügen kann.
|
||||
Dieses Dokument beschreibt Laden, Vertrag und Betrieb der Plugins.
|
||||
|
||||
### Überblick
|
||||
## Ueberblick
|
||||
Der Router laedt Provider Integrationen aus `addon/plugins/*.py`.
|
||||
Aktive Plugins werden instanziiert und im UI genutzt.
|
||||
|
||||
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.
|
||||
Relevante Dateien:
|
||||
- `addon/default.py`
|
||||
- `addon/plugin_interface.py`
|
||||
- `docs/DEFAULT_ROUTER.md`
|
||||
- `docs/PLUGIN_DEVELOPMENT.md`
|
||||
|
||||
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`
|
||||
- `topstreamfilm_plugin.py`
|
||||
- `einschalten_plugin.py`
|
||||
- `aniworld_plugin.py`
|
||||
- `filmpalast_plugin.py`
|
||||
- `dokustreams_plugin.py`
|
||||
- `_template_plugin.py` (Vorlage)
|
||||
|
||||
### Aktuelle Plugins
|
||||
## Discovery Ablauf
|
||||
In `addon/default.py`:
|
||||
1. Finde `*.py` in `addon/plugins/`
|
||||
2. Ueberspringe Dateien mit `_` Prefix
|
||||
3. Importiere Modul
|
||||
4. Nutze `Plugin = <Klasse>`, falls vorhanden
|
||||
5. Sonst instanziiere `BasisPlugin` Subklassen deterministisch
|
||||
6. Ueberspringe Plugins mit `is_available = False`
|
||||
|
||||
- `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
|
||||
## Basis Interface
|
||||
`BasisPlugin` definiert den Kern:
|
||||
- `search_titles`
|
||||
- `seasons_for`
|
||||
- `episodes_for`
|
||||
|
||||
### Plugin-Discovery (Ladeprozess)
|
||||
Weitere Methoden sind optional und werden nur genutzt, wenn vorhanden.
|
||||
|
||||
Der Loader in `addon/default.py`:
|
||||
## Capabilities
|
||||
Plugins koennen Features aktiv melden.
|
||||
Typische Werte:
|
||||
- `popular_series`
|
||||
- `genres`
|
||||
- `latest_episodes`
|
||||
- `new_titles`
|
||||
- `alpha`
|
||||
- `series_catalog`
|
||||
|
||||
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`
|
||||
Das UI zeigt nur Menues fuer aktiv gemeldete Features.
|
||||
|
||||
Damit bleiben fehlerhafte Plugins isoliert und blockieren nicht das gesamte Add-on.
|
||||
## Metadaten Quelle
|
||||
`prefer_source_metadata = True` bedeutet:
|
||||
- Quelle zuerst
|
||||
- TMDB nur Fallback
|
||||
|
||||
### Plugin-Manifest (Audit & Repro)
|
||||
`docs/PLUGIN_MANIFEST.json` listet alle Plugins mit Version, Capabilities und Basis-Settings.
|
||||
Erzeugung: `python3 scripts/generate_plugin_manifest.py`
|
||||
## Stabilitaet
|
||||
- Keine Netz Calls im Import Block.
|
||||
- Fehler im Plugin muessen lokal behandelt werden.
|
||||
- Ein defektes Plugin darf andere Plugins nicht blockieren.
|
||||
|
||||
### BasisPlugin – verpflichtende Methoden
|
||||
## Build
|
||||
Kodi ZIP bauen:
|
||||
|
||||
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
|
||||
|
||||
```
|
||||
```bash
|
||||
./scripts/build_kodi_zip.sh
|
||||
```
|
||||
|
||||
Das ZIP liegt anschließend unter `dist/plugin.video.viewit-<version>.zip`.
|
||||
Ergebnis:
|
||||
`dist/plugin.video.viewit-<version>.zip`
|
||||
|
||||
Reference in New Issue
Block a user