1.0.0-rc1 Docs

2026-05-08 09:01:17 +02:00
parent 9b437fe5e5
commit 9b38d78042
61 changed files with 452 additions and 419 deletions
@@ -1,68 +1,82 @@
 # Audiobooks

-Die Seite `Audiobooks` ist der spezialisierte AAX-Workflow.
+Die Seite `Audiobooks` ist der spezialisierte Workflow für Audible-`*.aax`-Dateien.

-## Ablaufübersicht
+## Seitenstruktur

-Die Oberfläche ist in drei Bereiche gegliedert:
+Die Oberfläche besteht aus zwei Hauptbereichen:

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

 ## 1) Audiobooks Upload

-Der Upload verarbeitet ausschließlich AAX-Dateien.
+Der Upload akzeptiert ausschließlich `.aax`.

-Direkt nach Upload passieren im Hintergrund:
+### Bedienung

- Probe/Metadatenanalyse (ffprobe)
- Anlage eines RAW-Ordners per `Audiobook RAW Template`
- Ablage der AAX-Datei im RAW-Pfad
- Initiale Jobkonfiguration (Format, Kapitel, Metadaten)
+- Datei auswählen (Button oder Drag-and-Drop)
+- Upload starten
+- Auswahl entfernen oder laufenden Upload abbrechen

-Wichtige Parameter:
+Während des Uploads zeigt die UI:

- Zielformat (`m4b`, `mp3`, `flac`)
- optionaler Sofortstart
+- Prozentfortschritt
+- übertragene/gesamte Bytes
+- Statusmeldung (z. B. „Job vorbereitet“, „in Queue eingereiht“)

-Toolabhängigkeit:
+### Ablauf nach erfolgreichem Upload

- `ffprobe_command` für Metadaten/Kapitel
- `ffmpeg_command` für Encode/Cover-Extraktion
+- AAX wird serverseitig geprüft
+- Audiobook-Job wird angelegt
+- Job landet je nach Pipelinezustand in `READY_TO_START`, startet direkt oder wird eingereiht

 ## 2) Audiobook Jobs

-Jobkarten zeigen Zustand, Fortschritt und verfügbare Aktionen.
+Gezeigt werden aktive Jobs (nicht abgeschlossene). Fertige Jobs liegen in der `Historie`.

-Typische Aktionen:
+Jeder Job kann eingeklappt/ausgeklappt werden und zeigt:

- `Starten`
+- Titel-/Metadatenblock (Titel, Autor, Sprecher, Jahr, Kapitel)
+- Statusbadge
+- Fortschritt/ETA
+- ggf. Kapitel-Fortschritt
+
+### Konfigurierbare Job-Parameter
+
+Im ausgeklappten Job:
+
+- Ausgabeformat (`m4b`, `mp3`, `flac`)
+- formatspezifische Optionen (dynamisch je Format)
+- Kapitelnamen bearbeiten
+- Pre-Rip-Ausführungen (Skript/Kette)
+- Post-Rip-Ausführungen (Skript/Kette)
+
+### Formatverhalten
+
+- `m4b`: eine Datei mit Kapiteln
+- `mp3`/`flac`: kapitelweise Ausgabedateien
+
+Für `mp3`/`flac` zeigt die UI während/nach dem Lauf eine Kapitel-Status-Tabelle (`Rip`/`Encode`).
+
+### Aktionen je Job
+
+- `Encode starten` (bzw. Neustart mit aktuellen Optionen)
 - `Abbrechen`
- `Retry`
- `Löschen`
- `Im Ripper` (Kontextwechsel)
+- `Job löschen` (mit Bestätigung)

-Die Karten werden regelmäßig aktualisiert und durch WebSocket-Ereignisse ergänzt.
+## Relevante Settings

-## 3) Audiobook Output Explorer
+- `raw_dir_audiobook`
+- `movie_dir_audiobook`
+- `audiobook_raw_template`
+- `output_template_audiobook`
+- `output_chapter_template_audiobook`
+- `ffprobe_command`
+- `ffmpeg_command`

-Read-only Explorer des Audiobook-Outputpfads:
+## Typische Fehlerbilder

- Ordner-/Dateistruktur
- Zeitstempel/Größen
- schnelle Ergebnisprüfung ohne Dateisystemwechsel
-
-## Pfad- und Template-Logik
-
-| Bereich | Gesteuert durch |
-|---|---|
-| RAW-Ablage | `raw_dir_audiobook` + `audiobook_raw_template` |
-| Finale Ausgabe | `movie_dir_audiobook` + `output_template_audiobook` |
-| Dateiformat | Jobkonfiguration (`m4b`, `mp3`, `flac`) |
-
-## 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.
+- Upload wird abgelehnt: Datei ist keine gültige `*.aax`.
+- Start/Encode schlägt fehl: `ffprobe` oder `ffmpeg` nicht erreichbar.
+- Unerwartete Ausgabeorte: Templates/Pfade passen nicht zur gewünschten Struktur.
@@ -7,7 +7,7 @@ Dieses Kapitel ist das Bedienhandbuch für die Oberflächen im Alltag.
 | Seite | Rolle im Betrieb | Typischer Einsatz |
 |---|---|---|
 | [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 |
+| [Audiobooks](audiobooks.md) | AAX-Spezialflow | Upload, Jobkonfiguration 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 |
@@ -29,4 +29,5 @@ Direkt in der Top-Navigation:

 Nur per URL:

- `Database` unter `/database`
+- `Database` unter `/database` (nur Expertenmodus in der Navigation sichtbar)
+- `TMDb Migration` unter `/tmdb-migration` (Direktlink, nicht in der Navigation)
@@ -166,3 +166,12 @@ Du kannst gezielt ab Position einfügen:
 - Skript
 - Skriptkette
 - Wartezeit
+
+### Audible Activation Bytes eintragen
+
+Wenn für eine AAX-Datei keine Activation Bytes automatisch ermittelt werden können,
+öffnet Ripster einen Dialog zur manuellen Eingabe.
+
+- Eingabeformat: genau 8 Hex-Zeichen (z.B. `1a2b3c4d`)
+- Speicherung: lokal im Activation-Bytes-Cache
+- Wirkung: nach dem Speichern kann der Audiobook-Flow fortgesetzt werden
@@ -1,107 +1,167 @@
 # Settings

-Die Seite `Settings` steuert alle Betriebsparameter von Ripster: Pfade, Tools, Queue-Limits, Metadatenquellen, Automatisierung.
+Die Seite `Settings` ist das zentrale Kontrollpanel für Laufzeitverhalten, Automatisierung und Expertenfunktionen.

 ## Tab-Überblick

-| Tab | Hauptzweck |
+| Tab | Zweck |
 |---|---|
-| `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 |
+| `Konfiguration` | Alle fachlichen Settings (Pfade, Tools, Laufwerk, Metadaten, Monitoring, Benachrichtigungen, Converter) |
+| `Scripte` | Einzelne Bash-Skripte pflegen, testen und sortieren |
+| `Skriptketten` | Mehrstufige Sequenzen aus `Skript` und `Warten` bauen und testen |
+| `Encode-Presets` | Benutzer-Presets und Standard-Zuordnungen für Blu-ray/DVD-Workflows |
+| `Cronjobs` | Zeitgesteuerte Jobs auf Basis Skript/Skriptkette |

 ## Tab `Konfiguration`

-### Bedienprinzip
+### Bedienlogik

-1. Werte ändern.
-2. `Änderungen speichern`.
-3. erst danach sind Werte für neue Aktionen wirksam.
+1. Felder ändern.
+2. `Änderungen speichern` klicken.
+3. Erst dann werden Änderungen persistiert und für neue Pipeline-Schritte wirksam.

-Zusätzliche Bedienhilfen:
+Aktionen in der Toolbar:

- `Neu laden` verwirft lokale Formzustände
- `Änderungen verwerfen` setzt auf zuletzt gespeicherten Stand
- `PushOver Test` validiert Benachrichtigungszugang sofort
+- `Änderungen speichern`: schreibt nur geänderte Felder als Bulk-Update.
+- `Änderungen verwerfen`: setzt den Formularzustand auf zuletzt geladen/zum Server gespeicherten Stand zurück.
+- `Neu laden`: lädt Kategorien + Werte erneut vom Backend.
+- `PushOver Test`: sendet eine Testnachricht mit aktuellen PushOver-Werten.
+- `Coverarts prüfen`: startet die manuelle Coverart-Recovery.
+- `Expertenmodus`: wird sofort gespeichert (nicht Teil des normalen Bulk-Speicherns).

-### Was wirkt unmittelbar, was erst bei neuem Job?
+### Wichtige UI-Verhalten

- 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.
+- Jede Einstellung zeigt `Gespeichert` oder `Ungespeichert` direkt am Feld.
+- Pflichtfelder sind mit `*` markiert.
+- Bei Validierungsfehlern wird pro Feld ein Fehlertext angezeigt und Speichern blockiert.
+- Tool-Kommandos (`makemkv_command`, `mediainfo_command`, `handbrake_command`, `ffmpeg_command`, `ffprobe_command`, `cdparanoia_command`, `mkvmerge_command`) sind im Formular schreibgeschützt markiert.
+- Einige Felder sind abhängig vom Expertenmodus sichtbar.

-### Welche Bereiche im Alltag kritisch sind
+### Kategorie `Pfade`: Besondere Interaktion

-| 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 |
+Die Pfad-Kategorie hat eine eigene Darstellung:
+
+- Tabelle `Effektive Pfade`: zeigt die aktuell tatsächlich aufgelösten Laufzeitpfade inkl. Fallbacks.
+- Accordion je Bereich (`Blu-ray`, `DVD`, `CD / Audio`, `Audiobook`, `Converter`, `Downloads`, optional `Externe Speicher`, `Logs`).
+- Für Pfadfelder mit Owner-Pendant (`*_owner`) erscheint direkt darunter das Feld `Eigentümer (user:gruppe)`.
+- Owner-Felder sind deaktiviert, solange der zugehörige Pfad leer ist.
+
+### Spezial-Editoren in der Konfiguration
+
+- `drive_devices`: JSON-Array wird über UI-Editor gepflegt (Pfad + MakeMKV-Index je Laufwerk).
+- `external_storage_paths`: Liste aus `Name` + `Pfad` (für Anzeige freier externer Speicher).
+- `converter_scan_extensions`: Checkbox-Raster der erlaubten Endungen; mindestens eine Endung muss aktiv bleiben.
+- `makemkv_registration_key`: zusätzlicher Betakey-Hinweis mit `übernehmen`-Button.
+
+### Laufwerks-Infobox innerhalb `Laufwerk`
+
+In der Kategorie `Laufwerk` wird eine Live-Tabelle erkannter optischer Laufwerke angezeigt:
+
+- `Neu einlesen` lädt Laufwerksinfos neu.
+- Im Expertenmodus: `Freigeben` pro Laufwerk und `Alle Laufwerke freigeben`.

 ## Tab `Scripte`

 Funktionen:

- anlegen, bearbeiten, löschen
- testen (`Test`)
- sortieren
+- Skript anlegen (Inline-Editor)
+- Skript bearbeiten (Dialog)
+- Skript löschen (mit Bestätigung)
+- Skript testen
+- Reihenfolge per Drag-and-Drop ändern

-Testausführung liefert:
+Testergebnis enthält:

+- Erfolg/Fehler
 - Exit-Code
+- Timeout-Info
 - Dauer
 - stdout/stderr

-Wichtig:
-
- Nur erfolgreiche Skripte sollten in produktive Pre-/Post-Listen übernommen werden.
-
 ## Tab `Skriptketten`

-Ketten bestehen aus Schritten:
+Skriptketten bestehen aus Schritten:

 - `Skript`
- `Warten`
+- `Warten (Sekunden)`

-Typischer Einsatz:
+Funktionen:

- externe Hooks vor/nach Encode
- gestaffelte Abläufe mit Pausen
+- Ketten anlegen/bearbeiten/löschen
+- Reihenfolge der Ketten per Drag-and-Drop
+- Kette testen
+- Schritte in der Kette per Drag-and-Drop neu anordnen

-In der Queue erscheinen Ketten als eigene Einträge und werden dort ausgeführt.
+Im Ketteneditor:
+
+- linke Palette (`Systemblöcke`, `Scripte`)
+- rechte Canvas mit Drop-Zonen
+- pro Warte-Schritt konfigurierbare Sekunden

 ## Tab `Encode-Presets`

-Ein Preset bündelt:
+Bereiche:

- optionales HandBrake-Preset (`-Z`)
- optionale Extra-Args
- Medienziel (Universell/Blu-ray/DVD/Sonstiges)
+1. `Standard-Zuordnungen` (Slots)
+2. `Preset-Liste` (CRUD)

-Im Ripper-Review kannst du Presets pro Job auswählen, statt Parameter jedes Mal neu zu setzen.
+### Standard-Zuordnungen
+
+Es gibt vier persistente Slots:
+
+- `bluray_movie`
+- `bluray_series`
+- `dvd_movie`
+- `dvd_series`
+
+Die Auswahl ist medientyp-kompatibel gefiltert. Nicht kompatible oder fehlende bereits gespeicherte IDs werden weiterhin sichtbar gemacht, damit bestehende Zuordnungen nachvollziehbar bleiben.
+
+### Preset-Inhalt
+
+Ein Preset umfasst:
+
+- Name
+- Medientyp (`all`, `bluray`, `dvd`)
+- HandBrake-Preset (`-Z`)
+- Extra Args
+- optionale Beschreibung

 ## Tab `Cronjobs`

 Funktionen:

- Cronjob anlegen und bearbeiten
- Quelle wählen (`Skript` oder `Skriptkette`)
- Cron-Ausdruck prüfen
+- Cronjob erstellen/bearbeiten/löschen
+- Debounced Validierung des Cron-Ausdrucks
+- Quelle wählen: `Skript` oder `Skriptkette`
+- Aktiv- und PushOver-Toggle je Job
 - `Jetzt ausführen`
- Job-Logs ansehen
- Aktivierung/Pushover toggeln
+- Lauf-Logs öffnen

-Empfehlung:
+Die Seite zeigt zusätzlich Live-Status laufender Cron-Aktivitäten (Runtime Activities).

-1. Skript/Kette manuell testen.
-2. Dann Cron aktivieren.
-3. Erste automatische Läufe aktiv im Runtime-Status kontrollieren.
+## Expertenbereich: Activation Bytes Cache

-## Verbindung zur Einstellungsreferenz
+Der Activation-Bytes-Block wird nur im Expertenmodus angezeigt und nur wenn Einträge vorhanden sind.

-Die vollständige Wirkung jeder einzelnen Einstellung steht in [Einstellungsreferenz](../configuration/settings-reference.md).
+Er zeigt:
+
+- AAX-Checksum
+- Activation Bytes
+- Speicherzeitpunkt
+
+## Validierungshinweise für Template-Felder
+
+Template-Felder akzeptieren nur:
+
+- Buchstaben/Ziffern
+- Leerzeichen
+- `_` und `-`
+- Platzhalter in `{...}` bzw. `${...}`
+- `/` für Ordnertrennung
+
+Nicht erlaubt sind z. B. unvollständige geschweifte Klammern oder sonstige Sonderzeichen.
+
+## Siehe auch
+
+- [Einstellungsreferenz](../configuration/settings-reference.md)
+- [Ripper](ripper.md)