0.14.0-4 Docs

2026-04-21 14:52:30 +00:00
parent c27a81cdb1
commit ccd6c3ab2a
29 changed files with 999 additions and 691 deletions
@@ -1,60 +1,68 @@
 # Audiobooks

-Die Seite `Audiobooks` ist die dedizierte Oberfläche für AAX- und Audiobook-Jobs.
+Die Seite `Audiobooks` ist der spezialisierte AAX-Workflow.

---
+## Ablaufübersicht

-## Aufbau
+Die Oberfläche ist in drei Bereiche gegliedert:

 1. `Audiobooks Upload`
 2. `Audiobook Jobs`
 3. `Audiobook Output Explorer`

---
-
 ## 1) Audiobooks Upload

-Hier werden AAX-Dateien hochgeladen und als Job vorbereitet.
+Der Upload verarbeitet ausschließlich AAX-Dateien.

-Typische Schritte:
+Direkt nach Upload passieren im Hintergrund:

-1. Datei auswählen
-2. optional Format/Startverhalten setzen
-3. Upload starten
+- Probe/Metadatenanalyse (ffprobe)
+- Anlage eines RAW-Ordners per `Audiobook RAW Template`
+- Ablage der AAX-Datei im RAW-Pfad
+- Initiale Jobkonfiguration (Format, Kapitel, Metadaten)

-Während des Uploads zeigt die Seite Fortschritt und Status an.
+Wichtige Parameter:

---
+- Zielformat (`m4b`, `mp3`, `flac`)
+- optionaler Sofortstart
+
+Toolabhängigkeit:
+
+- `ffprobe_command` für Metadaten/Kapitel
+- `ffmpeg_command` für Encode/Cover-Extraktion

 ## 2) Audiobook Jobs

-Aktive Audiobook-Jobs werden als Karten dargestellt (mit Status und Fortschritt).
+Jobkarten zeigen Zustand, Fortschritt und verfügbare Aktionen.

-Pro Job sind je nach Zustand Aktionen verfügbar:
+Typische Aktionen:

- Starten (mit aktueller Audiobook-Konfiguration)
- Abbrechen
- Retry
- Löschen
+- `Starten`
+- `Abbrechen`
+- `Retry`
+- `Löschen`
+- `Im Ripper` (Kontextwechsel)

-Zusätzlich:
-
- `Im Ripper` springt in die Hauptansicht
- Jobs laden periodisch nach und reagieren auf WebSocket-Updates
-
---
+Die Karten werden regelmäßig aktualisiert und durch WebSocket-Ereignisse ergänzt.

 ## 3) Audiobook Output Explorer

-Read-only Baumansicht des konfigurierten Audiobook-Ausgabeordners:
+Read-only Explorer des Audiobook-Outputpfads:

- Ordner- und Dateiansicht
- Größen-/Zeitstempelübersicht
- schnelle Kontrolle der erzeugten Ergebnisse
+- Ordner-/Dateistruktur
+- Zeitstempel/Größen
+- schnelle Ergebnisprüfung ohne Dateisystemwechsel

---
+## Pfad- und Template-Logik

-## Abgrenzung zum Converter
+| Bereich | Gesteuert durch |
+|---|---|
+| RAW-Ablage | `raw_dir_audiobook` + `audiobook_raw_template` |
+| Finale Ausgabe | `movie_dir_audiobook` + `output_template_audiobook` |
+| Dateiformat | Jobkonfiguration (`m4b`, `mp3`, `flac`) |

-Audio/Video-Datei-Konvertierung läuft weiterhin auf der Seite `Converter`.
-Der AAX-spezifische Flow (Upload, Start, Jobsteuerung, Output-Explorer) liegt auf `Audiobooks`.
+## Typische Probleme
+
+- Upload wird abgelehnt: Eingabedatei ist keine AAX-Datei.
+- Start schlägt fehl: `ffmpeg`/`ffprobe` nicht aufrufbar.
+- Unerwartete Pfade: Templates enthalten ungültige oder zu generische Platzhalter.
@@ -1,85 +1,108 @@
 # Converter

-Die Converter-Seite ermöglicht das Konvertieren vorhandener Audio- und Video-Dateien.
+Die Seite `Converter` verarbeitet bereits vorhandene Dateien (Video, Audio, ISO) ohne Laufwerks-Rip.

---
+## Betriebsmodell

-## Überblick
+Der Converter arbeitet auf dem Eingangspfad `converter_raw_dir`:

-Der Converter arbeitet mit einem konfigurierbaren Eingangsordner (`converter_raw_dir`). Dateien werden dort abgelegt (manuell oder per Upload) und dann als Converter-Jobs in die Pipeline eingereiht.
+- Uploads landen dort
+- Explorer-Aktionen arbeiten dort
+- daraus werden Converter-Jobs erstellt

---
+Wichtig:
+
+- Upload erzeugt nicht automatisch einen Job.
+- Joberstellung erfolgt explizit über Auswahl im Explorer.

 ## Datei-Explorer

-Der Datei-Explorer zeigt den Inhalt des `converter_raw_dir` als Baumstruktur.
+Der Explorer zeigt den kompletten Baum unter `converter_raw_dir`.

-### Verfügbare Aktionen
+Aktionen:

-| Aktion | Beschreibung |
+| Aktion | Wirkung |
 |---|---|
-| **Upload** | Dateien direkt aus dem Browser hochladen (bis zu 50 Dateien) |
-| **Ordner erstellen** | Neuen Unterordner anlegen |
-| **Umbenennen** | Datei oder Ordner umbenennen |
-| **Verschieben** | Datei oder Ordner in einen anderen Unterordner verschieben |
-| **Löschen** | Datei oder Ordner löschen (unwiderruflich) |
-| **Scannen** | Eingangsordner manuell neu scannen |
+| `Upload` | Dateien werden in den Raw-Baum geschrieben |
+| `Ordner erstellen` | legt Unterordner im Raw-Baum an |
+| `Umbenennen` | benennt Datei/Ordner im Raw-Baum um |
+| `Verschieben` | verschiebt innerhalb des Raw-Baums |
+| `Löschen` | entfernt Datei/Ordner dauerhaft |
+| `Scannen` | synchronisiert Explorer und DB-Zuordnungen |

-### Dateiauswahl
+Upload-Regeln:

-Dateien können per Checkbox ausgewählt werden. Aus der Auswahl lassen sich Jobs erstellen:
+- Dateiendung muss in `Erlaubte Datei-Endungen*` enthalten sein
+- bei Verstoß wird der Upload abgelehnt

- **Ein Job pro Datei** — jede Datei wird als eigenständiger Job angelegt
- **Gemeinsamer Job (Audio)** — mehrere Audio-Dateien werden zu einem gemeinsamen Job zusammengefasst
+## Joberstellung aus Explorer-Auswahl

-Erlaubte Dateiendungen werden in den Settings unter `Converter > Erlaubte Datei-Endungen*` als Checkboxen konfiguriert.
+Es gibt zwei Audio-Strategien:

---
+1. `Ein Job pro Datei`
+2. `Gemeinsamer Job (Audio)`

-## Jobs erstellen und konfigurieren
+Verhalten:

-Nach der Auswahl und Job-Erstellung erscheinen die Jobs in der Job-Liste.
+- Video/ISO werden grundsätzlich als Einzeljobs angelegt.
+- Audio kann als Shared-Job mit mehreren Eingabedateien erzeugt werden.

-### Job-Konfiguration
+Shared-Audio-Job:

-Jeder Job kann konfiguriert werden:
+- hält mehrere `inputPaths`
+- kann vor Start erweitert/reduziert werden (nur Audio-Dateien)

- **Medientyp:** Video, Audio oder Audiobook
- **Ausgabeformat:** z. B. `mkv`, `mp4`, `m4b`, `mp3`, `flac`
- **HandBrake-Preset:** für Video-Konvertierung
- **Track-Auswahl:** Video-, Audio- und Untertitel-Spuren
- **Metadaten:** Titel, Autor, Jahr (für Audiobooks)
- **MusicBrainz-Suche:** automatische Metadaten-Suche für Audiodateien
+## Job-Konfiguration

-### Job-Start
+Vor Start je Job einstellbar:

-Jobs starten sofort oder reihen sich in die Queue ein (abhängig von `Parallele Jobs`).
+- `converterMediaType` (`video`, `audio`, `iso`)
+- `outputFormat`
+- Metadaten
+- Track-/Titelwahl (bei video/iso)
+- Pre-/Post-Encode-Skripte und Ketten

---
+Spezifika:
+
+- Video/ISO laufen durch Mediainfo/Review ähnlich zum Disc-Flow.
+- Audio kann direkt mit Formatoptionen konfiguriert werden.
+
+## Ausgabe-Pfade
+
+### Video/ISO
+
+- Root: `converter_movie_dir`
+- Dateiname: `Output-Template (Video)`
+- Endung: aus gewähltem Output-Format
+
+### Audio
+
+- Root: `converter_audio_dir`
+- Dateiname/Ordner: `Output-Template (Audio)`
+- bei Shared-/Folder-Job: Ausgabe als Ordnerstruktur mit Trackdateien
+
+## Queue und Start
+
+Converter-Jobs laufen über dieselbe Pipeline-/Queue-Logik:
+
+- sofortiger Start wenn Limits frei
+- sonst Queue-Eintrag
+
+Parallelität richtet sich nach den globalen Encode-Limits in `Settings`.

 ## Auto-Scan (Polling)

-Wenn in den Settings `Converter > Auto-Scan (Polling)` aktiviert ist, wird der Eingangsordner automatisch in regelmäßigen Abständen gescannt. Neue Dateien werden in der DB erfasst und im Explorer angezeigt.
+Mit aktiviertem Polling:

-Das Scan-Intervall wird unter `Converter > Polling-Intervall (Sekunden)` konfiguriert (Standard: 300 Sekunden).
+- `converter_raw_dir` wird zyklisch gescannt
+- neue Dateien erscheinen automatisch im Explorer

---
+Relevante Settings:

-## Hinweis zu Audiobooks
+- `Auto-Scan (Polling)`
+- `Polling-Intervall (Sekunden)`

-Der dedizierte AAX-/Audiobook-Flow ist auf der Seite [Audiobooks](audiobooks.md) dokumentiert.
+## Abgrenzung zu Audiobooks

---
-
-## Einstellungen
-
-| Setting | Pfad in GUI |
-|---|---|
-| Eingangsordner | `Settings > Pfade > Converter Raw-Ordner` |
-| Videoausgabe | `Settings > Pfade > Converter Ausgabe (Video)` |
-| Audioausgabe | `Settings > Pfade > Converter Ausgabe (Audio)` |
-| Erlaubte Endungen | `Settings > Converter > Erlaubte Datei-Endungen*` |
-| Auto-Scan | `Settings > Converter > Auto-Scan (Polling)` |
-| Scan-Intervall | `Settings > Converter > Polling-Intervall (Sekunden)` |
-| Output-Template Video | `Settings > Pfade > Output-Template (Video)` |
-| Output-Template Audio | `Settings > Pfade > Output-Template (Audio)` |
+- `Converter`: beliebige Audio/Video/ISO-Dateien
+- `Audiobooks`: dedizierter AAX-Workflow mit Kapitel-/Audiobook-Metadaten
@@ -1,29 +1,35 @@
 # Database (Expert)

-`/database` ist eine erweiterte Ansicht für Power-User und Recovery-Fälle.
+`/database` ist die Recovery- und Expertensicht für Fälle, in denen Dateisystem und Historie nicht mehr sauber zusammenpassen.

 ## Zugriff

- Route direkt aufrufen: `/database`
- nicht Teil der Standard-Navigation
+- direkte Route: `/database`
+- nicht Teil der Standardnavigation

-## Bereiche
+## Bereich `Gefundene RAW-Einträge`

-### `Gefundene RAW-Einträge`
-
-Listet RAW-Ordner, die keinen zugehörigen Job-Eintrag haben.
+Dieser Bereich listet RAW-Verzeichnisse ohne zugeordneten Historie-Job.

 Aktionen:

- `RAW prüfen` (Scan der konfigurierten RAW-Pfade)
- `Job anlegen` (Orphan-RAW in Historie importieren)
+- `RAW prüfen`: scannt konfigurierte RAW-Wurzeln
+- `Job anlegen`: erstellt aus einem orphan RAW einen neuen Historie-Job

-## Typischer Einsatz
+## Was bei `Job anlegen` passiert

- nach manuellen Dateioperationen
- nach Migrationen oder Recovery
- wenn RAW-Dateien vorhanden sind, aber kein Historieneintrag existiert
+- RAW-Pfad wird als Importquelle registriert
+- Job wird in die Historie geschrieben
+- anschließende Analyse läuft als RAW-basierter Einstieg (ohne klassischen Disc-Read)

-## Vorsicht
+Typischer Einsatz:

-Diese Seite erlaubt Eingriffe mit direkter Auswirkung auf Datenbestand und Historie. Vor Lösch- oder Importaktionen Pfade und Zieljob sorgfältig prüfen.
+- manuelle Dateioperationen außerhalb der UI
+- Migrationen
+- Wiederherstellung nach abgebrochenen Läufen
+
+## Sicherheits- und Betriebsregeln
+
+- Aktionen wirken direkt auf produktive Historie/Dateipfade.
+- Vor Import oder Löschung immer Pfad und Ziel prüfen.
+- Diese Seite nur für Recovery-Szenarien nutzen, nicht für normalen Tagesbetrieb.
@@ -1,53 +1,58 @@
 # Downloads

-Die Downloads-Seite ermöglicht es, Ausgabedateien aus abgeschlossenen Jobs als ZIP-Archiv herunterzuladen.
+Auf `Downloads` werden ZIP-Archive für Historie-Artefakte erstellt und bereitgestellt.

---
+## Was heruntergeladen werden kann

-## Überblick
+Ein Download-Eintrag referenziert immer einen Historie-Job und genau ein Ziel:

-Jobs, die in der Historie abgeschlossen sind, können in die Download-Queue eingereiht werden. Ripster erstellt daraus ein ZIP-Archiv, das direkt im Browser heruntergeladen werden kann.
+- `RAW`
+- `Output`

---
+Erzeugt wird ein ZIP-Archiv im Download-Verzeichnis des Backends.

-## Download-Queue
+## Statusmodell

-Die Queue zeigt alle aktuellen Download-Einträge mit ihrem Status:
-
-| Status | Beschreibung |
+| Status | Bedeutung |
 |---|---|
-| **Ausstehend** | In der Queue, ZIP-Erstellung noch nicht gestartet |
-| **Wird verarbeitet** | ZIP-Archiv wird gerade erstellt |
-| **Bereit** | ZIP fertig, Download-Button verfügbar |
-| **Fehlgeschlagen** | Fehler bei der ZIP-Erstellung |
+| `queued` | Eintrag erstellt, wartet auf Verarbeitung |
+| `processing` | ZIP wird gerade gebaut |
+| `ready` | Archiv fertig, Download-Link aktiv |
+| `failed` | Erzeugung oder Zugriff fehlgeschlagen |

---
+## Eintrag anlegen

-## Download einreihen
+Startpunkt ist die `Historie`:

-Downloads können über die **Historie** eingereiht werden:
+1. Job öffnen.
+2. Download einreihen.
+3. Ziel (`RAW` oder `Output`) wählen.
+4. Status in `Downloads` verfolgen.

-1. Job in der Historie öffnen
-2. **Download einreihen** wählen
-3. Ziel auswählen: `RAW-Dateien` oder `Ausgabedateien`
-4. Den Eintrag in der Downloads-Queue verfolgen
+## Wichtige Laufzeitdetails

---
+- Wenn bereits ein passendes, aktuelles Archiv existiert, kann der Eintrag wiederverwendet werden.
+- Nach Backend-Neustart werden unterbrochene `queued`/`processing`-Einträge geprüft und fortgesetzt.
+- Fehlt eine erwartete ZIP-Datei bei `ready`, wird der Eintrag auf `failed` gesetzt.

-## Download starten
+## Download auslösen

-Sobald der Status **Bereit** angezeigt wird, kann die ZIP-Datei mit dem Download-Button heruntergeladen werden.
+Bei Status `ready`:

-ZIP-Dateinamen folgen dem Muster: `Job_<id>_<target>.zip`
+- Download-Button lädt die ZIP direkt aus `/api/downloads/:id/file`.

---
+## Einträge entfernen

-## Einträge löschen
+`Löschen` entfernt:

-Abgeschlossene oder fehlerhafte Einträge können einzeln gelöscht werden. Die dazugehörige ZIP-Datei wird dabei ebenfalls vom Server entfernt.
+- Queue-Metadaten
+- zugehörige Archivdatei

---
+Nicht erlaubt:

-## Echtzeit-Updates
+- Löschen während `queued`/`processing`

-Die Downloads-Seite aktualisiert sich automatisch per WebSocket (`DOWNLOADS_UPDATED`). Statusänderungen (z. B. von `Wird verarbeitet` zu `Bereit`) werden ohne Seiten-Reload angezeigt.
+## Echtzeitaktualisierung
+
+Die Seite reagiert auf `DOWNLOADS_UPDATED` per WebSocket.
+Dadurch sind Statuswechsel ohne Reload sichtbar.
@@ -1,88 +1,89 @@
 # Historie

-Die Seite `Historie` ist für Suche, Prüfung und Nachbearbeitung bestehender Jobs.
+`Historie` ist die Kontroll- und Nachbearbeitungsoberfläche für alle bereits angelegten Jobs.

 ## Hauptansicht

-Filter und Werkzeuge:
+Filter und Arbeitsmittel:

- Suche (Titel/IMDb)
- Status-Filter
- Medium-Filter (`Blu-ray`, `DVD`, `Sonstiges`)
+- Suche (Titel, IMDb, Kontextbegriffe)
+- Statusfilter
+- Mediumfilter
 - Sortierung
 - Listen-/Grid-Layout

-Jeder Eintrag zeigt:
+Jeder Eintrag zeigt auf einen Blick:

- Poster, Titel, Jahr, IMDb
- Medium-Indikator
- Status
- Start/Ende
- Verfügbarkeit von RAW/Movie
- Ratings (wenn OMDb-Daten vorhanden)
+- Titel, Jahr, Poster
+- Status und Zeitstempel
+- RAW-/Output-Verfügbarkeit
+- Medien- und ggf. Containerhinweise

-Klick auf einen Eintrag öffnet die Detailansicht.
+## Detaildialog: Was dort zusammenläuft

---
+Der Detaildialog bündelt:

-## Job-Detaildialog
+- Metadaten (Film oder Serie)
+- Jobstatus und Fehlertexte
+- RAW-/Output-Pfade
+- Encode-Plan und Trackauswahl
+- ausgeführte Kommandodetails
+- Prozesslog (`Tail` oder vollständig)

-Bereiche:
+Bei Seriencontainern wird disk-/child-orientiert dargestellt, nicht nur als Einzeljob.

- Film-Infos + OMDb-Details
- Job-Infos (Status, Pfade, Erfolgsflags, Fehler)
- hinterlegte Encode-Auswahl
- ausgeführter HandBrake-Befehl
- strukturierte JSON-Blöcke (OMDb/MakeMKV/MediaInfo/EncodePlan/HandBrake)
- Log-Ladefunktionen (`Tail`, `Vollständig`)
+## Nachbearbeitungsaktionen und Wirkung

-Bei Serien-Containern zeigt der Dialog statt eines globalen Log-Blocks einen `Disks`-Bereich mit einzelnen Disk-Akkordeons.
-Jede Disk kann dort separat geprüft und bearbeitet werden.
+| Aktion | Typischer Einsatz | Technische Wirkung |
+|---|---|---|
+| `OMDb neu zuordnen` | falsches Match, Titel/Jahr korrigieren | Metadatenfelder werden neu geschrieben; Folder-Rename wird best effort angestoßen |
+| `Review neu starten` | neue Track-/Titelbewertung nötig | Mediainfo/Review wird aus RAW neu aufgebaut |
+| `RAW neu encodieren` | neuer Encode aus vorhandenem RAW | startet Encode ohne neuen Laufwerks-Rip |
+| `Encode neu starten` | gleiche bestätigte Auswahl erneut fahren | letzter bestätigter Plan wird geladen, optional mit Bereinigung unvollständiger Ausgabe |
+| `Retry Rippen` | Rip/Analyse neu anstoßen | neuer Rip-Lauf, inkl. erneuter RAW-Phase |

-## Typische Aktionen im Detaildialog
+Löschaktionen im Dialog:

- `OMDb neu zuordnen`
- `Encode neu starten`
- `Review neu starten`
- `RAW neu encodieren`
- `RAW löschen`, `Movie löschen`, `Beides löschen`
+- `RAW löschen`
+- `Movie löschen`
+- `Beides löschen`
 - `Historieneintrag löschen`
- bei Queue-Lock: `Aus Queue löschen`

-Zusätzlich bei Serien-Container-Disks:
+## Löschvorschau und selektives Löschen

- `Im Ripper öffnen` (für `READY_TO_ENCODE`-Kinder)
- diskbezogene Löschaktionen (`RAW`, `Folgen`, `Beides`) mit Child-/Subjob-Scope
- diskbezogenes Löschen des Historieneintrags (inkl. Subjobs)
+Vor endgültigem Löschen zeigt Ripster eine Vorschau mit:

-## Wann welche Aktion?
+- `RAW`-Kandidaten
+- `Movie`-/Episoden-Kandidaten
+- Related-Scope (Container/Kinder/verbundene Jobs)

-| Ziel | Aktion |
-|---|---|
-| Metadaten korrigieren | `OMDb neu zuordnen` |
-| mit gleicher bestätigter Auswahl neu encodieren | `Encode neu starten` |
-| Titel-/Spurprüfung komplett neu berechnen | `Review neu starten` |
-| aus vorhandenem RAW erneut encodieren | `RAW neu encodieren` |
-| Speicher freigeben | Dateilöschaktionen |
+Wichtige Punkte:

---
+- Pfade sind selektierbar.
+- Für RAW-Löschung muss bei Mehrfachkandidaten mindestens ein RAW-Pfad gewählt werden.
+- Schutzlogik verhindert Löschungen außerhalb erlaubter Root-Verzeichnisse.

-## Löschen mit Vorschau
+## Serien- und Multipart-Sicht in der Historie

-Beim Löschen eines Historieneintrags (`Eintrag löschen`) gibt es eine Pfadvorschau:
+### Serien

- getrennt nach `RAW` und Ausgabe (`Movie`/`Folgen`)
- für Serien-/Multipart-Fälle mit Scope auf verknüpfte Jobs
- selektierbare Pfade vor dem finalen Löschen
+- Container zeigt aggregierten Zustand aus Child-Jobs.
+- Disk-/Episode-Aktionen können child-spezifisch ausgeführt werden.
+- `Im Ripper öffnen` hilft bei `Bereit zum Encodieren`-Kindern.

-Neu im RAW-Bereich:
+### Multipart

- bei mehreren RAW-Kandidaten kann pro Pfad gewählt werden, was entfernt wird
- mindestens ein RAW-Pfad muss gewählt sein, wenn RAW-Löschung Teil der Aktion ist
+- gemeinsamer Container mit Disc-Childs
+- Disc-Nummern bleiben pro Child nachvollziehbar
+- Delete-Preview kann Related-Pfade gemeinsam auflösen

-Die Buttons (`Eintrag + nur RAW`, `Eintrag + nur ...`, `Eintrag + RAW + ...`) berücksichtigen die aktuelle Pfadauswahl und deaktivieren sich bei unvollständiger Auswahl.
+## Logs sinnvoll nutzen

-## Logs
+- `Tail laden (800)` für schnellen Fehlerkontext
+- `Vollständiges Log laden` für forensische Analyse

- `Tail laden (800)` für schnelle Fehleranalyse
- `Vollständiges Log laden` für vollständige Nachverfolgung
+Empfehlung:
+
+1. Erst Tail prüfen.
+2. Bei Pfad-/Toolproblemen vollständiges Log laden.
+3. Danach passende Wiederanlauf-Aktion wählen.
@@ -1,32 +1,34 @@
 # GUI-Seiten

-Ripster hat sieben Hauptseiten in der Navigation plus eine Expert-Seite.
+Dieses Kapitel ist das Bedienhandbuch für die Oberflächen im Alltag.

 ## Seitenüberblick

-| Seite | Zweck |
-|---|---|
-| [Jobs](jobs.md) | zentrale Inbox mit allen Jobs (Ripper, Converter, Audiobooks) |
-| [Ripper](ripper.md) | Live-Betrieb: Pipeline, Queue, Aktivitäten, Disc-Infos |
-| [Audiobooks](audiobooks.md) | AAX-Upload, Audiobook-Jobsteuerung und Output-Explorer |
-| [Settings](settings.md) | Konfiguration, Skripte, Ketten, Presets, Cronjobs |
-| [Historie](history.md) | abgeschlossene/laufende Jobs durchsuchen und nachbearbeiten |
-| [Converter](converter.md) | Audio/Video-Dateien konvertieren, Datei-Explorer, Upload |
-| [Downloads](downloads.md) | Ausgabedateien als ZIP herunterladen |
-| [Database (Expert)](database.md) | tabellarische Rohsicht inkl. Orphan-RAW-Import |
+| Seite | Rolle im Betrieb | Typischer Einsatz |
+|---|---|---|
+| [Jobs](jobs.md) | zentrale Inbox | Gesamtlage prüfen und in Fachseite springen |
+| [Ripper](ripper.md) | Live-Steuerung der Pipeline | Disc-Flow starten, Queue steuern, Review freigeben |
+| [Audiobooks](audiobooks.md) | AAX-Spezialflow | Upload, Konfiguration und Encode von Audiobooks |
+| [Settings](settings.md) | Konfiguration/Automatisierung | Pfade, Tools, Queue-Limits, Skripte, Cron |
+| [Historie](history.md) | Nachbearbeitung und Kontrolle | Logs, Re-Encode, Löschvorschau, Recovery-Aktionen |
+| [Converter](converter.md) | dateibasierte Konvertierung | Video/Audio/ISO ohne Disc-Rip verarbeiten |
+| [Downloads](downloads.md) | ZIP-Exports | RAW/Output aus Historie bereitstellen |
+| [Database (Expert)](database.md) | Recovery-Sicht | orphan RAW finden und importieren |

-## Empfohlene Nutzung im Alltag
+## Empfohlener Tagesablauf

-1. **Ersten Überblick über alle Jobs:** `Jobs`
-2. **Start eines neuen Disc-Jobs:** `Ripper`
-3. **Audio/Video-Dateien konvertieren:** `Converter`
-4. **AAX/Audiobook-Flow:** `Audiobooks`
-5. **Regeln/Automatisierung anpassen:** `Settings`
-6. **Ergebnisse prüfen oder Jobs nachbearbeiten:** `Historie`
-7. **Dateien herunterladen:** `Downloads`
-8. **Sonderfälle/Recovery:** `Database`
+1. `Jobs`: Statuslage und Auffälligkeiten prüfen.
+2. `Ripper` oder `Converter`/`Audiobooks`: neue Arbeit starten.
+3. `Historie`: Ergebnisse validieren und ggf. nachbearbeiten.
+4. `Downloads`: Exporte für externe Übergabe erzeugen.
+5. `Settings`: Regeln und Limits nur kontrolliert anpassen.

-## Hinweise zur Navigation
+## Navigation

- `Jobs`, `Ripper`, `Converter`, `Audiobooks`, `Settings`, `Historie` und `Downloads` sind direkt in der Kopfnavigation.
- `Database` ist als Expert-Route verfügbar: `/database`.
+Direkt in der Top-Navigation:
+
+- `Jobs`, `Ripper`, `Converter`, `Audiobooks`, `Settings`, `Historie`, `Downloads`
+
+Nur per URL:
+
+- `Database` unter `/database`
@@ -1,22 +1,18 @@
 # Jobs

-Die Seite `Jobs` ist die zentrale Inbox über alle Job-Typen.
+`Jobs` ist die zentrale Inbox über alle Jobarten und dient als schneller Einstieg in den Tagesbetrieb.

---
+## Zweck der Seite

-## Zweck
+Die Liste vereinheitlicht:

-`Jobs` zeigt denselben Datenbestand in einer einheitlichen Liste:
-
- Ripper-Jobs (Blu-ray/DVD/CD)
- Converter-Jobs (Audio/Video/ISO)
+- Disc-/Ripper-Jobs
+- Converter-Jobs
 - Audiobook-Jobs

-Die Seite eignet sich als schneller Einstieg, bevor man in den jeweiligen Fachbereich springt.
+Dadurch kannst du unabhängig von der Fachseite zuerst den Gesamtzustand prüfen.

---
-
-## Filter und Ansicht
+## Filterlogik

 ### View-Filter

@@ -31,26 +27,28 @@ Die Seite eignet sich als schneller Einstieg, bevor man in den jeweiligen Fachbe
 - `Aktiv`
 - `Fehler/Abbruch`

-Zusätzlich gibt es eine Freitextsuche (Titel, Status, IMDb, Job-Kind etc.) und eine Paginierung.
+Zusätzlich:

---
+- Freitextsuche
+- Paginierung

-## Was ein Eintrag zeigt
+## Was ein Jobeintrag zeigt

 - Job-ID und Titel
- Status-Badge (inkl. Queue-Berücksichtigung)
- Job-Typ-Badge (z. B. Blu-ray, Converter Audio, Audiobook)
- Zeitstempel der letzten Aktualisierung
+- Statusbadge
+- Jobtypbadge (z. B. Blu-ray, DVD, Converter Audio, Audiobook)
+- Aktualisierungszeit

-Die Liste aktualisiert sich zyklisch automatisch.
+Die Ansicht wird periodisch aktualisiert und ergänzt sich mit WebSocket-Events.

---
+## Schnellaktion pro Zeile

-## Aktion
-
-Pro Eintrag gibt es einen Schnellzugriff:
-
- `Im Ripper öffnen` für Disc-/Audiobook-orientierte Jobs
+- `Im Ripper öffnen` für Disc-/Audiobook-nahe Jobs
 - `Im Converter öffnen` für Converter-Jobs

-So gelangst du mit einem Klick in die passende Detailoberfläche.
+So kommst du ohne Umwege in die Oberfläche mit den passenden Detailaktionen.
+
+## Empfohlener Einsatz
+
+1. In `Jobs` Störungen und Auslastung identifizieren.
+2. Danach gezielt in `Ripper`, `Converter` oder `Historie` springen.
@@ -1,8 +1,8 @@
 # Ripper

-Das Ripper ist die **Betriebszentrale** für laufende Jobs.
+Die Seite `Ripper` ist die Live-Steuerung der Pipeline. Hier laufen Disc-Erkennung, Queue-Steuerung, Review und Encode-Start zusammen.

-## Aufbau der Seite
+## Seitenaufbau und Betriebslogik

 Die Bereiche erscheinen in dieser Reihenfolge:

@@ -12,129 +12,157 @@ Die Bereiche erscheinen in dieser Reihenfolge:
 4. `Job Übersicht`
 5. `Disk-Information`

---
-
 ## 1) Hardware Monitoring

-Zeigt live:
+Zeigt kontinuierlich:

- CPU (gesamt + optional pro Kern)
- RAM
- GPU-Auslastung/Temperatur/VRAM
- freien Speicher in den konfigurierten Pfaden
+- CPU / RAM
+- GPU (wenn verfügbar)
+- freie Speicherstände konfigurierter Pfade

-Wichtig für den Betrieb:
+Nutzen im Betrieb:

- Hohe Speicherauslastung oder fast volle Zielpfade früh erkennen
- über `Settings` aktivierbar/deaktivierbar (`Hardware Monitoring aktiviert`)
+- Engpässe vor Jobfehlern erkennen
+- Pfadfüllstände vor Start großer Batchs prüfen
+
+Gesteuert über `Settings`:
+
+- `Hardware Monitoring aktiviert`
+- `Hardware Monitoring Intervall (ms)`

 ## 2) Job Queue

-Zwei Spalten:
+Es gibt zwei operative Zonen:

 - `Laufende Jobs`
 - `Warteschlange`

-Mögliche Aktionen:
+Mögliche Queue-Einträge:

- Queue per Drag-and-Drop umsortieren
- Queue-Job entfernen (`X`)
- zusätzliche Queue-Elemente einfügen (`+`):
-  - Skript
-  - Skriptkette
-  - Wartezeit
+- Job-Startaktionen (`Start`, `Retry Rippen`, `RAW neu encodieren`, `Encode neu starten`, `Review neu berechnen`, `Audio CD starten`)
+- Nicht-Job-Einträge (`Skript`, `Skriptkette`, `Warten`)

-Hinweis:
+Wichtige Regeln:

- `Parallel` zeigt den Wert aus `Settings` -> `Parallele Jobs`.
+- Queue-Reihenfolge ist per Drag-and-Drop änderbar.
+- `Warten` blockiert nachfolgende Queue-Starts bis kein aktiver Prozess mehr läuft.
+- `Skript` und `Skriptkette` werden als Queue-Einträge mitgeführt.
+
+Parallelität kommt aus `Settings`:
+
+- `Max. parallele Film/Video Encodes`
+- `Max. parallele Audio CD Jobs`
+- `Max. Encodes gesamt`
+- optional `Audio CDs: Queue-Reihenfolge überspringen`

 ## 3) Skript- / Cron-Status

-Zeigt:
+Zeigt Runtime-Aktivitäten:

- aktive Ausführungen (Skripte, Ketten, Cron)
- zuletzt abgeschlossene Ausführungen
+- laufende Skripte
+- laufende Ketten
+- Cron-Ausführungen
+- letzte abgeschlossene Aktivitäten

-Mögliche Aktionen:
+Aktionen:

- laufende Ketten: `Nächster Schritt`
- laufende Einträge: `Abbrechen`
- Historie der Aktivitäten: `Liste leeren`
+- `Nächster Schritt` bei Ketten
+- `Abbrechen`
+- `Liste leeren`

 ## 4) Job Übersicht

-Kompakte Jobliste mit Status, Fortschritt, ETA. Klick auf einen Job klappt die Detailsteuerung auf.
+Die Jobliste ist der zentrale Arbeitsbereich. Ein Klick öffnet den jeweiligen `Pipeline-Status`.

-Zusätzliche Kennzeichnungen in der Liste:
+### Badges und Kontext

- `Serien-Container`/`Serien-Disk` für Staffel-Workflows
- `Multipart Movie` bei zusammengeführten Film-Discs
- Untertitel mit Disc-/Container-Infos (z. B. `Disc 2 | Container #123`)
+Neben Status/Fortschritt zeigt die Liste je nach Job:

-Im aufgeklappten Zustand erscheint die Karte `Pipeline-Status` mit allen zustandsabhängigen Aktionen.
+- Serienkontext (`Serien-Container`, Staffel/Disk)
+- Multipart-Kontext (`Multipart Movie`, Disc-Nr.)
+- Queue-/Subjob-Kontext bei Serien-Episoden

-### Zustandsabhängige Hauptaktionen
+### Zustandsabhängige Aktionen

-| Zustand | Typische Aktion |
-|---|---|
-| `Medium erkannt` / `Bereit` | `Analyse starten` |
-| `Metadatenauswahl` | `Metadaten öffnen` |
-| `Warte auf Auswahl` | Playlist wählen und `Playlist übernehmen` |
-| `Startbereit` | `Job starten` |
-| `Bereit zum Encodieren` | Tracks/Skripte prüfen, dann `Encoding starten` |
-| laufend (`Analyse`/`Rippen`/`Encodieren`) | `Abbrechen` |
-| `Fehler` / `Abgebrochen` | `Retry Rippen`, `Disk-Analyse neu starten` |
+| Zustand | Hauptaktion im Ripper | Ergebnis |
+|---|---|---|
+| `Medium erkannt`, `Bereit` | `Analyse starten` | startet MakeMKV-Analyse |
+| `Metadatenauswahl` | `Metadaten öffnen` | Film/Serie auswählen, Provider festlegen |
+| `Warte auf Auswahl` | Playlist/Titel/RAW-Entscheidung bestätigen | setzt Flow fort zur Prüfung |
+| `Startbereit` | `Job starten` | startet Rip oder RAW-basierte Prüfung |
+| `Bereit zum Encodieren` | `Encoding starten` | startet HandBrake mit bestätigter Auswahl |
+| Laufend (`Analyse`, `Rippen`, `Encodieren`) | `Abbrechen` | setzt Job auf `Abgebrochen` |
+| `Fehler`, `Abgebrochen` | `Retry Rippen` | neuer Rip-Anlauf |

-Zusätzlich je nach Job:
+Zusatzaktionen je nach Zustand und Jobtyp:

 - `Review neu starten`
 - `Encode neu starten`
+- `RAW neu encodieren`
 - `Aus Queue löschen`

-### Titel-/Spurprüfung (`Bereit zum Encodieren`)
+### Review-Bereich (`Bereit zum Encodieren`)

-Im selben Block siehst du:
+Hier wird die effektive Encode-Entscheidung festgelegt:

- Auswahl des Encode-Titels
- Audio-/Subtitle-Trackauswahl
- User-Preset-Auswahl
+- Titelwahl
+- Audio-/Subtitle-Trackselektion
+- User-Preset
 - Pre-/Post-Encode-Skripte und Ketten
- Preview des finalen HandBrakeCLI-Befehls
+- HandBrake-Kommandovorschau
+
+Ohne Bestätigung dieses Blocks startet kein produktiver Encode.
+
+### RAW-Ordnerphasen (sichtbar über Logs/Details)
+
+Der Ripper arbeitet mit drei RAW-Zuständen:
+
+- `Incomplete_...` während unvollständigem Rip
+- `Rip_Complete_...` nach erfolgreich abgeschlossenem Rip, vor Encode
+- ohne Prefix nach erfolgreichem Encode
+
+Das ist wichtig für Recovery und Delete-Vorschau.

 ## 5) Disk-Information

-Zeigt aktuelles Laufwerk und Disc-Metadaten (`Pfad`, `Modell`, `Disc-Label`, `Mount`).
+Zeigt aktuelle Laufwerksdaten:
+
+- Device-Pfad
+- Modell
+- Disc-Label / Mount

 Aktionen:

 - `Laufwerk neu lesen`
 - `Disk neu analysieren`
- `Metadaten-Modal öffnen`
+- Metadaten-Dialog öffnen

 Hinweis:

- `Laufwerk neu lesen` ist nicht mehr an einen festen Pipeline-State gebunden und kann genutzt werden, solange kein Rescan-Request läuft.
+- `Laufwerk neu lesen` ist nicht mehr an einen festen Pipeline-State gebunden.

---
-
-## Wichtige Dialoge im Ripper
+## Wichtige Dialoge

 ### Metadaten auswählen

- OMDb-Suche + Ergebnisliste
- manuelle Eingabe als Fallback
- `Auswahl übernehmen` startet den nächsten Pipeline-Schritt
+Im Dialog werden Film-/Serienmetadaten bestätigt.

-Bei Film-Duplikaten in der Historie öffnet sich ein Konfliktdialog:
+Sonderfälle:

- `Übernahme erzwingen`: legt trotzdem einen neuen Job mit denselben Metadaten an
- `Multipart movie`: verknüpft bestehenden und neuen Job in einem Multipart-Container (mit separaten Disc-Nummern)
- `Zurück zur Auswahl`: zurück in die Metadatenliste
+- Film-Duplikat: `Übernahme erzwingen` oder `Multipart movie`
+- Serie: `Disc-Nummer` ist Pflicht

-### Abbruch-Bereinigung
+### Vorhandenes RAW erkannt

-Nach Abbruch kann Ripster optional fragen, ob erzeugte RAW- oder Movie-Dateien gelöscht werden sollen.
+Wenn passendes RAW existiert, fordert der Dialog eine explizite Entscheidung:
+
+- vorhandenes RAW verwenden
+- RAW verwerfen/löschen und neu rippen

 ### Queue-Eintrag einfügen

-Erstellt gezielt einen Skript-, Ketten- oder Warte-Eintrag an einer bestimmten Queue-Position.
+Du kannst gezielt ab Position einfügen:
+
+- Skript
+- Skriptkette
+- Wartezeit
@@ -1,92 +1,107 @@
 # Settings

-Die Seite `Settings` steuert Konfiguration und Automatisierung.
+Die Seite `Settings` steuert alle Betriebsparameter von Ripster: Pfade, Tools, Queue-Limits, Metadatenquellen, Automatisierung.

-## Tabs im Überblick
+## Tab-Überblick

-| Tab | Zweck |
+| Tab | Hauptzweck |
 |---|---|
-| `Konfiguration` | alle Kernsettings (Pfade, Tools, Monitoring, Metadaten, Queue, Benachrichtigungen) |
-| `Scripte` | einzelne Bash-Skripte verwalten und testen |
-| `Skriptketten` | Sequenzen aus Skript- und Warte-Schritten bauen |
-| `Encode-Presets` | benutzerdefinierte Presets für das Review im Ripper |
-| `Cronjobs` | zeitgesteuerte Skript-/Kettenausführung |
-
---
+| `Konfiguration` | globale und profilspezifische Laufzeitsettings |
+| `Scripte` | einzelne Skripte verwalten und testen |
+| `Skriptketten` | mehrstufige Abläufe aus Skript/Warten |
+| `Encode-Presets` | wiederverwendbare HandBrake-Profile für Review |
+| `Cronjobs` | zeitgesteuerte Ausführung von Skript/Kette |

 ## Tab `Konfiguration`

-Wichtiges Bedienmuster:
+### Bedienprinzip

-1. Werte ändern
-2. `Änderungen speichern`
-3. bei Bedarf `Änderungen verwerfen` oder `Neu laden`
+1. Werte ändern.
+2. `Änderungen speichern`.
+3. erst danach sind Werte für neue Aktionen wirksam.

-Zusätzlich:
+Zusätzliche Bedienhilfen:

- `PushOver Test` sendet eine Testnachricht
- Änderungen werden erst nach Speichern wirksam
- Tool-Preset-Felder bieten HandBrake-Presetauswahl direkt im Formular
+- `Neu laden` verwirft lokale Formzustände
+- `Änderungen verwerfen` setzt auf zuletzt gespeicherten Stand
+- `PushOver Test` validiert Benachrichtigungszugang sofort
+
+### Was wirkt unmittelbar, was erst bei neuem Job?
+
+- Queue-/Parallelität wirkt auf neue Queue-Entscheidungen und Pump-Läufe.
+- Tool-/Pfad-/Template-Änderungen wirken vollständig auf neu gestartete Schritte.
+- Bereits laufende Prozesse übernehmen Änderungen in der Regel nicht rückwirkend.
+
+### Welche Bereiche im Alltag kritisch sind
+
+| Bereich | Kritisch für |
+|---|---|
+| `Pfade` | wo RAW, finale Ausgaben, Converter/Audiobook-Dateien landen |
+| `Tools` | ob Analyze/Rip/Encode ausführbar sind |
+| `Metadaten` | Film-/Serienzuordnung und Episode-Mapping |
+| `Queue-Limits` | Durchsatz und Reihenfolgeverhalten |
+| `Monitoring` | Sichtbarkeit von Last und Speicherengpässen |
+| `Benachrichtigungen` | PushOver-Ereignisse je Pipelinephase |

 ## Tab `Scripte`

 Funktionen:

- Skript anlegen, bearbeiten, löschen
- Skript testen (`Test`)
- Reihenfolge per Drag-and-Drop
+- anlegen, bearbeiten, löschen
+- testen (`Test`)
+- sortieren

-Praxis:
+Testausführung liefert:

- Reihenfolge ist wichtig, weil ausgewählte Skripte später sequentiell abgearbeitet werden.
- Testresultate zeigen Exit-Code, Dauer und stdout/stderr.
+- Exit-Code
+- Dauer
+- stdout/stderr
+
+Wichtig:
+
+- Nur erfolgreiche Skripte sollten in produktive Pre-/Post-Listen übernommen werden.

 ## Tab `Skriptketten`

-Funktionen:
+Ketten bestehen aus Schritten:

- Kette anlegen/bearbeiten/löschen
- Kette testen
- Reihenfolge der Ketten per Drag-and-Drop
+- `Skript`
+- `Warten`

-Im Ketten-Editor:
+Typischer Einsatz:

- Bausteine links (`Warten`, vorhandene Skripte)
- Schritte rechts per Klick oder Drag-and-Drop hinzufügen
- Schrittreihenfolge im Canvas ändern
+- externe Hooks vor/nach Encode
+- gestaffelte Abläufe mit Pausen
+
+In der Queue erscheinen Ketten als eigene Einträge und werden dort ausgeführt.

 ## Tab `Encode-Presets`

 Ein Preset bündelt:

- optional HandBrake-Preset (`-Z`)
+- optionales HandBrake-Preset (`-Z`)
 - optionale Extra-Args
- Medientyp (`Universell`, `Blu-ray`, `DVD`, `Sonstiges`)
+- Medienziel (Universell/Blu-ray/DVD/Sonstiges)

-Verwendung:
-
- Diese Presets erscheinen später im Ripper im Review (`Bereit zum Encodieren`).
+Im Ripper-Review kannst du Presets pro Job auswählen, statt Parameter jedes Mal neu zu setzen.

 ## Tab `Cronjobs`

 Funktionen:

 - Cronjob anlegen und bearbeiten
- Quelle wählen: Skript oder Skriptkette
- Cron-Ausdruck validieren
+- Quelle wählen (`Skript` oder `Skriptkette`)
+- Cron-Ausdruck prüfen
 - `Jetzt ausführen`
- Logs je Cronjob anzeigen
- `Aktiviert` und `Pushover` toggeln
+- Job-Logs ansehen
+- Aktivierung/Pushover toggeln

-Hilfen:
+Empfehlung:

- Beispiele für Cron-Ausdrücke direkt im Dialog
- Link zu `crontab.guru` im Editor
+1. Skript/Kette manuell testen.
+2. Dann Cron aktivieren.
+3. Erste automatische Läufe aktiv im Runtime-Status kontrollieren.

---
+## Verbindung zur Einstellungsreferenz

-## Empfehlung für stabile Nutzung
-
-1. Erst `Konfiguration` sauber setzen
-2. dann Skripte/Ketten testen
-3. danach Cronjobs aktivieren
+Die vollständige Wirkung jeder einzelnen Einstellung steht in [Einstellungsreferenz](../configuration/settings-reference.md).