1.0.0 release snapshot

2026-06-12 11:17:44 +02:00
parent 6115090da1
commit c9ad6b2f06
274 changed files with 138472 additions and 1 deletions
@@ -0,0 +1,103 @@
+# Encode-Planung & Track-Auswahl
+
+Vor dem eigentlichen Encoding erstellt Ripster einen Encode-Plan und zeigt ihn im Review an.
+
+---
+
+## Ablauf
+
+```text
+Quelle bestimmen (Disc/RAW)
+  -> HandBrake-Scan (--scan --json)
+  -> Plan erstellen (Titel, Audio, Untertitel)
+  -> Status: Bereit zum Encodieren
+  -> Benutzer bestaetigt Auswahl
+  -> finaler HandBrake-Aufruf
+```
+
+---
+
+## Review-Inhalt (Status: `Bereit zum Encodieren`)
+
+- auswählbarer Encode-Titel
+- Audio-Track-Auswahl
+- Untertitel-Track-Auswahl inkl. Flags
+  - `burnIn`
+  - `forced`
+  - `defaultTrack`
+- optionale User-Presets (HandBrake Preset + Extra Args)
+- optionale Pre-/Post-Skripte und Ketten
+
+---
+
+## Bestaetigung (`confirm-encode`)
+
+Typischer Payload:
+
+```json
+{
+  "selectedEncodeTitleId": 1,
+  "selectedTrackSelection": {
+    "1": {
+      "audioTrackIds": [1, 2],
+      "subtitleTrackIds": [3]
+    }
+  },
+  "selectedPreEncodeScriptIds": [1],
+  "selectedPostEncodeScriptIds": [2],
+  "selectedPreEncodeChainIds": [3],
+  "selectedPostEncodeChainIds": [4],
+  "selectedUserPresetId": 5
+}
+```
+
+Die bestätigte Auswahl wird im Job gespeichert und für Neustarts wiederverwendet.
+
+---
+
+## HandBrake-Aufruf
+
+Grundstruktur:
+
+```bash
+HandBrakeCLI \
+  -i <input> \
+  -o <output> \
+  -t <titleId> \
+  -Z "<preset>" \
+  <extra-args> \
+  -a <audioTrackIds|none> \
+  -s <subtitleTrackIds|none>
+```
+
+Untertitel-Flags werden bei Bedarf ergänzt:
+
+- `--subtitle-burned=<id>`
+- `--subtitle-default=<id>`
+- `--subtitle-forced=<id>` oder `--subtitle-forced`
+
+---
+
+## Pre-/Post-Encode-Ausführungen
+
+- Pre-Encode läuft vor HandBrake
+- Post-Encode läuft nach HandBrake
+
+Fehlerverhalten:
+
+- Pre-Encode-Fehler: Job endet mit Status `Fehler` (Encode startet nicht)
+- Post-Encode-Fehler: Job kann `Fertig` bleiben, enthält aber Fehlerhinweis/Script-Summary
+
+---
+
+## Dateinamen/Ordner
+
+Der finale Outputpfad wird aus den Templates in den Settings aufgebaut.
+
+Platzhalter:
+
+- `${title}`
+- `${year}`
+- `${imdbId}`
+
+Ungültige Dateizeichen werden bereinigt.
@@ -0,0 +1,43 @@
+# Anhang: Pipeline intern
+
+Dieser Abschnitt beschreibt die technische Pipeline-Logik hinter den UI-Workflows.
+
+<div class="grid cards" markdown>
+
+-   :material-state-machine: **Workflow & Zustände**
+
+    ---
+
+    Zustandsmodell, Übergänge, Queue-Verhalten.
+
+    [:octicons-arrow-right-24: Workflow](workflow.md)
+
+-   :material-film: **Encode-Planung**
+
+    ---
+
+    Aufbereitung von Titeln/Tracks und Bestätigungslogik.
+
+    [:octicons-arrow-right-24: Encoding](encoding.md)
+
+-   :material-playlist-check: **Playlist-Analyse**
+
+    ---
+
+    Bewertung mehrdeutiger Blu-ray-Playlists.
+
+    [:octicons-arrow-right-24: Playlist-Analyse](playlist-analysis.md)
+
+-   :material-script-text: **Pre-/Post-Encode-Ausführungen**
+
+    ---
+
+    Skript- und Kettenlauf vor/nach dem Encoding.
+
+    [:octicons-arrow-right-24: Encode-Skripte](post-encode-scripts.md)
+
+</div>
+
+## Zurück zum Handbuch
+
+- [Workflows aus Nutzersicht](../workflows/index.md)
@@ -0,0 +1,68 @@
+# Playlist-Analyse
+
+Ripster analysiert bei Blu-ray-ähnlichen Quellen Playlists und fordert bei Mehrdeutigkeit eine manuelle Auswahl an.
+
+---
+
+## Ziel
+
+Erkennen, welche Playlist sehr wahrscheinlich der Hauptfilm ist, statt versehentlich eine Fake-/Dummy-Playlist zu verwenden.
+
+---
+
+## Eingabedaten
+
+Die Analyse basiert auf MakeMKV-Infos (u. a. Playlist-/Segment-Struktur, Laufzeiten, Titelzuordnung).
+
+---
+
+## Auswertung (vereinfacht)
+
+Für Kandidaten werden u. a. berücksichtigt:
+
+- Laufzeit
+- Segment-Reihenfolge
+- Rückwärtssprünge/große Sprünge
+- Kohärenz linearer Segmentfolgen
+- Duplikatgruppen mit ähnlicher Laufzeit
+
+Daraus entstehen intern Kandidatenlisten, Bewertungen und eine Empfehlung.
+
+---
+
+## Wann muss der Benutzer entscheiden?
+
+Wenn nach Filterung mehr als ein relevanter Kandidat übrig bleibt, wechselt der Job in der GUI auf:
+
+- `Warte auf Auswahl`
+
+Dann muss eine Playlist bestätigt werden, bevor der Workflow weiterläuft.
+
+---
+
+## Konfigurationseinfluss
+
+| Feld in `Settings` | Wirkung |
+|---|---|
+| `Minimale Titellänge (Minuten)` | Mindestlaufzeit für Kandidaten aus MakeMKV/Playlist-Analyse |
+| `TMDb Runtime-Abzug für Playlistfilter (%)` | lockert bei Bedarf die untere Laufzeitgrenze relativ zur TMDb-Laufzeit, damit leicht kürzere Hauptfassungen Kandidaten bleiben |
+
+Default ist aktuell `60` Minuten.
+
+---
+
+## UI-Verhalten
+
+Bei manueller Entscheidung zeigt der `Ripper` Kandidaten mit:
+
+- Playlist-Datei
+- Titel-ID
+- Laufzeit
+- Score
+- Empfehlung
+- Segment- und Audio-Vorschau
+
+Nach Bestätigung:
+
+- mit vorhandenem RAW -> zurück zu `Mediainfo-Pruefung`
+- ohne RAW -> Startpfad über `Startbereit` / `Rippen`
@@ -0,0 +1,70 @@
+# Encode-Skripte (Pre & Post)
+
+Ripster kann Skripte und Skript-Ketten vor und nach dem Encode ausführen.
+
+---
+
+## Ablauf
+
+```text
+Bereit zum Encodieren
+  -> Pre-Encode Skripte/Ketten
+  -> HandBrake Encoding
+  -> Post-Encode Skripte/Ketten
+  -> Fertig oder Fehler
+```
+
+---
+
+## Auswahl im Review
+
+Im Review-Panel kannst du getrennt wählen:
+
+- `selectedPreEncodeScriptIds`
+- `selectedPostEncodeScriptIds`
+- `selectedPreEncodeChainIds`
+- `selectedPostEncodeChainIds`
+
+---
+
+## Fehlerverhalten
+
+- Pre-Encode-Fehler stoppen die Kette und führen zu `Fehler`.
+- Post-Encode-Fehler stoppen die restlichen Post-Schritte; Job kann dennoch `Fertig` sein (mit Fehlerzusatz im Status/Log).
+
+---
+
+## Verfügbare Umgebungsvariablen
+
+Beim Script-Run werden gesetzt:
+
+- `RIPSTER_SCRIPT_RUN_AT`
+- `RIPSTER_JOB_ID`
+- `RIPSTER_JOB_TITLE`
+- `RIPSTER_MODE`
+- `RIPSTER_INPUT_PATH`
+- `RIPSTER_OUTPUT_PATH`
+- `RIPSTER_RAW_PATH`
+- `RIPSTER_SCRIPT_ID`
+- `RIPSTER_SCRIPT_NAME`
+- `RIPSTER_SCRIPT_SOURCE`
+
+---
+
+## Skript-Ketten
+
+Ketten unterstützen zwei Step-Typen:
+
+- `script` (führt ein hinterlegtes Skript aus)
+- `wait` (wartet `waitSeconds`)
+
+Bei Fehler in einem Script-Step wird die Kette abgebrochen.
+
+---
+
+## Testläufe
+
+- Skript testen: `POST /api/settings/scripts/:id/test`
+- Kette testen: `POST /api/settings/script-chains/:id/test`
+
+Ergebnisse enthalten Erfolg/Exit-Code, Laufzeit und stdout/stderr.
@@ -0,0 +1,101 @@
+# Workflow & Zustände
+
+Ripster steuert den Ablauf als Zustandsmaschine.
+
+---
+
+## Zustandsdiagramm (vereinfacht)
+
+```mermaid
+flowchart LR
+    A[Bereit] --> B[Medium erkannt]
+    B --> C[Analyse]
+    C --> D[Metadatenauswahl]
+    D --> E[Startbereit]
+    E --> F[Rippen]
+    E --> G[Mediainfo-Pruefung]
+    G --> H[Warte auf Auswahl]
+    H --> G
+    G --> I[Bereit zum Encodieren]
+    I --> J[Encodieren]
+    J --> K[Fertig]
+    J --> L[Fehler]
+    F --> L
+    F --> M[Abgebrochen]
+```
+
+---
+
+## Statusliste (GUI-Anzeige)
+
+| Status in der GUI | Bedeutung |
+|---|---|
+| `Bereit` | Wartet auf Disc |
+| `Medium erkannt` | Disc wurde erkannt |
+| `Analyse` | MakeMKV-Analyse läuft |
+| `Metadatenauswahl` | Metadaten müssen bestätigt werden |
+| `Warte auf Auswahl` | Playlist-Auswahl ist erforderlich |
+| `Warte auf Auswahl` | auch für RAW-Entscheidung bei vorhandenen Quelldaten genutzt |
+| `Startbereit` | kurzer Übergang vor Start |
+| `Rippen` | MakeMKV-Rip läuft |
+| `Mediainfo-Pruefung` | Titel/Spuren werden ausgewertet |
+| `Bereit zum Encodieren` | Review ist bereit |
+| `Encodieren` | HandBrake läuft |
+| `CD-Metadatenauswahl` | CD-Metadaten müssen bestätigt werden |
+| `CD-Startbereit` | CD-Job wartet auf Start |
+| `CD-Analyse` | CD-Track-/Strukturaufbereitung |
+| `CD-Rippen` | Audio-CD-Rip läuft |
+| `CD-Encodieren` | CD-Encode läuft |
+| `Fertig` | erfolgreich abgeschlossen |
+| `Abgebrochen` | manuell oder technisch abgebrochen |
+| `Fehler` | fehlgeschlagen |
+
+---
+
+## Typische Pfade
+
+### Standardfall (kein vorhandenes RAW)
+
+1. Medium erkannt
+2. Analyse + Metadaten
+3. Rippen
+4. Mediainfo-Pruefung
+5. Bereit zum Encodieren
+6. Encodieren
+7. Fertig
+
+### Vorhandenes RAW
+
+`Startbereit` springt direkt zu `Mediainfo-Pruefung` (kein neuer Rip).
+
+### Mehrdeutige Blu-ray-Playlist
+
+`Mediainfo-Pruefung` -> `Warte auf Auswahl` bis Playlist bestätigt wurde.
+
+### Vorhandenes RAW mit Nutzerentscheidung
+
+`Metadatenauswahl` -> `Warte auf Auswahl` bis Entscheidung für Weiterverarbeitung (`continue`) oder Neustart getroffen wurde.
+
+### CD-Flow
+
+`CD-Metadatenauswahl` -> `CD-Startbereit` -> `CD-Rippen` -> `CD-Encodieren` -> `Fertig`
+
+---
+
+## Queue-Verhalten
+
+Wenn der Wert `Parallele Jobs` erreicht ist:
+
+- neue Starts werden als Queue-Einträge abgelegt
+- die Queue kann zusätzlich Nicht-Job-Einträge enthalten (`Skript`, `Kette`, `Warten`)
+- Reihenfolge ist per UI/API änderbar
+
+---
+
+## Abbruch, Wiederaufnahme, Neustart
+
+- `Abbrechen`: laufenden Job stoppen oder Queue-Eintrag entfernen
+- `Retry Rippen`: Fehler-/Abbruch-Job erneut starten
+- `RAW neu encodieren`: aus vorhandenem RAW neu encodieren
+- `Review neu starten`: Review aus RAW neu aufbauen
+- `Encode neu starten`: Encoding mit letzter bestätigter Auswahl neu starten