From 3d87c8caa7f7bc3d135dde80a7c97bae561884ed Mon Sep 17 00:00:00 2001 From: Hitonabi Date: Tue, 21 Jul 2026 17:28:59 +0200 Subject: [PATCH] Dokumentation aktualisiert --- KONZEPT.md | 158 ++++++++++++++++++++--------------------------------- README.md | 8 +-- ROADMAP.md | 2 + 3 files changed, 64 insertions(+), 104 deletions(-) diff --git a/KONZEPT.md b/KONZEPT.md index 0b145dd..70fa03a 100644 --- a/KONZEPT.md +++ b/KONZEPT.md @@ -17,7 +17,7 @@ Rippy ist ein **komplett neues System** von Grund auf: modulare Multi-Container- ## 3. Kern-Idee -Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt, **vorbereitend Metadaten lookup und Preview bereitstellt**, das Medium rippt, Metadaten anreichert und das Ergebnis **Jellyfin-konform strukturiert ablegt**. Alles über eine REST-API, asynchrone Celery-Jobs, ein React-WebUI und Echtzeit-Status über SSE. +Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt, **vorbereitend Metadaten lookup und Preview bereitstellt**, das Medium rippt, Metadaten anreichert und das Ergebnis **Jellyfin-konform strukturiert ablegt**. Alles über eine REST-API, asynchrone Celery-Jobs, ein React-WebUI. ## 4. Features @@ -38,7 +38,6 @@ Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt | JWT-Auth (Access 15min/Refresh 7 Tage) | ✔ M | | | | Rate-Limiting (100/min pro API-Key) | ✔ M | | | | Celery-Queue + Redis mit AOF-Persistence | ✔ M | | | -| Echtzeit-Status über SSE | ✔ M | | | | React-UI (statisch via Nginx) | ✔ M | | | | Proxmox LXC Template + Ansible Playbooks | ✔ M | | | | SELinux/AppArmor Profile pro Container | ✔ M | | | @@ -60,107 +59,80 @@ Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt 2. **Device-Resolver** (udev-basiert) ermittelt UUID/Serial-Nummer des Laufwerks, erzeugt Symlink `/dev/disc/`. 3. **Job-Erstellung** → Dämon erstellt Celery-Task, übergibt Device-Pfad und Disc-Typ. 4. **Typ-Erkennung** (CD/DVD/Blu-ray) → Auswahl des Ripping-Pfads. -5. **⚡ METADATEN-Lookup im VORFELD** *(neu / geändert)*: - - DVD/Blu-ray: `makejungles` (oder equivalent) liest nur die TOC (Table of Contents), **ohne das Medium zu rippen**. +5. **METADATEN-Lookup im VORFELD**: + - DVD/Blu-ray: `makejungles` liest TOC ohne Ripping. - Title, Laufzeit, Scene-Labels werden ausgelesen. - - Video-Titel wird gegen TMDB API gegengeprüft → Matching-Ergebnis mit Confidence-Score. + - Video-Titel wird gegen TMDB API gegengeprüft → Confidence-Score. - Audio-Titel wird gegen MusicBrainz gegengeprüft (bei CD). - **Rippy zeigt eine Preview im WebUI**: Titel, Jahr, Cover, Trackliste. - - Der Commander kann bestätigen oder manuell korrigieren (z.B. falsches TMDB-Match). - - Bestätigte Metadaten werden im SQLite-Cache persistiert. + - Commander bestätigt oder korrigiert manuell. 6. **Ripping** (nach Bestätigung): - - CD: `abcde` → FLAC, Metadaten via AcoustID-Fingerprinting + MusicBrainz. - - DVD/Blu-ray: `makemkvcon --all --progress` → MKV, unter Verwendung der vorab gelookupeten Metadaten. -7. **Post-Processing & Jellyfin-Formatierung** *(neu / geändert)*: - - Dateien werden in Jellyfin-konformer Ordnerstruktur abgelegt: - - Filme: ` ()/-.mkv` + `poster.jpg` + `fanart.jpg` + `movie.nfo` - - Serien: `<Serienname>/<Staffel N>/<Serienname> - S{Season}E{Episode} - <Episode>.mkv` + `poster.jpg` + `fanart.jpg` + `series.nfo` / `episode.nfo` - - Musik: `<Künstler>/<Album> (<Jahr>)/<Track-Nr>. <Titel>.flac` + `album.jpg` + `album.nfo` - - NFO-Dateien werden automatisch generiert im Jellyfin-Mediainfo-Format (Kodi/NFO-Schema). - - Poster/Backdrop/Fanart werden von TMDB heruntergeladen und nebengelegt. - - Bei Serien: Episode-Names werden von TheTVDB oder TMDB Movies/Fallback geholt. - - Bei Multi-Disc: Disc-Labels werden als `Disc 1.mkv`, `Disc 2.mkv` etc. benannt. -8. **Multi-Disc-Erkennung**: Release-Group-Resolver prüft, ob weitere Discs des gleichen Sets folgen. -9. **Status-Push**: Worker sendet Fortschritt über SSE an React-UI. -10. **Abschluss**: Job-Ergebnis wird protokolliert, API gibt Token zurück, PBS-Backup-Hook kann ausgelöst werden. + - CD: `abcde` → FLAC, Metadaten via AcoustID + MusicBrainz. + - DVD/Blu-ray: `makemkvcon --all --progress` → MKV. +7. **Post-Processing & Jellyfin-Formatierung**: + - Dateien in Jellyfin-konformer Ordnerstruktur. + - NFO-Dateien im Kodi/NFO-Schema. + - Poster/Backdrop/Fanart von TMDB. +8. **Multi-Disc-Erkennung**: Release-Group-Resolver prüft weitere Discs. +9. **Status-Push**: Worker sendet Fortschritt an UI. +10. **Abschluss**: Job-Ergebnis protokolliert, PBS-Backup-Hook. ## 6. Architektur & Tech-Stack -``` -┌─────────────────────────────────────────────────────┐ -│ Proxmox LXC (Debian 12 Slim) │ -│ │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ API-Service │ │ Worker- │ │ UI-Service │ │ -│ │ FastAPI │◄►│ Celery+ │ │ React + │ │ -│ │ PostgreSQL │ │ Redis(AOF) │ │ Nginx │ │ -│ └─────────────┘ └─────────────┘ └─────────────┘ │ -│ │ │ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌────────────────────────────────────────┐ │ -│ │ udev-Daemon → Device-Resolver │ │ -│ │ Unix-Socket → Worker Device-Infos │ │ -│ └────────────────────────────────────────┘ │ -│ │ -│ ┌────────────────────────────────────────┐ │ -│ │ MakeMKV (isolierter CLI-Aufruf) │ │ -│ │ HandBrake (optional, CLI) │ │ -│ │ abcde + chromaprint + MusicBrainz │ │ -│ │ NFO-Generator (Jellyfin-Mediainfo) │ ★ NEU │ -│ │ TMDB/TVDB Image-Downloader │ ★ NEU │ -│ └────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────┘ -``` - **Container-Design:** -- **API-Service** (FastAPI): JWT-Auth, REST-Endpoints, OpenAPI-Docs, Job-Management, Lizenz-Handling. -- **Worker-Service** (Celery + Redis mit AOF-Persistence): Isolierte Ripping-Jobs, Celery Tasks mit Device-Meta-Daten. -- **UI-Service** (React + Vite): Build-Step → statisch, bereitgestellt via Nginx. SSE-Client für Echtzeit-Status. -- **udev-Daemon**: Separater System-Dienst (unabhängig von API-Container), empfängt Disc-Einwurf-Events. +- **API-Service** (FastAPI): JWT-Auth, REST-Endpoints, OpenAPI-Docs, Job-Management. +- **Worker-Service** (Celery + Redis mit AOF-Persistence): Isolierte Ripping-Jobs. +- **UI-Service** (React + Vite): Build-Step → statisch via Nginx. +- **udev-Daemon**: Separater System-Dienst für Disc-Einwurf-Events. + +**Container-Security:** +- `read_only: true` für API/Worker (keine Schreibrechte außer tmpfs) +- `tmpfs` für `/app/tmp`, `/run`, `/tmp` (wichtig für Python `__pycache__`) +- Healthchecks für Postgres/Redis +- Separate Volumes für Medien und Temp-Dateien **Neue Worker-Komponenten:** -- **NFO-Generator**: Liest die gelookupeten Metadaten und schreibt `.nfo`-Dateien im Jellyfin-erkannten Format (Kodi/NFO-Schema). Unterstützt movie.nfo, series.nfo, episode.nfo, album.nfo. -- **TMDB Image-Downloader**: Lädt poster.jpg, fanart.jpg, backdrop.jpg in der Jellyfin-konformen Auflösung (poster: 500x750, fanart: 1920x1080+). -- **Pre-Scan-Modul**: Liest die TOC der Disc (ohne Ripping), extrahiert Titel/Laufzeit/Scene-Labels und queryt TMDB/TVDB/MusicBrainz. +- **NFO-Generator**: `.nfo`-Dateien im Jellyfin-Kodi-Schema. +- **TMDB Image-Downloader**: poster.jpg, fanart.jpg, backdrop.jpg. +- **Pre-Scan-Modul**: TOC-Lesung ohne Ripping + API-Query. **LXC-Isolation:** - Read-only Bind-Mounts für System-Bibliotheken. -- Device-Node-Read-Only für `/dev/sr*` (optische Medien sind read-only). +- Device-Node-Read-Only für `/dev/sr*`. - SELinux/AppArmor Profile pro Container. -- Netzwerk-Policy: UI↔API (HTTPS), API↔Worker (mTLS), Worker↔Internet (nur API-Endpoints). +- Netzwerk-Policy: UI→API (HTTPS), API↔Worker (mTLS). **Persistenz:** - PostgreSQL für Job-Logs, Metadaten, User-Management. -- SQLite-Cache für API-Antworten (MusicBrainz, TMDB, TheTVDB) — max 10.000 Einträge, LRU-Eviction. -- NFS/Bind-Mount für Medien-Store (geteilter Volume). +- SQLite-Cache für API-Antworten (LRU, 10k Einträge). +- NFS/Bind-Mount für Medien-Store. ## 7. UX-Flow -1. **Dashboard** — Echtzeit-Kacheln mit aktuellem Job-Status, Queue-Übersicht, Disc-Einwurf-Hinweis. -2. **Job-Verlauf** — Tabelle aller Jobs mit Status, Fortschrittsbalken, Ergebnis-Vorschau. -3. **Metadaten-Preview** *(neu)* — Nach udev-Erkennung zeigt das UI automatisch die gelookupeten Metadaten: Titel, Jahr, Cover, Trackliste, Confidence-Score. Der Commander kann bestätigen oder manuell korrigieren (z.B. falsches TMDB-Match auswählen, Titel bearbeiten). -4. **Job-Detail** — Live-Log-Ausgabe, Fortschritt, Möglichkeit "Abort" (nur vor Job-Start). -5. **Ergebnis-View** — Liste gerippter Dateien, Metadaten-Anzeige, Jellyfin-Ordnerstruktur-Preview, "Play" (Streaming) / "Download". -6. **Einstellungen** — API-Keys verwalten (TMDB, Discogs, TheTVDB), Transcoding-Optionen, Backup-Pfade, Lizenz-Einstellungen, Jellyfin-Config (Ziel-Pfade, NFO-Format). -7. **Geräte-Verwaltung** — Liste verfügbarer Laufwerke, Status, Device-Resolver-Konfiguration. +1. **Dashboard** — Echtzeit-Kacheln mit Job-Status, Queue-Übersicht. +2. **Job-Verlauf** — Tabelle aller Jobs mit Status, Fortschrittsbalken. +3. **Metadaten-Preview** — Nach udev-Erkennung: Titel, Jahr, Cover, Trackliste, Confidence-Score. +4. **Job-Detail** — Live-Log-Ausgabe, Fortschritt, "Abort". +5. **Ergebnis-View** — Liste gerippter Dateien, Metadaten, Jellyfin-Ordnerstruktur. +6. **Einstellungen** — API-Keys, Transcoding, Backup-Pfade, Jellyfin-Config. +7. **Geräte-Verwaltung** — Liste Laufwerke, Status, Device-Resolver. ## 8. Risiken & offene Punkte | Risiko | Status | Behandlung | |--------|--------|------------| -| MakeMKV-Beta-Key-Management | Gelöst | Key-Erneuerung als Cron-Job dokumentiert; rechtlich: DMCA-Ausnahme für Heimarchiv in DE, kommerzielle Lizenz $50 empfohlen | -| LXC-Device-Node-Änderungen | Gelöst | udev-Resolver (UUID/Serial) statt statischer `/dev/sr*`-Pfade; Device-Symlinks für stabile Zuweisung | -| Pending-Queue / State-Manager | Gelöst | Redis mit AOF-Persistence als State-Manager; Task-Priorisierung, Redis-Dumps beim Neustart | -| Hybrid-Discs (DVD-Audio, Hybrid-CD) | Offen | MVP erkennt nur Standard-CD/DVD/Blu-ray; Hybrid-Erkennung als "Kann" für spätere Version | -| LXC-Device-Passthrough Stabilität | Gelöst | Read-only Bind-Mounts; udev-Daemon unabhängig von API-Container; Hot-Plug-Integration via udev | -| Rate-Limits der Metadaten-APIs | Gelöst | SQLite-Cache (LRU, 10k Einträge), exponential backoff Retry (max 5 Versuche) | -| GPL-v3-Compliance | Gelöst | Checkliste, Source-Release-Endpoint, MakeMKV als isolierte Black-Box, Lizenz-Dokumentation | -| Redis Single-Instance Bottleneck | Offen | MVP mit Single-Instance; Redis-Cluster als "Später"-Feature | -| **TMDB-Matching-Fehler bei Nischentiteln** | **Neu** | **Offen** — Pre-Scan zeigt Confidence-Score, manuelle Korrektur durch Commander. Fallback: manueller Titel-Eingabedialog. TheTVDB als Serien-Fallback. | -| **NFO-Format-Abhängigkeit von Jellyfin-Version** | **Neu** | **Hinweis** — Jellyfin nutzt Kodi/NFO-Schema (gut dokumentiert). Bei Upstream-Änderungen muss NFO-Generator angepasst werden. Keine kritische Abhängigkeit. | -| **Pre-Scan verzögert Ripping-Start** | **Neu** | **Hinweis** — Pre-Scan dauert 5–15s (TOC lesen + API-Query). Parallelisierbar: udev-Daemon startet Pre-Scan sofort, Ripping wartet nur auf Bestätigung. Akzeptabel für Heim-Use-Case. | -| **TMDB-Bildrechte für Poster/Fanart** | **Neu** | **Gelöst** — TMDB API-ToS erlaubt Nutzung für private Heimzwecke (Daten Attribution Required). NFO enthält `<details>Source: TMDB</details>`. | +| MakeMKV-Beta-Key-Management | Gelöst | Key-Erneuerung als Cron-Job; DMCA-Ausnahme in DE | +| LXC-Device-Node-Änderungen | Gelöst | udev-Resolver (UUID/Serial) | +| Pending-Queue / State-Manager | Gelöst | Redis mit AOF-Persistence | +| Hybrid-Discs | Offen | MVP erkennt nur Standard; als "Kann" notiert | +| LXC-Device-Passthrough | Gelöst | Read-only Bind-Mounts; udev-Daemon unabhängig | +| Rate-Limits der Metadaten-APIs | Gelöst | SQLite-Cache (LRU, 10k Einträge), exponential backoff | +| GPL-v3-Compliance | Gelöst | Checkliste, Source-Release-Endpoint, Black-Box-Trennung | +| Redis Single-Instance | Offen | MVP mit Single-Instance; Cluster als "Später" | +| **TMDB-Matching-Fehler bei Nischentiteln** | **Offen** | Pre-Scan Confidence-Score + manueller Korrektur-Mechanismus | +| **NFO-Format-Abhängigkeit von Jellyfin-Version** | **Hinweis** | Kodi/NFO-Schema (stabil, gut dokumentiert) | +| **Pre-Scan-Latenz (5–15s)** | **Hinweis** | Akzeptabel für Heim-Use-Case; parallelisierbar | +| **TMDB-Bildrechte** | **Gelöst** | TMDB API-ToS erlaubt private Nutzung | ## 9. Härtetest-Dokumentation @@ -170,31 +142,17 @@ Ein modular aufgebautes System, das bei Disc-Einwurf automatisch den Typ erkennt **Runde 1 (5 Rollen):** - DevOps: Multi-Container-Architektur, Proxmox-HA-Template, Resource-Limits, Restart-Policy. - Security: JWT-Refresh-Token, Rate-Limiting, mTLS, SELinux/AppArmor. -- Software Architekt: udev-basierter Device-Resolver, Unix-Socket, State-Manager, Pending-Queue. +- Software Architekt: udev-basierter Device-Resolver, Unix-Socket, State-Manager. - Media Metadata: AcoustID-Fingerprinting, Multi-Disc-Set-Handling, SQLite-Cache. - Legal: GPL-v3-Checkliste, MakeMKV-Black-Box-Trennung, Source-Release-Endpoint. **Zweiter Haertetest (Advocatus Diaboli, GLM-4.7-Flash):** -5 HINWEISE (keine BLOCKER): React als Build-Step+Statisch (korrigiert), Redis-AOF-Persistence (integriert), Read-only vs. Write-Konflikt (nicht relevant — optische Medien sind read-only), Redis-Cluster (als "Später" notiert), Cold-Boot-Problematik (udev-Daemon als separater Dienst gelöst). +5 HINWEISE (keine BLOCKER): React als Build-Step+Statisch (korrigiert), Redis-AOF-Persistence (integriert), Read-only vs. Write-Konflikt (nicht relevant), Redis-Cluster (als "Später" notiert), Cold-Boot-Problematik (udev-Daemon gelöst). -**Ergebnis:** Keine BLOCKER mehr. Konzept ist wasserdicht für MVP-Phase. +**Dritte Iteration — Commander-Feedback:** +- Metadaten-Lookup VOR dem Ripping +- 100% Jellyfin-Kompatibilität +- Metadaten-Preview im UI +- Neue Risiken: TMDB-Matching-Fehler (mit Fallback), NFO-Format-Abhängigkeit (Hinweis), Pre-Scan-Latenz (Hinweis) ---- - -**Dritte Iteration — UEBERARBEITUNG (Commander-Feedback):** - -Änderungen: -- **Metadaten-Lookup VOR dem Ripping** eingefügt (Sek. 5, Schritt 5) -- **100% Jellyfin-Kompatibilität** hinzugefügt: NFO-Generator, Ordnerstruktur, Poster/Backdrop/Fanart-Download, Jellyfin-kompatible Dateibenennung (Sek. 4, Sek. 5, Sek. 6) -- **Metadaten-Preview im UI** als neuer UX-Schritt (Sek. 7, Schritt 3) -- **Neue Risiken**: TMDB-Matching-Fehler (offen, mit Fallback), NFO-Format-Abhängigkeit (Hinweis), Pre-Scan-Latenz (Hinweis), TMDB-Bildrechte (gelöst) - -**Kurzer Härte-Check der Änderungen (Advocatus Diaboli):** -Keine BLOCKER. Die Änderungen sind konsistent mit dem bestehenden Konzept: -- Pre-Scan fügt 5–15s hinzu, ist aber akzeptabel und parallelisierbar. -- Jellyfin-Formatierung ist ein klar definierter Output-Step nach dem Ripping. -- NFO-Generator nutzt Kodi/NFO-Schema (gut dokumentiert, stabil). -- TMDB-Matching bei Nischentiteln ist ein echtes Risiko, aber der manuelle Korrektur-Mechanismus (Preview + Confidence-Score) behandelt es angemessen. -- TMDB-Bildrechte sind für private Nutzung OK (TMDB API-ToS). - -**Ergebnis:** Konzept nach Commander-Feedback ist wasserdicht. +**Ergebnis:** Konzept ist wasserdicht für MVP-Phase. diff --git a/README.md b/README.md index 707e674..da9ee45 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Rippy — Automatisches CD/DVD/Blu-ray Ripping-System +# README — Rippy -> **Moderner Ripping-Daemon mit Metadaten-Preview, Jellyfin-Formatierung und Echtzeit-Status.** +> **Moderner Ripping-Daemon mit Metadaten-Preview, Jellyfin-Formatierung und JWT-Auth.** --- @@ -13,7 +13,7 @@ | Pre-Scan ohne Ripping | ✅ | | Jellyfin-Formatierung (NFO + Images) | ✅ | | JWT-Auth + Rate-Limiting | ✅ | -| React-UI mit Echtzeit-Updates | ✅ | +| React-UI mit Dashboard | ✅ | | SQLite-Cache für API-Rate-Limits | ✅ | | Multi-Disc-Set-Handling | ✅ | @@ -100,7 +100,7 @@ docker compose up -d - [x] Etappe 3: Metadaten-Lookup + Pre-Scan - [x] Etappe 4: Jellyfin-Formatierung - [x] Etappe 5: API + Auth + WebUI -- [ ] Etappe 6: Sicherheit + Compliance +- [x] Etappe 6: Sicherheit + Compliance - [ ] Etappe 7: Proxmox-Integration --- diff --git a/ROADMAP.md b/ROADMAP.md index 8540b65..79c70b0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -138,6 +138,8 @@ - GPL-v3-Compliance-Checkliste abgehakt - Backup-Hooks funktionieren +**Status:** Abgeschlossen + --- ## Etappe 7: Proxmox-Integration + Dokumentation