1.0.0 docs

docs/gui/settings.md

@@ -1,82 +1,198 @@
 # Settings
 
-Die Seite `Settings` ist das zentrale Kontrollpanel für Laufzeitverhalten, Automatisierung und Expertenfunktionen.
+Die Seite `Settings` ist das Kontrollzentrum für Laufzeitverhalten, Standardwerte und Automatisierung. Alles, was spätere Jobs automatisch tun oder vorschlagen, wird hier vorbereitet.
 
 ## Tab-Überblick
 
 | Tab | Zweck |
 |---|---|
-| `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 |
+| `Konfiguration` | alle fachlichen Einstellungen aus der GUI |
+| `Scripte` | einzelne Bash-Skripte anlegen, testen und sortieren |
+| `Skriptketten` | mehrstufige Abläufe aus Skript- und Warte-Schritten bauen |
+| `Encode-Presets` | eigene Video-Presets und Standard-Zuordnungen pflegen |
+| `Cronjobs` | zeitgesteuerte Ausführung von Skripten oder Ketten |
 
 ## Tab `Konfiguration`
 
 ### Bedienlogik
 
-1. Felder ändern.
-2. `Änderungen speichern` klicken.
-3. Erst dann werden Änderungen persistiert und für neue Pipeline-Schritte wirksam.
+1. Felder ändern
+2. `Änderungen speichern` klicken
+3. erst dann gelten die neuen Werte für künftige Starts, Reviews oder Scheduler
 
-Aktionen in der Toolbar:
+Ausnahmen:
 
-- `Ä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).
+- `Expertenmodus` wird sofort gespeichert
+- Buttons wie `PushOver Test`, `Coverarts prüfen` oder der MakeMKV-Betakey-Import lösen direkte Aktionen aus
 
-### Wichtige UI-Verhalten
+### Toolbar-Aktionen
 
-- 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.
+- `Änderungen speichern`: schreibt nur geänderte Felder
+- `Änderungen verwerfen`: setzt den Formularzustand zurück
+- `Neu laden`: lädt Schema und Werte neu
+- `PushOver Test`: sendet eine Testnachricht mit den aktuellen PushOver-Werten
+- `Coverarts prüfen`: startet den Coverart-Recovery-Lauf sofort
+
+### Was die Kategorien im Alltag steuern
+
+#### Benachrichtigungen
+
+Hier steuerst du zwei Dinge:
+
+- ob und wohin Ripster PushOver-Nachrichten sendet
+- bei welchen Ereignissen Ripster überhaupt benachrichtigt
+
+Wichtig:
+
+- `PushOver aktiviert` ist der Master-Schalter
+- `Bei manueller Auswahl senden` ist besonders relevant für Playlist-, RAW- oder Titelentscheidungen
+- der `Expertenmodus` blendet zusätzliche technische Felder in der gesamten Settings-Seite ein
+
+#### Laufwerk
+
+Diese Kategorie beeinflusst, wie Ripster optische Laufwerke findet und überwacht.
+
+Typische Fragen:
+
+- Soll Ripster Laufwerke automatisch erkennen?
+- Soll ein bestimmtes Laufwerk fest an einen MakeMKV-Index gebunden werden?
+- Soll das Laufwerk nach erfolgreichem Rip automatisch auswerfen?
+
+Das ist vor allem wichtig bei:
+
+- mehreren Laufwerken
+- USB-SATA-Adaptern
+- Hosts mit instabilen Device-Namen
+
+#### Logging
+
+Diese Felder ändern nicht die Job-Logs auf Platte, sondern die Ausgabe im Server-Terminal.
+
+Damit steuerst du zum Beispiel:
+
+- ob `start.sh` oder ein Terminal-Run sehr gesprächig sein darf
+- ob HTTP-Requests im Terminal sichtbar sein sollen
+- ob DEBUG/INFO/WARN/ERROR dort mitlaufen
+
+#### Metadaten
+
+Hier legst du fest, wie Ripster mit TMDb, Covern und NFO-Dateien umgeht.
+
+Besonders wichtig:
+
+- ohne `TMDb Read Access Token` funktionieren Film-/Seriensuche und Neu-Zuordnung nur eingeschränkt oder gar nicht
+- `Film-Sprache` und `Fallback Sprache` bestimmen, welche Titel, Beschreibungen und Staffelinformationen bevorzugt werden
+- `Coverart-Nachladen aktiv` hilft bei nachträglich fehlenden Postern/Covern
+
+#### Monitoring
+
+Steuert das Hardware-Monitoring für:
+
+- CPU
+- RAM
+- GPU
+- Speicherstände
+
+Diese Werte erscheinen:
+
+- kompakt im `Ripper`
+- ausführlich in der Seite `Hardware`
+
+#### Pfade
+
+Hier legst du fest, wohin Ripster schreibt und wie Dateien benannt werden.
+
+Die Felder steuern:
+
+- RAW-Verzeichnisse pro Medium
+- Zielordner für Filme, Serien, CDs, Audiobooks, Converter und Downloads
+- Eigentümer per `user:gruppe`
+- Templates für Datei- und Ordnernamen
+
+Praxisbeispiele:
+
+- Serien getrennt von Filmen ablegen
+- RAW auf große HDD, Final-Output auf NAS
+- Audiobooks kapitelweise in Unterordnern strukturieren
+
+#### Converter
+
+Diese Kategorie wirkt nur auf die Seite `Converter`.
+
+Sie steuert:
+
+- welche Dateiendungen der Upload und der Verzeichnisscan akzeptieren
+- ob der Converter-RAW-Baum automatisch neu gescannt wird
+- wie häufig dieses Polling läuft
+
+#### Tools
+
+Diese Kategorie entscheidet über das technische Verhalten der eigentlichen Pipeline.
+
+Dazu gehören:
+
+- Pfade/Befehle für externe Tools
+- MakeMKV-Filter und Rip-Modi
+- HandBrake-Presets und Extra-Args
+- Vorauswahl von Audio-/Untertitelsprachen in der Review
+- Ausgabeformate
+- Queue- und Parallelitätsregeln
+- Timeout für Script-Tests
+
+Für die Nutzer-Workflows besonders relevant:
+
+- `Minimale Titellänge (Minuten)`
+- `TMDb Runtime-Abzug für Playlistfilter (%)`
+- `HandBrake Preset` und `HandBrake Extra Args`
+- `Review Audio-Sprachen (...)`
+- `Review UT-Sprachen (...)`
+- `Parallele Jobs`
+- `Max. parallele Audio CD Jobs`
+- `Max. Encodes gesamt (medienunabhängig)`
 
 ### Kategorie `Pfade`: Besondere Interaktion
 
 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.
+- Tabelle `Effektive Pfade`: zeigt die aktuell wirklich verwendeten Laufzeitpfade inklusive Fallbacks
+- Accordion pro Bereich wie `Blu-ray`, `DVD`, `CD / Audio`, `Audiobook`, `Converter`, `Downloads`, `Logs`
+- Owner-Felder (`*_owner`) erscheinen direkt beim zugehörigen Pfad
+- Owner-Felder sind deaktiviert, solange der zugehörige Pfad leer ist
 
-### Spezial-Editoren in der Konfiguration
+### Spezial-Editoren
 
-- `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.
+- `drive_devices`: Editor für mehrere Laufwerke mit Pfad und MakeMKV-Index
+- `external_storage_paths`: Liste aus Anzeigename und Pfad für die Speicheranzeige
+- `converter_scan_extensions`: Auswahl der erlaubten Upload-/Scan-Endungen
+- `makemkv_registration_key`: inkl. Betakey-Hinweis und Übernahme-Button
 
-### Laufwerks-Infobox innerhalb `Laufwerk`
+### Wichtig für Reviews und Workflows
 
-In der Kategorie `Laufwerk` wird eine Live-Tabelle erkannter optischer Laufwerke angezeigt:
+Die Seite `Settings` bestimmt direkt, was Nutzer später im Workflow sehen:
 
-- `Neu einlesen` lädt Laufwerksinfos neu.
-- Im Expertenmodus: `Freigeben` pro Laufwerk und `Alle Laufwerke freigeben`.
+- Playlist-Kandidaten werden durch `Minimale Titellänge` und `TMDb Runtime-Abzug ...` beeinflusst
+- Audio-/Untertitel-Vorauswahlen in `Bereit zum Encodieren` hängen an den Review-Sprachfeldern
+- automatisch vorgeschlagene Presets hängen an den Standard-Zuordnungen unter `Encode-Presets`
+- Queue-Verhalten im `Ripper` hängt an den drei Parallelitätsfeldern plus `Audio CDs: Queue-Reihenfolge überspringen`
 
 ## Tab `Scripte`
 
 Funktionen:
 
-- Skript anlegen (Inline-Editor)
-- Skript bearbeiten (Dialog)
-- Skript löschen (mit Bestätigung)
+- Skript anlegen
+- Skript bearbeiten
+- Skript löschen
 - Skript testen
 - Reihenfolge per Drag-and-Drop ändern
+- Favorit markieren
 
-Testergebnis enthält:
+Das Testergebnis zeigt:
 
-- Erfolg/Fehler
+- Erfolg oder Fehler
 - Exit-Code
-- Timeout-Info
 - Dauer
 - stdout/stderr
+- Timeout, falls `Script-Test Timeout (ms)` greift
 
 ## Tab `Skriptketten`
 
@@ -87,81 +203,79 @@ Skriptketten bestehen aus Schritten:
 
 Funktionen:
 
-- Ketten anlegen/bearbeiten/löschen
-- Reihenfolge der Ketten per Drag-and-Drop
-- Kette testen
-- Schritte in der Kette per Drag-and-Drop neu anordnen
+- Ketten anlegen, bearbeiten, löschen
+- Reihenfolge der Ketten ändern
+- einzelne Ketten testen
+- Schritte innerhalb der Kette per Drag-and-Drop sortieren
 
-Im Ketteneditor:
+Wichtig:
 
-- linke Palette (`Systemblöcke`, `Scripte`)
-- rechte Canvas mit Drop-Zonen
-- pro Warte-Schritt konfigurierbare Sekunden
+- dieselben Skripte können sowohl in Jobs als auch in Ketten und Cronjobs wiederverwendet werden
 
 ## Tab `Encode-Presets`
 
-Bereiche:
-
-1. `Standard-Zuordnungen` (Slots)
-2. `Preset-Liste` (CRUD)
+Hier werden Video-Standards für Disc- und Converter-Workflows verwaltet.
 
 ### Standard-Zuordnungen
 
-Es gibt vier persistente Slots:
+Es gibt vier feste Slots:
 
-- `bluray_movie`
-- `bluray_series`
-- `dvd_movie`
-- `dvd_series`
+- `Blu-ray Film`
+- `Blu-ray Serie`
+- `DVD Film`
+- `DVD Serie`
 
-Die Auswahl ist medientyp-kompatibel gefiltert. Nicht kompatible oder fehlende bereits gespeicherte IDs werden weiterhin sichtbar gemacht, damit bestehende Zuordnungen nachvollziehbar bleiben.
+Wenn für einen Workflow hier ein Default gesetzt ist, erscheint dieses User-Preset später in der Review bereits vorausgewählt.
 
 ### Preset-Inhalt
 
-Ein Preset umfasst:
+Ein User-Preset besteht aus:
 
 - Name
 - Medientyp (`all`, `bluray`, `dvd`)
-- HandBrake-Preset (`-Z`)
+- HandBrake-Preset
 - Extra Args
-- optionale Beschreibung
+- optionaler Beschreibung
 
 ## Tab `Cronjobs`
 
 Funktionen:
 
-- Cronjob erstellen/bearbeiten/löschen
-- Debounced Validierung des Cron-Ausdrucks
+- Cronjob anlegen, bearbeiten, löschen
+- Cron-Ausdruck live validieren
 - Quelle wählen: `Skript` oder `Skriptkette`
-- Aktiv- und PushOver-Toggle je Job
+- Aktiv- und PushOver-Status pro Job setzen
 - `Jetzt ausführen`
 - Lauf-Logs öffnen
 
-Die Seite zeigt zusätzlich Live-Status laufender Cron-Aktivitäten (Runtime Activities).
+Die Runtime-Aktivitäten der laufenden Cronjobs werden zusätzlich live angezeigt.
 
 ## Expertenbereich: Activation Bytes Cache
 
-Der Activation-Bytes-Block wird nur im Expertenmodus angezeigt und nur wenn Einträge vorhanden sind.
+Dieser Block wird nur im Expertenmodus angezeigt.
 
-Er zeigt:
+Er zeigt lokal bekannte AAX-Activation-Bytes mit:
 
-- AAX-Checksum
+- Prüfsumme
 - Activation Bytes
 - Speicherzeitpunkt
 
-## Validierungshinweise für Template-Felder
+Das hilft bei Audiobook-Workflows, wenn dieselbe Datei oder derselbe Hash später erneut auftaucht.
+
+## Validierung von Template-Feldern
 
 Template-Felder akzeptieren nur:
 
-- Buchstaben/Ziffern
+- Buchstaben und Ziffern
 - Leerzeichen
 - `_` und `-`
-- Platzhalter in `{...}` bzw. `${...}`
-- `/` für Ordnertrennung
+- Platzhalter in `{...}` oder `${...}`
+- `/` für Unterordner
 
-Nicht erlaubt sind z. B. unvollständige geschweifte Klammern oder sonstige Sonderzeichen.
+Damit verhindert Ripster fehlerhafte Dateinamen schon beim Speichern.
 
 ## Siehe auch
 
-- [Einstellungsreferenz](../configuration/settings-reference.md)
+- [Alle Einstellungen](../configuration/settings-reference.md)
 - [Ripper](ripper.md)
+- [Workflows aus Nutzersicht](../workflows/index.md)