From 922d3e753d88ad3f43254a401809a658114f6182 Mon Sep 17 00:00:00 2001 From: mboehmlaender Date: Thu, 5 Mar 2026 10:04:50 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Doku=20f=C3=BCr=20Skript-Integration=20?= =?UTF-8?q?und=20neue=20Pipeline-Zust=C3=A4nde?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/pipeline.md | 156 +++++++++---------- docs/api/settings.md | 133 ++++++++++++++++ docs/pipeline/index.md | 8 + docs/pipeline/playlist-analysis.md | 16 +- docs/pipeline/post-encode-scripts.md | 163 ++++++++++++++++++++ docs/pipeline/workflow.md | 223 ++++++++++++++++++--------- mkdocs.yml | 3 +- 7 files changed, 543 insertions(+), 159 deletions(-) create mode 100644 docs/pipeline/post-encode-scripts.md diff --git a/docs/api/pipeline.md b/docs/api/pipeline.md index 069a155..f4458b9 100644 --- a/docs/api/pipeline.md +++ b/docs/api/pipeline.md @@ -27,28 +27,49 @@ Gibt den aktuellen Pipeline-Zustand zurück. } ``` -**States:** +**Pipeline-Zustände:** | Wert | Beschreibung | |------|-------------| | `IDLE` | Wartet auf Disc | -| `ANALYZING` | MakeMKV analysiert | -| `METADATA_SELECTION` | Wartet auf Benutzer | +| `DISC_DETECTED` | Disc erkannt, wartet auf Benutzer | +| `METADATA_SELECTION` | Disc-Scan läuft / Metadaten-Dialog | +| `WAITING_FOR_USER_DECISION` | Mehrere Playlist-Kandidaten – manuelle Auswahl | | `READY_TO_START` | Bereit zum Starten | -| `RIPPING` | Rippen läuft | -| `MEDIAINFO_CHECK` | Track-Analyse | -| `READY_TO_ENCODE` | Wartet auf Bestätigung | -| `ENCODING` | Encoding läuft | +| `RIPPING` | MakeMKV-Ripping läuft | +| `MEDIAINFO_CHECK` | HandBrake-Scan & Encode-Plan-Erstellung | +| `READY_TO_ENCODE` | Wartet auf Encode-Bestätigung | +| `ENCODING` | HandBrake encodiert | +| `POST_ENCODE_SCRIPTS` | Post-Encode-Skripte laufen | | `FINISHED` | Abgeschlossen | | `ERROR` | Fehler | +**Kontext-Felder (state-abhängig):** + +Beim Zustand `WAITING_FOR_USER_DECISION` enthält die Response zusätzlich: + +```json +{ + "state": "WAITING_FOR_USER_DECISION", + "context": { + "playlistAnalysis": { + "evaluatedCandidates": [...], + "recommendation": { "playlistId": "00800", "score": 18 }, + "manualDecisionRequired": true, + "manualDecisionReason": "multiple_candidates_after_min_length" + }, + "playlistCandidates": ["00800", "00801", "00900"] + } +} +``` + --- ## POST /api/pipeline/analyze -Startet eine manuelle Disc-Analyse (ohne Disc-Detection-Trigger). +Startet eine manuelle Disc-Analyse. -**Request:** Kein Body erforderlich +**Request:** Kein Body **Response:** @@ -65,11 +86,7 @@ Startet eine manuelle Disc-Analyse (ohne Disc-Detection-Trigger). Erzwingt eine erneute Disc-Erkennung. -**Response:** - -```json -{ "ok": true } -``` +**Response:** `{ "ok": true }` --- @@ -81,27 +98,17 @@ Sucht in der OMDb-API nach einem Filmtitel. | Parameter | Typ | Beschreibung | |----------|-----|-------------| -| `q` | string | Suchbegriff (Filmtitel) | +| `q` | string | Suchbegriff | | `type` | string | `movie` oder `series` (optional) | -**Beispiel:** - -``` -GET /api/pipeline/omdb/search?q=Inception&type=movie -``` +**Beispiel:** `GET /api/pipeline/omdb/search?q=Inception&type=movie` **Response:** ```json { "results": [ - { - "imdbId": "tt1375666", - "title": "Inception", - "year": "2010", - "type": "movie", - "poster": "https://m.media-amazon.com/images/..." - } + { "imdbId": "tt1375666", "title": "Inception", "year": "2010", "type": "movie", "poster": "https://..." } ] } ``` @@ -110,7 +117,7 @@ GET /api/pipeline/omdb/search?q=Inception&type=movie ## POST /api/pipeline/select-metadata -Bestätigt Metadaten und Playlist-Auswahl für den aktuellen Job. +Bestätigt Metadaten und optionale Playlist-Auswahl. **Request:** @@ -124,31 +131,28 @@ Bestätigt Metadaten und Playlist-Auswahl für den aktuellen Job. "type": "movie", "poster": "https://..." }, - "playlist": "00800.mpls" + "selectedPlaylist": "00800" } ``` -`playlist` ist optional und nur bei Blu-rays relevant. +!!! info "Playlist-Felder" + `selectedPlaylist` ist optional. Wird es beim ersten Aufruf weggelassen (kein Obfuskierungsverdacht), wird die Empfehlung automatisch übernommen. -**Response:** + Beim zweiten Aufruf aus dem `WAITING_FOR_USER_DECISION`-Dialog reicht es, nur `jobId` + `selectedPlaylist` zu schicken – `omdb` kann dann weggelassen werden. -```json -{ "ok": true } -``` +**Response:** `{ "ok": true }` --- ## POST /api/pipeline/start/:jobId -Startet den Ripping-Prozess für einen vorbereiteten Job. +Startet den Ripping-Prozess. -**URL-Parameter:** `jobId` – ID des Jobs +**URL-Parameter:** `jobId` -**Response:** +**Response:** `{ "ok": true, "message": "Ripping gestartet" }` -```json -{ "ok": true, "message": "Ripping gestartet" } -``` +**Sonderfall:** Falls für den Job bereits eine Raw-Datei vorhanden ist, wird das Ripping übersprungen und direkt der HandBrake-Scan gestartet. **Fehlerfälle:** - `404` – Job nicht gefunden @@ -158,40 +162,45 @@ Startet den Ripping-Prozess für einen vorbereiteten Job. ## POST /api/pipeline/confirm-encode/:jobId -Bestätigt die Encode-Konfiguration mit Track-Auswahl. +Bestätigt die Encode-Konfiguration mit Track-Auswahl und Post-Encode-Skripten. -**URL-Parameter:** `jobId` – ID des Jobs +**URL-Parameter:** `jobId` **Request:** ```json { - "audioTracks": [1, 2], - "subtitleTracks": [1] + "selectedEncodeTitleId": 1, + "selectedTrackSelection": { + "1": { + "audioTrackIds": [1, 2], + "subtitleTrackIds": [1] + } + }, + "selectedPostEncodeScriptIds": ["script-abc123", "script-def456"] } ``` -Track-Indizes entsprechen den 1-basierten Track-Nummern aus dem Encode-Plan. +| Feld | Typ | Beschreibung | +|------|-----|-------------| +| `selectedEncodeTitleId` | number | HandBrake-Titel-ID (aus dem Encode-Plan) | +| `selectedTrackSelection` | object | Pro Titel: Audio- und Untertitel-Track-IDs | +| `selectedPostEncodeScriptIds` | string[] | Skript-IDs in Ausführungsreihenfolge (optional) | -**Response:** +!!! note "Track-IDs" + Die Track-IDs entsprechen den `id`-Feldern aus dem Encode-Plan (`encode_plan_json`), nicht den rohen HandBrake-Track-Nummern. -```json -{ "ok": true, "message": "Encoding gestartet" } -``` +**Response:** `{ "ok": true, "message": "Encoding gestartet" }` --- ## POST /api/pipeline/cancel -Bricht den aktuellen Pipeline-Prozess ab. +Bricht den aktiven Pipeline-Prozess ab. -**Response:** +**Response:** `{ "ok": true, "message": "Pipeline abgebrochen" }` -```json -{ "ok": true, "message": "Pipeline abgebrochen" } -``` - -Der laufende Prozess wird mit SIGINT beendet (Fallback: SIGKILL nach Timeout). +SIGINT → graceful exit (10 s Timeout) → SIGKILL. --- @@ -199,13 +208,7 @@ Der laufende Prozess wird mit SIGINT beendet (Fallback: SIGKILL nach Timeout). Wiederholt einen fehlgeschlagenen Job. -**URL-Parameter:** `jobId` – ID des Jobs - -**Response:** - -```json -{ "ok": true, "message": "Job wird wiederholt" } -``` +**Response:** `{ "ok": true, "message": "Job wird wiederholt" }` **Fehlerfälle:** - `404` – Job nicht gefunden @@ -215,35 +218,28 @@ Wiederholt einen fehlgeschlagenen Job. ## POST /api/pipeline/resume-ready/:jobId -Setzt einen Job im Status `READY_TO_ENCODE` zurück in die aktive Pipeline. +Reaktiviert einen Job im Status `READY_TO_ENCODE` in die aktive Pipeline (z. B. nach Neustart). -**URL-Parameter:** `jobId` – ID des Jobs - -**Response:** - -```json -{ "ok": true } -``` +**Response:** `{ "ok": true }` --- ## POST /api/pipeline/reencode/:jobId -Startet ein erneutes Encoding für einen abgeschlossenen Job (ohne erneutes Ripping). - -**URL-Parameter:** `jobId` – ID des Jobs +Encodiert eine abgeschlossene Raw-MKV erneut – ohne Ripping. **Request:** ```json { - "audioTracks": [1, 2], - "subtitleTracks": [1] + "selectedEncodeTitleId": 1, + "selectedTrackSelection": { + "1": { "audioTrackIds": [1, 2], "subtitleTrackIds": [1] } + }, + "selectedPostEncodeScriptIds": ["script-abc123"] } ``` -**Response:** +Gleiche Struktur wie `confirm-encode` – ermöglicht andere Track-Auswahl und Skripte als beim ersten Encoding. -```json -{ "ok": true, "message": "Re-Encoding gestartet" } -``` +**Response:** `{ "ok": true, "message": "Re-Encoding gestartet" }` diff --git a/docs/api/settings.md b/docs/api/settings.md index f01d1ce..58f6194 100644 --- a/docs/api/settings.md +++ b/docs/api/settings.md @@ -113,6 +113,139 @@ Sendet eine Test-Benachrichtigung über PushOver. --- +## Skript-Verwaltung + +Post-Encode-Skripte werden über eigene Endpunkte unter `/api/settings/scripts` verwaltet. + +### GET /api/settings/scripts + +Gibt alle konfigurierten Skripte zurück. + +**Response:** + +```json +{ + "scripts": [ + { + "id": "script-abc123", + "name": "Zu Plex verschieben", + "command": "/home/michael/scripts/move-to-plex.sh", + "description": "Verschiebt die fertige Datei ins Plex-Verzeichnis", + "createdAt": "2024-01-15T10:00:00.000Z" + } + ] +} +``` + +--- + +### POST /api/settings/scripts + +Legt ein neues Post-Encode-Skript an. + +**Request:** + +```json +{ + "name": "Zu Plex verschieben", + "command": "/home/michael/scripts/move-to-plex.sh", + "description": "Verschiebt die fertige Datei ins Plex-Verzeichnis" +} +``` + +| Feld | Typ | Pflicht | Beschreibung | +|------|-----|---------|-------------| +| `name` | string | ✅ | Anzeigename | +| `command` | string | ✅ | Shell-Befehl oder absoluter Skriptpfad | +| `description` | string | — | Optionale Beschreibung | + +**Response:** + +```json +{ + "ok": true, + "script": { + "id": "script-abc123", + "name": "Zu Plex verschieben", + "command": "/home/michael/scripts/move-to-plex.sh" + } +} +``` + +--- + +### PUT /api/settings/scripts/:scriptId + +Aktualisiert ein vorhandenes Skript. + +**URL-Parameter:** `scriptId` + +**Request:** Gleiche Felder wie beim Anlegen (alle optional). + +```json +{ "name": "Zu Jellyfin verschieben", "command": "/home/michael/scripts/move-to-jellyfin.sh" } +``` + +**Response:** `{ "ok": true }` + +--- + +### DELETE /api/settings/scripts/:scriptId + +Löscht ein Skript. + +**URL-Parameter:** `scriptId` + +**Response:** `{ "ok": true }` + +!!! warning "Referenzen in Jobs" + Wenn das Skript in laufenden oder abgeschlossenen Jobs referenziert wird, wird es trotzdem gelöscht. In zukünftigen Encode-Reviews erscheint es nicht mehr. + +--- + +### POST /api/settings/scripts/:scriptId/test + +Führt ein Skript mit Platzhalter-Umgebungsvariablen aus (Testlauf). + +**URL-Parameter:** `scriptId` + +**Response (Erfolg):** + +```json +{ + "ok": true, + "exitCode": 0, + "stdout": "Testausgabe des Skripts", + "stderr": "", + "durationMs": 245 +} +``` + +**Response (Fehler):** + +```json +{ + "ok": false, + "exitCode": 1, + "stdout": "", + "stderr": "Datei nicht gefunden: /home/michael/scripts/move-to-plex.sh", + "durationMs": 12 +} +``` + +**Platzhalter-Werte beim Testlauf:** + +| Variable | Testwert | +|---------|---------| +| `RIPSTER_OUTPUT_PATH` | `/tmp/ripster-test-output.mkv` | +| `RIPSTER_JOB_ID` | `0` | +| `RIPSTER_TITLE` | `Test Film` | +| `RIPSTER_YEAR` | `2024` | +| `RIPSTER_IMDB_ID` | `tt0000000` | +| `RIPSTER_RAW_PATH` | `/tmp/ripster-test-raw.mkv` | + +--- + ## Einstellungs-Schlüssel Referenz Eine vollständige Liste aller Einstellungs-Schlüssel: diff --git a/docs/pipeline/index.md b/docs/pipeline/index.md index e8b2db5..0844339 100644 --- a/docs/pipeline/index.md +++ b/docs/pipeline/index.md @@ -28,4 +28,12 @@ Der Pipeline-Abschnitt beschreibt den Kern-Workflow von Ripster. [:octicons-arrow-right-24: Playlist-Analyse](playlist-analysis.md) +- :material-script-text: **Post-Encode-Skripte** + + --- + + Automatische Ausführung von Shell-Skripten nach erfolgreichem Encoding – z. B. zum Verschieben oder Benachrichtigen. + + [:octicons-arrow-right-24: Post-Encode-Skripte](post-encode-scripts.md) + diff --git a/docs/pipeline/playlist-analysis.md b/docs/pipeline/playlist-analysis.md index 7397d4b..6f2324c 100644 --- a/docs/pipeline/playlist-analysis.md +++ b/docs/pipeline/playlist-analysis.md @@ -84,7 +84,6 @@ Alle Titel werden nach **ähnlicher Laufzeit** gruppiert (±90 Sekunden Toleranz ``` 8 Titel mit ~148 Minuten Laufzeit → Duplikat-Gruppe → obfuscationDetected = true -→ manualDecisionRequired = true ``` ### Schritt 5 – Besten Kandidaten empfehlen (`scoreCandidates`) @@ -98,19 +97,28 @@ Innerhalb der größten Duplikat-Gruppe werden alle Kandidaten sortiert nach: Der **erste Kandidat** der sortierten Liste ist die Empfehlung. +### Schritt 6 – Entscheidung erzwingen bei mehreren Kandidaten + +Sobald nach `MIN_LENGTH_MINUTES` **mehr als eine** Playlist übrig bleibt, wird immer eine manuelle Auswahl verlangt: + +``` +candidateCount > 1 → manualDecisionRequired = true +candidateCount <= 1 → manualDecisionRequired = false +``` + --- ## Wann greift der Benutzer ein? ``` obfuscationDetected = duplicateDurationGroups.length > 0 -manualDecisionRequired = obfuscationDetected +manualDecisionRequired = candidates.length > 1 ``` | Ergebnis | Nächster Pipeline-Zustand | Aktion | |---------|--------------------------|--------| -| Keine Duplikat-Gruppen | `READY_TO_START` | Empfehlung wird automatisch übernommen | -| Duplikat-Gruppen gefunden | `WAITING_FOR_USER_DECISION` | Benutzer muss Playlist auswählen | +| Nur ein Kandidat nach Mindestlänge | `READY_TO_START` | Automatische Übernahme möglich | +| Mehrere Kandidaten nach Mindestlänge | `WAITING_FOR_USER_DECISION` | Benutzer muss Playlist auswählen | --- diff --git a/docs/pipeline/post-encode-scripts.md b/docs/pipeline/post-encode-scripts.md new file mode 100644 index 0000000..348bc7e --- /dev/null +++ b/docs/pipeline/post-encode-scripts.md @@ -0,0 +1,163 @@ +# Post-Encode-Skripte + +Post-Encode-Skripte ermöglichen es, nach erfolgreichem Encoding automatisch beliebige Shell-Befehle oder Programme auszuführen – z. B. zum Verschieben von Dateien, Benachrichtigen externer Dienste oder Auslösen weiterer Verarbeitungsschritte. + +--- + +## Funktionsweise + +Nach einem erfolgreich abgeschlossenen Encoding-Schritt führt Ripster die konfigurierten Skripte **sequenziell** in der festgelegten Reihenfolge aus: + +``` +ENCODING abgeschlossen + ↓ +Skript 1 ausführen ← Fehler? → Abbruch + ↓ +Skript 2 ausführen ← Fehler? → Abbruch + ↓ + ... + ↓ +FINISHED +``` + +!!! warning "Abbruch bei Fehler" + Schlägt ein Skript fehl (Exit-Code ≠ 0), werden alle nachfolgenden Skripte **nicht mehr ausgeführt**. Der Job wechselt in den Status `ERROR`. + +--- + +## Skript-Verwaltung + +Skripte werden über die **Einstellungen-Seite** angelegt und verwaltet. Sie stehen danach in jedem Encode-Review zur Auswahl. + +### Skript anlegen + +Navigiere zu **Einstellungen → Skripte** und klicke **"Neues Skript"**: + +| Feld | Beschreibung | +|------|-------------| +| **Name** | Anzeigename des Skripts (z. B. `Zu Plex verschieben`) | +| **Befehl** | Shell-Befehl oder Skriptpfad (z. B. `/home/michael/scripts/move-to-plex.sh`) | +| **Beschreibung** | Optionale Erklärung | + +### Verfügbare Umgebungsvariablen + +Jedes Skript wird mit folgenden Umgebungsvariablen aufgerufen: + +| Variable | Inhalt | Beispiel | +|---------|--------|---------| +| `RIPSTER_OUTPUT_PATH` | Absoluter Pfad der encodierten Datei | `/mnt/movies/Inception (2010).mkv` | +| `RIPSTER_JOB_ID` | Job-ID in der Datenbank | `42` | +| `RIPSTER_TITLE` | Filmtitel | `Inception` | +| `RIPSTER_YEAR` | Erscheinungsjahr | `2010` | +| `RIPSTER_IMDB_ID` | IMDb-ID | `tt1375666` | +| `RIPSTER_RAW_PATH` | Pfad zur Raw-MKV-Datei | `/mnt/raw/Inception-2010/t00.mkv` | + +### Beispiel-Skript: Datei nach Jellyfin verschieben + +```bash +#!/bin/bash +# /home/michael/scripts/move-to-jellyfin.sh + +TARGET_DIR="/mnt/media/movies" +mkdir -p "$TARGET_DIR" +mv "$RIPSTER_OUTPUT_PATH" "$TARGET_DIR/" +echo "Verschoben: $RIPSTER_TITLE nach $TARGET_DIR" +``` + +### Beispiel-Skript: Webhook auslösen + +```bash +#!/bin/bash +# /home/michael/scripts/notify-webhook.sh + +curl -s -X POST https://mein-webhook.example.com/ripster \ + -H "Content-Type: application/json" \ + -d "{\"title\": \"$RIPSTER_TITLE\", \"year\": \"$RIPSTER_YEAR\", \"path\": \"$RIPSTER_OUTPUT_PATH\"}" +``` + +--- + +## Skript im Encode-Review auswählen + +Im `READY_TO_ENCODE`-Zustand zeigt das **MediaInfoReviewPanel** einen Skript-Abschnitt: + +``` +┌──────────────────────────────────────────────────────────┐ +│ Post-Encode-Skripte │ +├──────────────────────────────────────────────────────────┤ +│ Ausgewählte Skripte (Reihenfolge per Drag & Drop): │ +│ ≡ 1. Zu Plex verschieben [Entfernen]│ +│ ≡ 2. Webhook auslösen [Entfernen]│ +├──────────────────────────────────────────────────────────┤ +│ Skript hinzufügen: [Zu Jellyfin verschieben ▾] [+ Hinzuf.]│ +└──────────────────────────────────────────────────────────┘ +``` + +- **Reihenfolge** per Drag & Drop ändern +- **Hinzufügen** aus der Dropdown-Liste aller konfigurierten Skripte +- **Entfernen** einzelner Skripte aus der aktuellen Auswahl +- Skripte können pro Job unterschiedlich gewählt werden + +--- + +## Skript testen + +Über die Einstellungen kann jedes Skript mit einem Test-Job ausgeführt werden: + +```http +POST /api/settings/scripts/:scriptId/test +``` + +Der Test-Aufruf befüllt die Umgebungsvariablen mit Platzhalter-Werten. + +--- + +## Ausführungs-Ergebnis + +Das Ergebnis der Skript-Ausführung wird im Job-Datensatz gespeichert und in der History angezeigt: + +```json +{ + "postEncodeScripts": { + "configured": 2, + "succeeded": 2, + "failed": 0, + "skipped": 0, + "aborted": false, + "results": [ + { + "scriptId": "script-1", + "name": "Zu Plex verschieben", + "exitCode": 0, + "stdout": "Verschoben: Inception nach /mnt/media/movies", + "stderr": "", + "durationMs": 342 + }, + { + "scriptId": "script-2", + "name": "Webhook auslösen", + "exitCode": 0, + "stdout": "", + "stderr": "", + "durationMs": 128 + } + ] + } +} +``` + +| Feld | Beschreibung | +|------|-------------| +| `configured` | Anzahl ausgewählter Skripte | +| `succeeded` | Erfolgreich ausgeführt (Exit-Code 0) | +| `failed` | Fehlgeschlagen | +| `skipped` | Nicht ausgeführt (wegen vorherigem Fehler) | +| `aborted` | `true`, wenn die Kette abgebrochen wurde | + +--- + +## API-Referenz + +Eine vollständige API-Dokumentation der Skript-Endpunkte findest du unter: + +[:octicons-arrow-right-24: Settings API – Skripte](../api/settings.md#skript-verwaltung) diff --git a/docs/pipeline/workflow.md b/docs/pipeline/workflow.md index 01c05fc..69de26a 100644 --- a/docs/pipeline/workflow.md +++ b/docs/pipeline/workflow.md @@ -8,27 +8,36 @@ Der Ripping-Workflow von Ripster ist als **State Machine** implementiert. Jeder ```mermaid stateDiagram-v2 - direction LR + direction TB [*] --> IDLE - IDLE --> ANALYZING: Disc erkannt\n(automatisch) - ANALYZING --> METADATA_SELECTION: MakeMKV-Analyse\nabgeschlossen - METADATA_SELECTION --> READY_TO_START: Benutzer wählt\nMetadaten + Playlist + IDLE --> DISC_DETECTED: Disc erkannt + DISC_DETECTED --> METADATA_SELECTION: Analyse starten - READY_TO_START --> RIPPING: Benutzer startet\nden Job + METADATA_SELECTION --> READY_TO_START: Kein Obfuskierungsverdacht\n(ein Kandidat) + METADATA_SELECTION --> WAITING_FOR_USER_DECISION: Mehrere Playlist-Kandidaten\n→ manuelle Auswahl nötig - RIPPING --> MEDIAINFO_CHECK: MKV/Backup\nerstellt - MEDIAINFO_CHECK --> READY_TO_ENCODE: Track-Analyse\nabgeschlossen + WAITING_FOR_USER_DECISION --> READY_TO_START: Playlist bestätigt - READY_TO_ENCODE --> ENCODING: Benutzer bestätigt\nEncode + Tracks + READY_TO_START --> RIPPING: Starten\n(kein Raw vorhanden) + READY_TO_START --> MEDIAINFO_CHECK: Starten\n(Raw bereits vorhanden) - ENCODING --> FINISHED: HandBrake\nfertig - FINISHED --> IDLE: Disc auswerfen /\nneue Disc + RIPPING --> MEDIAINFO_CHECK: MKV/Backup erstellt + + MEDIAINFO_CHECK --> READY_TO_ENCODE: Track-Scan\nabgeschlossen + + READY_TO_ENCODE --> ENCODING: Tracks + Skripte\nbestätigt + + ENCODING --> POST_ENCODE_SCRIPTS: Erfolg\n(Skripte konfiguriert) + ENCODING --> FINISHED: Erfolg\n(keine Skripte) + POST_ENCODE_SCRIPTS --> FINISHED: Alle Skripte\nerfolgt RIPPING --> ERROR: Fehler ENCODING --> ERROR: Fehler - ANALYZING --> ERROR: Fehler - ERROR --> IDLE: cancelPipeline()\noder retryJob() + POST_ENCODE_SCRIPTS --> ERROR: Skript-Fehler + + ERROR --> IDLE: Abbrechen / Retry + FINISHED --> IDLE: Neue Disc ``` --- @@ -39,51 +48,88 @@ stateDiagram-v2 **Ausgangszustand.** Ripster wartet auf eine Disc. -- `diskDetectionService` pollt das Laufwerk (Intervall konfigurierbar) -- Bei Disc-Erkennung: Automatischer Übergang zu `ANALYZING` +- `diskDetectionService` pollt das Laufwerk im konfigurierten Intervall +- Bei Disc-Erkennung: automatischer Übergang zu `DISC_DETECTED` - WebSocket-Event: `DISC_DETECTED` --- -### ANALYZING +### DISC_DETECTED -**MakeMKV analysiert die Disc-Struktur.** +**Disc erkannt, wartet auf Benutzeraktion.** -```bash -makemkvcon -r info disc:0 -``` +- Dashboard zeigt **"Neue Disc erkannt"**-Badge +- **"Analyse starten"**-Button wird aktiv +- Kein Prozess läuft noch -- Liest Titel-Informationen, Playlist-Liste, Track-Details -- Fortschritt wird über WebSocket übertragen -- Bei Blu-ray: Playlist-Liste für spätere Analyse gesammelt -- Dauer: 30 Sekunden bis 5 Minuten - -**Ausgabe:** JSON-Struktur mit allen Titeln und Playlists +**Übergang:** Benutzer klickt "Analyse starten" → `METADATA_SELECTION` --- ### METADATA_SELECTION -**Wartet auf Benutzer-Eingabe.** +**Disc-Info-Scan läuft, danach Benutzer-Eingabe.** -- `MetadataSelectionDialog` wird im Frontend angezeigt -- Benutzer sucht in OMDb nach dem Filmtitel -- Benutzer wählt einen Eintrag aus den Suchergebnissen -- Bei Blu-ray: Playlist-Auswahl (mit Empfehlung durch `playlistAnalysis.js`) +1. MakeMKV wird im Info-Modus gestartet und liest alle Titel/Playlists +2. OMDb-Vorsuche mit erkanntem Disc-Label +3. `MetadataSelectionDialog` öffnet sich mit vorgeladenen Ergebnissen +4. Benutzer wählt Filmtitel (oder gibt manuell ein) +5. Nach Bestätigung: **Playlist-Analyse** läuft sofort durch -**Übergang:** `selectMetadata(jobId, omdbData, playlist)` aufrufen +**Übergang (automatisch nach Playlist-Analyse):** + +| Ergebnis der Analyse | Nächster Zustand | +|--------------------|-----------------| +| Nur ein Kandidat nach Mindestlänge | `READY_TO_START` | +| Mehrere Kandidaten nach Mindestlänge | `WAITING_FOR_USER_DECISION` | + +--- + +### WAITING_FOR_USER_DECISION + +**Playlist-Obfuskierung erkannt – manuelle Auswahl erforderlich.** + +!!! info "Neu seit „Skript Integration + UI Anpassungen"" + Dieser Zustand wurde eingeführt, um Blu-rays mit mehreren Playlists ähnlicher Länge korrekt zu behandeln. + +- Playlist-Auswahl-Dialog wird im Dashboard angezeigt +- Alle Kandidaten mit Score, Laufzeit und Bewertungslabel +- Empfohlene Playlist ist vorausgewählt +- Benutzer bestätigt mit **"Playlist übernehmen"** + +**Darstellung im Dashboard:** + +``` +┌──────────────────────────────────────────────────────────┐ +│ Playlist-Auswahl erforderlich │ +│ Es wurden mehrere Titel mit ähnlicher Laufzeit gefunden. │ +├──────────┬──────────┬────────┬──────────────────────────┤ +│ Playlist │ Laufzeit │ Score │ Bewertung │ +├──────────┼──────────┼────────┼──────────────────────────┤ +│ ● 00800 │ 2:28:05 │ +18 │ wahrscheinlich korrekt │ +│ ○ 00801 │ 2:28:12 │ −4 │ Auffällige Segmentfolge │ +│ ○ 00900 │ 2:28:05 │ −32 │ Fake-Struktur │ +└──────────┴──────────┴────────┴──────────────────────────┘ + [Playlist übernehmen] +``` + +**Übergang:** `selectMetadata(jobId, { selectedPlaylist })` → `READY_TO_START` + +Mehr Details: [Playlist-Analyse](playlist-analysis.md) --- ### READY_TO_START -**Metadaten bestätigt, bereit zum Starten.** +**Metadaten und Playlist bestätigt, bereit zum Starten.** -- Job-Datensatz in Datenbank mit Metadaten aktualisiert -- Start-Button im Dashboard aktiv -- Benutzer kann Metadaten noch mal ändern +- Job-Datensatz in Datenbank aktualisiert +- **"Starten"**-Button im Dashboard aktiv -**Übergang:** `startJob(jobId)` aufrufen +**Sonderfall – Raw-Datei bereits vorhanden:** +Wenn für diesen Job bereits eine geri rippte Raw-Datei im `raw_dir` existiert (Pfad-Match über Metadaten-Basis), überspringt Ripster den Ripping-Schritt und springt direkt zum HandBrake-Scan. + +**Übergang:** `startJob(jobId)` → `RIPPING` oder direkt `MEDIAINFO_CHECK` --- @@ -94,8 +140,7 @@ makemkvcon -r info disc:0 === "MKV-Modus (Standard)" ```bash - makemkvcon mkv disc:0 all /path/to/raw/ \ - --minlength=900 + makemkvcon mkv disc:0 all /path/to/raw/ --minlength=900 -r ``` Erstellt MKV-Datei(en) direkt aus den gewählten Titeln. @@ -103,45 +148,49 @@ makemkvcon -r info disc:0 === "Backup-Modus" ```bash - makemkvcon backup disc:0 /path/to/raw/backup/ \ - --decrypt + makemkvcon backup disc:0 /path/to/raw/backup/ --decrypt -r ``` Erstellt vollständiges Disc-Backup inkl. Menüs. -**Live-Updates:** Fortschritt wird zeilenweise aus MakeMKV-Ausgabe geparst: +**Live-Updates** aus MakeMKV-Ausgabe: ``` -PRGC:5012,0,2048 → Fortschritt: X% -PRGT:5011,0,"..." → Aktueller Task +PRGV:2048,0,65536 → Fortschritt-Berechnung +PRGT:5011,0,"..." → Aktueller Task-Name ``` +**Typische Dauer:** DVD 20–45 min · Blu-ray 45–120 min + --- ### MEDIAINFO_CHECK -**MediaInfo analysiert die gerippte Datei.** +**HandBrake-Scan und Encode-Plan-Erstellung.** -```bash -mediainfo --Output=JSON /path/to/raw/file.mkv -``` +Dieser Zustand umfasst zwei Phasen: -- Liest alle Audio-, Untertitel- und Video-Tracks -- Extrahiert Codec-Informationen (DTS, TrueHD, AC-3, ...) -- Bestimmt Sprachcodes (ISO 639) -- Erstellt Encode-Plan via `encodePlan.js` +1. **HandBrake-Scan** (`HandBrakeCLI --scan`) auf Disc oder Raw-Datei +2. **Encode-Plan-Erstellung** mit automatischer Track-Vorauswahl + +Kein Benutzereingriff – läuft automatisch durch. + +**Übergang:** → `READY_TO_ENCODE` --- ### READY_TO_ENCODE -**Encode-Plan erstellt, wartet auf Bestätigung.** +**Encode-Plan bereit, wartet auf Benutzer-Bestätigung.** -- `MediaInfoReviewPanel` wird im Frontend angezeigt -- Benutzer kann Audio- und Untertitel-Tracks de/aktivieren -- Vorgeschlagene Tracks basierend auf Sprach-Einstellungen +Das `MediaInfoReviewPanel` zeigt: -**Übergang:** `confirmEncode(jobId, trackSelection)` aufrufen +- **Titel-Auswahl** (bei Discs mit mehreren langen Titeln) +- **Audio-Tracks** mit Encoder-Vorschau (Copy/Transcode/Fallback) +- **Untertitel-Tracks** mit Flags (Einbrennen, Forced, Default) +- **Post-Encode-Skripte** – Auswahl und Reihenfolge der auszuführenden Skripte + +**Übergang:** `confirmEncodeReview(jobId, { tracks, scripts })` → `ENCODING` --- @@ -151,27 +200,56 @@ mediainfo --Output=JSON /path/to/raw/file.mkv ```bash HandBrakeCLI \ - --input /path/to/raw.mkv \ - --output /path/to/movies/Inception\ \(2010\).mkv \ + -i -o \ + -t \ --preset "H.265 MKV 1080p30" \ - --audio 1,2 \ - --subtitle 1 + -a 1,2 -E copy:ac3,av_aac \ + -s 1 --subtitle-default 1 ``` -**Live-Updates:** Fortschritt wird aus HandBrake-stderr geparst: +**Live-Updates** aus HandBrake-stderr: ``` -Encoding: task 1 of 1, 73.50 % +Encoding: task 1 of 1, 73.50 % (45.23 fps, avg 44.12 fps, ETA 00h12m34s) ``` --- +### POST_ENCODE_SCRIPTS + +**Post-Encode-Skripte werden ausgeführt.** + +!!! info "Neu seit „Skript Integration + UI Anpassungen"" + Post-Encode-Skripte ermöglichen es, nach erfolgreichem Encoding automatisch Aktionen auszuführen. + +- Skripte werden **sequenziell** in der konfigurierten Reihenfolge ausgeführt +- Bei Fehler eines Skripts: restliche Skripte werden **abgebrochen** +- Ergebnis-Zusammenfassung wird im Job-Datensatz gespeichert: + +```json +{ + "configured": 2, + "succeeded": 2, + "failed": 0, + "skipped": 0, + "aborted": false +} +``` + +Dieser Zustand wird nur erreicht, wenn im Encode-Review mindestens ein Skript ausgewählt wurde. + +**Übergang:** → `FINISHED` (alle Skripte erfolgreich) oder `ERROR` (Skript-Fehler) + +Details: [Post-Encode-Skripte](post-encode-scripts.md) + +--- + ### FINISHED **Job erfolgreich abgeschlossen.** - Ausgabedatei liegt im konfigurierten `movie_dir` -- Job-Status in Datenbank auf `FINISHED` gesetzt +- Job-Status in Datenbank: `FINISHED` - PushOver-Benachrichtigung (falls konfiguriert) - WebSocket-Event: `JOB_COMPLETE` @@ -182,8 +260,8 @@ Encoding: task 1 of 1, 73.50 % **Fehler aufgetreten.** - Fehlerdetails im Job-Datensatz gespeichert -- Fehler-Logs verfügbar in der History -- **Retry**: Job kann vom Fehlerzustand neu gestartet werden +- Fehler-Logs in History abrufbar +- **Retry**: Neustart vom Fehlerzustand - **Abbrechen**: Pipeline zurück zu IDLE --- @@ -196,10 +274,8 @@ Encoding: task 1 of 1, 73.50 % POST /api/pipeline/cancel ``` -- Sendet SIGINT an aktiven Prozess -- Wartet auf graceful exit (Timeout: 10 Sekunden) -- Falls kein graceful exit: SIGKILL -- Pipeline-Zustand zurück zu IDLE +- SIGINT → graceful exit (Timeout: 10 s) → SIGKILL +- Pipeline zurück zu IDLE ### Job wiederholen @@ -207,9 +283,8 @@ POST /api/pipeline/cancel POST /api/pipeline/retry/:jobId ``` -- Setzt Job-Status zurück auf `READY_TO_START` -- Behält Metadaten und Playlist-Auswahl -- Pipeline neu starten mit vorhandenen Daten +- Setzt Job zurück auf `READY_TO_START` +- Metadaten und Playlist-Auswahl bleiben erhalten ### Re-Encode @@ -218,5 +293,5 @@ POST /api/pipeline/reencode/:jobId ``` - Encodiert bestehende Raw-MKV neu -- Nützlich für geänderte Encoding-Einstellungen -- Kein neues Ripping erforderlich +- Ermöglicht neue Track-Auswahl und andere Skripte +- Kein Ripping erforderlich diff --git a/mkdocs.yml b/mkdocs.yml index 26fade2..d4d9063 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,8 +60,9 @@ nav: - Pipeline: - pipeline/index.md - Workflow & Zustände: pipeline/workflow.md - - Encode-Planung: pipeline/encoding.md + - Encode-Planung & Track-Auswahl: pipeline/encoding.md - Playlist-Analyse: pipeline/playlist-analysis.md + - Post-Encode-Skripte: pipeline/post-encode-scripts.md - API-Referenz: - api/index.md - Pipeline API: api/pipeline.md