docs: update readmes with new dashboard features and instructions

Steven Seitz · Steven Seitz · commit 3e6e378aeb4b · 2026-03-27T15:06:42.000+01:00
diff --git a/README.md b/README.md
@@ -12,125 +12,43 @@
 Instead of altering global metadata or manually checking when media expires, this script calculates the exact days remaining for each item in your Maintainerr collections. It then connects to your Plex server and seamlessly updates the collection's **custom sort order**. Items closest to their deletion date automatically rise to the top!
 
 ## ✨ Features
+* **Interactive Dashboard:** Manage all settings, design your overlays, and monitor logs via a modern web interface (Port 8501).
+* **Live WYSIWYG Preview:** Real-time simulation of your Kometa banners. Upload your own posters to test the design before applying.
 * **Safe Sorting:** Uses Plex's custom collection sorting. Your global library `titleSort` metadata remains completely untouched.
-* **Multi-Collection Support:** Sync as many Maintainerr collections as you want simultaneously.
-* **Smart Kometa Overlays:** Dynamically generates library-specific YAML files for [Kometa](https://kometa.wiki/). Includes native support for season-level overlays and smart grammar logic (e.g., "1 Tag" vs "2 Tage").
-* **Built-in Scheduler:** Run it instantly (`NOW`) or set up multiple daily schedules (e.g., `04:30`, `12:00`). The container stays alive and waits for its cue.
-* **Safety First:** Includes a `dry_run` mode to test your config, and an `undo` mode to revert a collection back to its default Plex sorting.
+* **Smart Kometa Overlays:** Dynamically generates library-specific YAML files for [Kometa](https://kometa.wiki/). Includes native support for season-level overlays and customizable banner designs (Colors, Offsets, Radius).
+* **Built-in Scheduler:** Set up multiple daily sync intervals directly in the UI. The background thread keeps everything in sync while you sleep.
 * **Lightweight:** Built on `python:3.9-slim` with minimal dependencies.
 
 ## 🚀 Installation (Docker Compose)
 
 The easiest way to run this tool is via Docker. 
 
-1. Create a directory for the project and navigate into it.
-2. Create a `docker-compose.yml` file:
-
 ```yaml
 version: "3.8"
 
 services:
   maintainerr-plex-sync:
-  # You can use :latest for automatic updates, or pin a specific version like :1.1.8
     image: ghcr.io/00scooby/maintainerr-plex-sync:latest
     container_name: maintainerr_sync
     restart: unless-stopped
     ports:
-      - "8501:8501"
+      - "8501:8501" # Access the Dashboard here
     environment:
-      - TZ=Europe/Zurich # Change to your timezone
-      - PLEX_URL=[http://192.168.1.100:32400](http://192.168.1.100:32400)
+      - TZ=Europe/Zurich
+      - PLEX_URL=http://[YOUR-IP]:32400
       - PLEX_TOKEN=your_plex_token_here
-      - MAINTAINERR_URL=[http://192.168.1.100:6246](http://192.168.1.100:6246)
+      - MAINTAINERR_URL=http://[YOUR-IP]:6246
     volumes:
       - ./config.yml:/app/config.yml
-      # OPTIONAL: Map this to access the exported YAML files during a 'dry_run'
-      - ./:/dry_run/
       - ./logs:/logs
-      # OPTIONAL: Map this if you want to use the Kometa Overlay feature
       - ./kometa/config:/app/kometa_export
 ```
-3. Create your `config.yml` in the same directory (see Configuration below).
-
-4. Run `docker compose up -d`.
-
-## ⚙️ Configuration (`config.yml`)
-Map this file into your container at `/app/config.yml`.
-
-```YAML
-# ==========================================
-# Maintainerr-to-Plex Sync Configuration
-# ==========================================
-
-settings:
-  # Modes: "run" (active), "dry_run" (testing), "undo" (revert Plex sorting)
-  run_mode: "run"
-  
-  # Log levels: DEBUG, INFO, WARNING, ERROR
-  log_level: "INFO"
-  
-  # "NOW" for a single immediate run (container exits afterwards)
-  # OR a list of times for standby mode
-  run_schedules:
-    - "04:30"
-    
-  # Exact names of the collections in Maintainerr to sync
-  collection_names:
-    - "Series unseen for 360 days"
-    - "Movies unseen for 1 year"
-
-  # ==========================================
-  # Kometa Overlay Integration (Optional)
-  # ==========================================
-  enable_kometa_overlays: false
-  
-  # Only generate overlays for these Plex libraries
-  kometa_allowed_libraries:
-    - "Filme"
-    - "Serien"
-    
-  # Dynamic Color Thresholds
-  kometa_threshold_days: 10
-  kometa_color_urgent: "#E31E24"         # Background color for <= threshold (e.g., Red)
-  kometa_text_color_urgent: "#FFFFFF"    # Text color for <= threshold (e.g., White)
-  kometa_color_warning: "#F1C40F"        # Background color for > threshold (e.g., Yellow)
-  kometa_text_color_warning: "#141414"   # Text color for > threshold (e.g., Dark Grey/Black for contrast)
-```
 
 ## 🛠️ How it works
-1. The script fetches the specified collections from your Maintainerr API.
-2. It calculates the days left before deletion for each item based on `addDate` and `deleteAfterDays`.
-3. It connects to Plex via the `plexapi` wrapper and updates the collection sorting.
-4. If enabled, it automatically generates library-specific YAML files (e.g., `maintainerr_Filme.yml`, `maintainerr_Serien.yml`) that Kometa can read to add visual expiration banners to your media.
+1. **Connect:** Access the Dashboard at `http://[YOUR-IP]:8501`.
+2. **Configure:** Select your Plex libraries and Maintainerr collections via dynamic dropdowns.
+3. **Design:** Use sliders to adjust your Kometa banners and check the live preview.
+4. **Automate:** Set your sync times and let the background worker handle the rest.
 
-## 🎨 Kometa Setup
-To utilize the generated overlay files, simply include them in your Kometa configuration under the respective libraries. Since the script splits the exports by library name, you avoid soft fails in your Kometa logs!
-
-```YAML
-libraries:
-  Filme:
-    overlay_path:
-      - file: config/maintainerr_Filme.yml
-  Serien:
-    overlay_path:
-      - file: config/maintainerr_Serien.yml
-```
 ## 🚑 Troubleshooting
-
-### ⚠️ Log: "Kollektion '[Name]' in Plex nicht gefunden!"
-**Cause:** The script found the collection in Maintainerr, but it doesn't exist in Plex under that exact name.
-**Solution:** Check the exact spelling in both Plex and Maintainerr. It must be a 100% match (including spaces and case sensitivity).
-
-### ⚠️ Log: "DRY RUN MODUS AKTIV: Plex wird nicht verändert."
-**Cause:** The script is only reading data. It won't reorder anything in Plex and saves the generated Kometa files to a test folder.
-**Solution:** Change `run_mode: "dry_run"` to `run_mode: "run"` in your `config.yml` and restart the container to apply changes to Plex.
-
-### ⚠️ No Kometa YAML files are being exported
-**Cause 1:** The Kometa feature is disabled in your configuration.
-**Solution 1:** Ensure `enable_kometa_overlays: true` is set in your `config.yml`.
-**Cause 2:** The library names don't match.
-**Solution 2:** Check the `kometa_allowed_libraries` block. The names (e.g., "Movies", "TV Shows") must exactly match the library names on your Plex server.
-
-### ⚠️ Log: "Fehler bei der Verbindung zu Plex / Maintainerr"
-**Cause:** The script cannot reach the respective APIs, or authentication failed.
-**Solution:** Double-check your `docker-compose.yml` (or `.env` file) to ensure the `PLEX_URL`, `PLEX_TOKEN`, and `MAINTAINERR_URL` are correct and accessible from within the Docker container.
+Check the **Live Logs** section at the bottom of the Dashboard for real-time feedback on API connections and sync status.
diff --git a/README_DE.md b/README_DE.md
@@ -1,5 +1,4 @@
 # Maintainerr-to-Plex Sync 🚀
-
 [🇩🇪 Deutsch](README_DE.md) | [🇬🇧 English](README.md)
 
 [![Docker Build](https://github.com/00Scooby/maintainerr-plex-sync/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/00Scooby/maintainerr-plex-sync/actions/workflows/docker-publish.yml)
@@ -10,128 +9,44 @@
 
 **Maintainerr-to-Plex Sync** ist ein vollautomatisierter Python-Microservice, der die Lücke zwischen den Löschplänen von [Maintainerr](https://github.com/jorenn92/Maintainerr) und deiner Plex-Oberfläche schliesst.
 
-Anstatt globale Metadaten zu ändern oder manuell zu prüfen, wann Medien ablaufen, berechnet dieses Skript die exakten verbleibenden Tage für jedes Item in deinen Maintainerr-Kollektionen. Anschliessend verbindet es sich mit deinem Plex-Server und aktualisiert nahtlos die **benutzerdefinierte Sortierung** der Kollektion. Items, die kurz vor der Löschung stehen, wandern automatisch nach oben!
+Anstatt globale Metadaten zu ändern, berechnet dieses Skript die exakten verbleibenden Tage für jedes Item in deinen Maintainerr-Kollektionen und aktualisiert nahtlos die **benutzerdefinierte Sortierung** in Plex. Medien, die kurz vor der Löschung stehen, wandern automatisch nach oben!
 
 ## ✨ Features
-* **Sicheres Sortieren:** Nutzt die benutzerdefinierte Kollektionssortierung von Plex. Deine globalen `titleSort`-Metadaten der Mediathek bleiben komplett unangetastet.
-* **Multi-Collection Support:** Synchronisiere so viele Maintainerr-Kollektionen gleichzeitig, wie du möchtest.
-* **Smarte Kometa-Overlays:** Generiert dynamisch bibliotheksspezifische YAML-Dateien für [Kometa](https://kometa.wiki/). Enthält native Unterstützung für Overlays auf Staffel-Ebene und eine intelligente Grammatik-Logik (z. B. "1 Tag" vs. "2 Tage").
-* **Integrierter Scheduler:** Führe das Skript sofort aus (`NOW`) oder richte mehrere tägliche Zeitpläne ein (z. B. `04:30`, `12:00`). Der Container bleibt aktiv und wartet auf seinen Einsatz.
-* **Safety First:** Beinhaltet einen `dry_run`-Modus, um deine Konfiguration zu testen, sowie einen `undo`-Modus, um eine Kollektion auf die Standard-Plex-Sortierung zurückzusetzen.
-* **Leichtgewicht:** Basiert auf `python:3.9-slim` mit minimalen Abhängigkeiten.
+* **Interaktives Dashboard:** Verwalte alle Einstellungen, gestalte deine Overlays und überwache Logs über eine moderne Web-Oberfläche (Port 8501).
+* **Live WYSIWYG Vorschau:** Echtzeit-Simulation deiner Kometa-Banner. Lade eigene Poster hoch, um das Design vorab zu prüfen.
+* **Sicheres Sortieren:** Nutzt die benutzerdefinierte Kollektionssortierung von Plex. Deine globalen Mediathek-Metadaten bleiben unangetastet.
+* **Smarte Kometa-Overlays:** Generiert dynamisch Dateien für [Kometa](https://kometa.wiki/) mit anpassbaren Farben, Offsets und Radien.
+* **Integrierter Scheduler:** Richte mehrere tägliche Zeitpläne direkt in der UI ein. Der Hintergrund-Thread hält alles synchron.
+* **Leichtgewicht:** Basiert auf `python:3.9-slim` mit minimalem Ressourcenverbrauch.
 
 ## 🚀 Installation (Docker Compose)
 
-Der einfachste Weg, dieses Tool auszuführen, ist über Docker. 
-
-1. Erstelle ein Verzeichnis für das Projekt und wechsle dorthin.
-2. Erstelle eine `docker-compose.yml`-Datei:
-
 ```yaml
 version: "3.8"
 
 services:
   maintainerr-plex-sync:
-  # Du kannst :latest für automatische Updates nutzen oder eine Version pinnen, z.B. :1.1.10
     image: ghcr.io/00scooby/maintainerr-plex-sync:latest
     container_name: maintainerr_sync
     restart: unless-stopped
     ports:
-      - "8501:8501"
+      - "8501:8501" # Dashboard-Zugriff
     environment:
-      - TZ=Europe/Zurich # Zeitzone anpassen
-      - PLEX_URL=[http://192.168.1.100:32400](http://192.168.1.100:32400)
+      - TZ=Europe/Zurich
+      - PLEX_URL=http://[DEINE-IP]:32400
       - PLEX_TOKEN=dein_plex_token_hier
-      - MAINTAINERR_URL=[http://192.168.1.100:6246](http://192.168.1.100:6246)
+      - MAINTAINERR_URL=http://[DEINE-IP]:6246
     volumes:
       - ./config.yml:/app/config.yml
-      # OPTIONAL: Mappe dies, um während eines 'dry_run' auf die exportierten YAML-Dateien zuzugreifen
-      - ./:/dry_run/
       - ./logs:/logs
-      # OPTIONAL: Mappe dies, wenn du das Kometa-Overlay-Feature nutzen möchtest
       - ./kometa/config:/app/kometa_export
 ```
-3. Erstelle deine `config.yml` im selben Verzeichnis (siehe Konfiguration unten).
-4. Führe `docker compose up -d` aus.
-
-## ⚙️ Konfiguration (`config.yml`)
-Mappe diese Datei in deinen Container unter `/app/config.yml`.
-
-```YAML
-# ==========================================
-# Maintainerr-to-Plex Sync Configuration
-# ==========================================
-
-settings:
-  # Modi: "run" (aktiv), "dry_run" (testen), "undo" (Plex-Sortierung zurücksetzen)
-  run_mode: "run"
-  
-  # Log-Level: DEBUG, INFO, WARNING, ERROR
-  log_level: "INFO"
-  
-  # "NOW" für einen sofortigen, einmaligen Start (Container beendet sich danach)
-  # ODER eine Liste von Uhrzeiten für den Standby-Modus
-  run_schedules:
-    - "04:30"
-    
-  # Exakte Namen der Maintainerr-Kollektionen, die synchronisiert werden sollen
-  collection_names:
-    - "Series unseen for 360 days"
-    - "Movies unseen for 1 year"
-
-  # ==========================================
-  # Kometa Overlay Integration (Optional)
-  # ==========================================
-  enable_kometa_overlays: false
-  
-  # Generiere Overlays nur für diese Plex-Mediatheken
-  kometa_allowed_libraries:
-    - "Filme"
-    - "Serien"
-    
-  # Dynamische Farb-Schwellenwerte
-  kometa_threshold_days: 10
-  kometa_color_urgent: "#E31E24"         # Hintergrundfarbe für <= Schwelle (z. B. Rot)
-  kometa_text_color_urgent: "#FFFFFF"    # Textfarbe für <= Schwelle (z. B. Weiss)
-  kometa_color_warning: "#F1C40F"        # Hintergrundfarbe für > Schwelle (z. B. Gelb)
-  kometa_text_color_warning: "#141414"   # Textfarbe für > Schwelle (z. B. Dunkelgrau/Schwarz für Kontrast)
-```
 
-## 🛠️ Wie es funktioniert
-1. Das Skript ruft die angegebenen Kollektionen über deine Maintainerr-API ab.
-2. Es berechnet die verbleibenden Tage bis zur Löschung für jedes Item basierend auf `addDate` und `deleteAfterDays`.
-3. Es verbindet sich via `plexapi`-Wrapper mit Plex und aktualisiert die benutzerdefinierte Sortierung der Kollektion.
-4. Falls aktiviert, generiert es automatisch bibliotheksspezifische YAML-Dateien (z. B. `maintainerr_Filme.yml`, `maintainerr_Serien.yml`), die Kometa lesen kann, um visuelle Ablauf-Banner zu deinen Medien hinzuzufügen.
-
-## 🎨 Kometa Setup
-Um die generierten Overlay-Dateien zu nutzen, füge sie einfach unter den jeweiligen Mediatheken in deine Kometa-Konfiguration ein. Da das Skript die Exporte nach Mediatheken-Namen aufteilt, vermeidest du Soft Fails in deinen Kometa-Logs!
-
-```YAML
-libraries:
-  Filme:
-    overlay_path:
-      - file: config/maintainerr_Filme.yml
-  Serien:
-    overlay_path:
-      - file: config/maintainerr_Serien.yml
-```
+## 🛠️ Funktionsweise
+1. **Dashboard:** Öffne `http://[DEINE-IP]:8501`.
+2. **Konfiguration:** Wähle Mediatheken und Kollektionen bequem über Dropdowns aus.
+3. **Design:** Nutze die Schieberegler für das Banner-Design und kontrolliere das Ergebnis in der Live-Vorschau.
+4. **Automatisierung:** Speichere deine Sync-Uhrzeiten und lass den Hintergrund-Ninja die Arbeit erledigen.
 
 ## 🚑 Troubleshooting
-
-### ⚠️ Log: "Kollektion '[Name]' in Plex nicht gefunden!"
-**Ursache:** Das Skript hat die Kollektion zwar in Maintainerr gefunden, aber in Plex existiert sie unter diesem exakten Namen nicht.
-**Lösung:** Prüfe die genaue Schreibweise in Plex und Maintainerr. Sie muss zu 100 % identisch sein (inklusive Leerzeichen und Gross-/Kleinschreibung).
-
-### ⚠️ Log: "DRY RUN MODUS AKTIV: Plex wird nicht verändert."
-**Ursache:** Das Skript liest nur Daten. Es sortiert nichts in Plex um und schreibt die generierten Kometa-Dateien in einen Testordner.
-**Lösung:** Ändere in deiner `config.yml` den Wert `run_mode: "dry_run"` zu `run_mode: "run"` und starte den Container neu, um die Änderungen auf Plex anzuwenden.
-
-### ⚠️ Es werden keine Kometa YAML-Dateien exportiert
-**Ursache 1:** Die Kometa-Funktion ist in deiner Konfiguration deaktiviert.
-**Lösung 1:** Stelle sicher, dass `enable_kometa_overlays: true` in der `config.yml` gesetzt ist.
-**Ursache 2:** Die Mediatheken-Namen stimmen nicht überein.
-**Lösung 2:** Prüfe den Block `kometa_allowed_libraries`. Die Namen (z. B. "Filme", "Serien") müssen exakt so heissen wie die Mediatheken auf deinem Plex-Server.
-
-### ⚠️ Log: "Fehler bei der Verbindung zu Plex / Maintainerr"
-**Ursache:** Das Skript kann die jeweiligen APIs nicht erreichen oder die Authentifizierung schlägt fehl.
-**Lösung:** Kontrolliere in deiner `docker-compose.yml` (oder `.env` Datei), ob die `PLEX_URL`, der `PLEX_TOKEN` und die `MAINTAINERR_URL` absolut korrekt und aus dem Docker-Container heraus erreichbar sind.
+Nutze den Bereich **Live-Logs** am Ende des Dashboards für Echtzeit-Feedback zu API-Verbindungen und dem Synchronisationsstatus.
