michael/ripster
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DOcs

Browse Source
This commit is contained in:
mboehmlaender
2026-03-11 14:54:08 +00:00
parent 3b66ca64f8
commit aabb28ee06
66 changed files with 1199 additions and 904 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
docs/getting-started/configuration.md
View File

@@ -1,99 +1,71 @@
# Konfiguration
# Ersteinrichtung
Die Hauptkonfiguration erfolgt über die UI (`Settings`) und wird in SQLite gespeichert.
Nach der Installation erfolgt die tägliche Konfiguration fast vollständig in der GUI unter `Settings`.
---
## Ziel
## Pflichteinstellungen vor dem ersten Rip
Vor dem ersten echten Job müssen Pfade, Tools und Metadatenzugriff sauber gesetzt sein.
### 1) Pfade
## Reihenfolge (empfohlen)
| Einstellung | Beschreibung | Beispiel |
|------------|-------------|---------|
| `raw_dir` | Basisverzeichnis für RAW-Rips | `/mnt/ripster/raw` |
| `movie_dir` | Basisverzeichnis für finale Encodes | `/mnt/ripster/movies` |
| `log_dir` | Verzeichnis für Prozess-/Backend-Logs | `/mnt/ripster/logs` |
### 1. `Settings` -> Tab `Konfiguration`
Optional profilspezifisch:
Setze zuerst diese Pflichtwerte:
- `raw_dir_bluray`, `raw_dir_dvd`, `raw_dir_other`
- `movie_dir_bluray`, `movie_dir_dvd`, `movie_dir_other`
| Bereich | Wichtige Felder |
|---|---|
| Pfade | `raw_dir`, `movie_dir`, `log_dir` |
| Tools | `makemkv_command`, `handbrake_command`, `mediainfo_command` |
| Metadaten | `omdb_api_key`, optional `omdb_default_type` |
### 2) Tools
Danach `Änderungen speichern`.
| Einstellung | Standard |
|------------|---------|
| `makemkv_command` | `makemkvcon` |
| `handbrake_command` | `HandBrakeCLI` |
| `mediainfo_command` | `mediainfo` |
### 2. Medienprofile prüfen
### 3) OMDb
Wenn du Blu-ray und DVD unterschiedlich behandeln willst, pflege die profilbezogenen Felder:
| Einstellung | Beschreibung |
|------------|-------------|
| `omdb_api_key` | API-Key von omdbapi.com |
| `omdb_default_type` | `movie`, `series`, `episode` |
- `*_bluray`
- `*_dvd`
- optional `*_other`
---
Typische Beispiele:
## Encode-Konfiguration (wichtig)
- `handbrake_preset_bluray` und `handbrake_preset_dvd`
- `raw_dir_bluray` und `raw_dir_dvd`
- `filename_template_bluray` und `filename_template_dvd`
Ripster arbeitet profilspezifisch, typischerweise über:
### 3. Queue und Monitoring festlegen
- Blu-ray: `handbrake_preset_bluray`, `handbrake_extra_args_bluray`, `output_extension_bluray`, `filename_template_bluray`
- DVD: `handbrake_preset_dvd`, `handbrake_extra_args_dvd`, `output_extension_dvd`, `filename_template_dvd`
- `pipeline_max_parallel_jobs` für parallele Jobs
- `hardware_monitoring_enabled` und Intervall für Live-Metriken im Dashboard
### Template-Platzhalter
### 4. Optional: Push-Benachrichtigungen
Verfügbar in `filename_template_*` und `output_folder_template_*`:
- `${title}`
- `${year}`
- `${imdbId}`
Beispiel:
```text
${title} (${year})
-> Inception (2010).mkv
```
---
## MakeMKV-spezifisch
| Einstellung | Standard | Hinweis |
|------------|---------|--------|
| `makemkv_min_length_minutes` | `60` | Kandidaten-Filter |
| `makemkv_rip_mode_bluray` | `backup` | `mkv` oder `backup` |
| `makemkv_rip_mode_dvd` | `mkv` | `mkv` oder `backup` |
| `makemkv_registration_key` | leer | optional, wird via `makemkvcon reg` gesetzt |
---
## Monitoring & Queue
| Einstellung | Standard |
|------------|---------|
| `hardware_monitoring_enabled` | `true` |
| `hardware_monitoring_interval_ms` | `5000` |
| `pipeline_max_parallel_jobs` | `1` |
---
## PushOver (optional)
Basis:
In den Benachrichtigungsfeldern setzen:
- `pushover_enabled`
- `pushover_token`
- `pushover_user`
Zusätzlich pro Event ein/aus (z. B. `pushover_notify_job_finished`).
Dann über `PushOver Test` direkt prüfen.
---
## 2-Minuten-Funktionstest
## Verwandte Doku
1. `Dashboard` öffnen
2. Disc einlegen
3. `Analyse starten`
4. Metadaten übernehmen
5. Bis `READY_TO_ENCODE` laufen lassen
- [Einstellungsreferenz](../configuration/settings-reference.md)
- [Umgebungsvariablen](../configuration/environment.md)
Wenn diese Schritte funktionieren, ist die Grundkonfiguration korrekt.
## Wenn Werte nicht gespeichert werden
- Feld mit Fehler markieren lassen (rote Validierung im Formular)
- Pfadangaben und numerische Werte prüfen
- bei Tool-Pfaden direkt CLI-Aufruf im Terminal testen
## Weiter
- [Erster Lauf](quickstart.md)
- [GUI-Seiten im Detail](../gui/index.md)

56
docs/getting-started/index.md
View File

@@ -1,41 +1,33 @@
# Erste Schritte
# Benutzerhandbuch Überblick
Dieser Abschnitt führt dich durch die Installation und Einrichtung von Ripster.
Dieses Kapitel ist für den **Betrieb von Ripster im Alltag** geschrieben.
## Überblick
## Zielgruppe
<div class="grid cards" markdown>
- Anwender, die Discs verarbeiten wollen
- Betreiber, die den täglichen Ablauf stabil fahren möchten
- Power-User, die Queue/Skripte/Cron im UI steuern möchten
- :material-list-check: **Voraussetzungen**
## Kapitelstruktur
---
| Kapitel | Zweck |
|---|---|
| [Voraussetzungen](prerequisites.md) | Prüfen, ob System und Tools bereit sind |
| [Installation](installation.md) | Ripster aufsetzen und starten |
| [Ersteinrichtung](configuration.md) | Pfade, Tools und Metadaten korrekt setzen |
| [Erster Lauf](quickstart.md) | Ein kompletter Job von Disc bis Datei |
| [GUI-Seiten](../gui/index.md) | Alle Ansichten und Aktionen im Detail |
| [Workflows](../workflows/index.md) | Typische Abläufe und Entscheidungen aus User-Sicht |
Systemanforderungen und externe Tools, die vor der Installation benötigt werden.
## Wenn du neu startest
[:octicons-arrow-right-24: Voraussetzungen prüfen](prerequisites.md)
1. [Voraussetzungen](prerequisites.md)
2. [Installation](installation.md)
3. [Ersteinrichtung](configuration.md)
4. [Erster Lauf](quickstart.md)
- :material-download: **Installation**
## Wenn Ripster bereits läuft
---
Schritt-für-Schritt-Anleitung zur Installation von Ripster.
[:octicons-arrow-right-24: Installation starten](installation.md)
- :material-tune: **Konfiguration**
---
Einrichten von Pfaden, API-Keys und Encoding-Presets.
[:octicons-arrow-right-24: Konfigurieren](configuration.md)
- :material-rocket-launch: **Schnellstart**
---
Rippe deinen ersten Film in wenigen Minuten.
[:octicons-arrow-right-24: Loslegen](quickstart.md)
</div>
1. [GUI-Seiten](../gui/index.md)
2. [Workflows](../workflows/index.md)
3. Bei Detailfragen: [Technischer Anhang](../appendix/index.md)

131
docs/getting-started/installation.md
View File

@@ -1,103 +1,84 @@
# Installation
---
Die empfohlene Installation läuft über `install.sh` und richtet Ripster vollständig ein.
## Repository klonen
## Zielbild nach der Installation
- Ripster-Backend als `systemd`-Dienst
- Frontend über nginx erreichbar
- UI auf `http://<Server-IP>`
## Schritt-für-Schritt
### 1. Installationsskript herunterladen
```bash
git clone https://github.com/YOUR_GITHUB_USERNAME/ripster.git
cd ripster
wget -qO install.sh https://raw.githubusercontent.com/Mboehmlaender/ripster/main/install.sh
```
---
## Dev-Start (empfohlen)
### 2. Installation ausführen
```bash
./start.sh
sudo bash install.sh
```
`start.sh`:
Während der Installation wirst du nach dem HandBrake-Modus gefragt:
1. prüft Node-Version (`>= 20.19.0`)
2. installiert Dependencies (Root/Backend/Frontend)
3. startet Backend + Frontend parallel
- `1` Standard (`apt`)
- `2` GPU/NVDEC (gebündeltes Binary)
Danach:
- Backend: `http://localhost:3001`
- Frontend: `http://localhost:5173`
Stoppen: mit `Ctrl+C` im laufenden Terminal.
---
## Manuell starten
### 3. Dienststatus prüfen
```bash
npm install
npm --prefix backend install
npm --prefix frontend install
npm run dev
sudo systemctl status ripster-backend
```
Oder getrennt:
### 4. Weboberfläche öffnen
- Mit nginx: `http://<Server-IP>`
- Ohne nginx (`--no-nginx`): API auf `http://<Server-IP>:3001/api`
## Wichtige Optionen
| Option | Zweck |
|---|---|
| `--branch <branch>` | anderen Branch installieren |
| `--dir <pfad>` | Installationsverzeichnis ändern |
| `--port <port>` | Backend-Port setzen |
| `--host <hostname>` | Hostname/IP für nginx/CORS |
| `--no-makemkv` | MakeMKV nicht installieren |
| `--no-handbrake` | HandBrake nicht installieren |
| `--no-nginx` | nginx-Konfiguration überspringen |
| `--reinstall` | Update einer bestehenden Installation |
Beispiele:
```bash
npm run dev:backend
npm run dev:frontend
sudo bash install.sh --branch dev
sudo bash install.sh --port 8080 --host ripster.local
sudo bash install.sh --reinstall
```
---
## Optional: .env-Dateien anlegen
### Backend
## Betrieb im Alltag
```bash
cp backend/.env.example backend/.env
# Logs live ansehen
sudo journalctl -u ripster-backend -f
# Dienst neu starten
sudo systemctl restart ripster-backend
# Update aus bestehender Installation
sudo bash /opt/ripster/install.sh --reinstall
```
Beispiel:
## Häufige Stolperstellen
```env
PORT=3001
DB_PATH=./data/ripster.db
LOG_DIR=./logs
CORS_ORIGIN=http://localhost:5173
LOG_LEVEL=info
```
- `Permission denied` am Laufwerk: Laufwerksrechte/Gruppen prüfen
- Tools nicht gefunden: `makemkvcon`, `HandBrakeCLI`, `mediainfo` im `PATH` prüfen
- UI nicht erreichbar: nginx-Status und Port/Firewall prüfen
### Frontend
## Danach weiter
```bash
cp frontend/.env.example frontend/.env
```
Beispiel:
```env
VITE_API_BASE=/api
# optional:
# VITE_WS_URL=ws://localhost:3001/ws
```
---
## Datenbank
SQLite wird automatisch beim Backend-Start initialisiert:
```text
backend/data/ripster.db
```
Schema-Quelle: `db/schema.sql`
---
## Nächste Schritte
1. Browser öffnen: `http://localhost:5173`
2. In `Settings` Pfade/Tools/API-Keys prüfen
3. Erste Disc einlegen und Workflow starten
1. [Ersteinrichtung](configuration.md)
2. [Erster Lauf](quickstart.md)

169
docs/getting-started/prerequisites.md
View File

@@ -1,157 +1,70 @@
# Voraussetzungen
Bevor du Ripster installierst, stelle sicher, dass folgende Software auf deinem System verfügbar ist.
Diese Seite ist die praktische Checkliste vor der Installation.
---
## 1) System
## System-Anforderungen
| Punkt | Mindestwert | Empfehlung |
|---|---|---|
| Betriebssystem | Linux oder macOS | Ubuntu 22.04+ |
| Node.js | 20.19.0 | 20.x LTS |
| RAM | 4 GB | 8 GB+ |
| Freier Speicher | 50 GB | 500 GB+ |
| Anforderung | Mindestversion | Empfohlen |
|------------|----------------|-----------|
| **Betriebssystem** | Linux / macOS | Ubuntu 22.04+ |
| **Node.js** | 20.19.0 | 20.x LTS |
| **RAM** | 4 GB | 8 GB+ |
| **Festplatte** | 50 GB frei | 500 GB+ (für Roh-MKVs) |
---
## Node.js
Ripster benötigt **Node.js >= 20.19.0**.
=== "nvm (empfohlen)"
```bash
# nvm installieren
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Node.js 20 installieren
nvm install 20
nvm use 20
# Version prüfen
node --version # v20.x.x
```
=== "Ubuntu/Debian"
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version # v20.x.x
```
=== "macOS (Homebrew)"
```bash
brew install node@20
node --version # v20.x.x
```
---
## Externe Tools
### MakeMKV
!!! warning "Lizenz erforderlich"
MakeMKV ist für den persönlichen Gebrauch kostenlos (Beta-Lizenz), benötigt aber eine gültige Lizenz.
Node-Version prüfen:
```bash
# Ubuntu/Debian - PPA verwenden
sudo add-apt-repository ppa:heyarje/makemkv-beta
sudo apt-get update
sudo apt-get install makemkv-bin makemkv-oss
node --version
```
# Installierte Version prüfen
## 2) Externe Tools
Ripster benötigt folgende CLI-Tools im `PATH`:
- `makemkvcon`
- `HandBrakeCLI`
- `mediainfo`
Schnell prüfen:
```bash
makemkvcon --version
```
[:octicons-link-external-24: MakeMKV Download](https://www.makemkv.com/download/){ .md-button }
### HandBrake CLI
```bash
# Ubuntu/Debian
sudo add-apt-repository ppa:stebbins/handbrake-releases
sudo apt-get update
sudo apt-get install handbrake-cli
# Version prüfen
HandBrakeCLI --version
# macOS
brew install handbrake
```
[:octicons-link-external-24: HandBrake Download](https://handbrake.fr/downloads2.php){ .md-button }
### MediaInfo
```bash
# Ubuntu/Debian
sudo apt-get install mediainfo
# macOS
brew install mediainfo
# Version prüfen
mediainfo --Version
```
---
## 3) Optisches Laufwerk
## Disc-Laufwerk
Ripster benötigt ein physisches **DVD- oder Blu-ray-Laufwerk**.
!!! danger "LibDriveIO-Modus erforderlich"
Das Laufwerk muss im **LibDriveIO-Modus** betrieben werden – MakeMKV greift direkt auf Rohdaten des Laufwerks zu. Ohne diesen Modus können verschlüsselte Blu-rays (insbesondere UHD) nicht gelesen werden.
Nicht alle Laufwerke unterstützen den direkten Zugriff. Eine Anleitung zur Einrichtung und Liste kompatibler Laufwerke findet sich im [MakeMKV-Forum](https://www.makemkv.com/forum/viewtopic.php?t=18856).
Für Disc-Betrieb muss ein DVD/Blu-ray-Laufwerk erreichbar sein.
```bash
# Laufwerk prüfen
ls /dev/sr*
# oder
lsblk | grep rom
```
# Laufwerk-Berechtigungen setzen (erforderlich für LibDriveIO)
Wenn nötig Rechte setzen (Beispiel):
```bash
sudo chmod a+rw /dev/sr0
```
!!! info "Blu-ray unter Linux"
MakeMKV bringt mit LibDriveIO eine eigene Entschlüsselung mit – externe Bibliotheken wie `libaacs` sind in der Regel nicht erforderlich.
## 4) OMDb API-Key
---
Für automatische Metadaten (Titel, Poster, IMDb-ID):
## OMDb API-Key
1. Key unter [omdbapi.com](https://www.omdbapi.com/apikey.aspx) anlegen
2. in den `Settings` als `omdb_api_key` eintragen
Ripster verwendet die [OMDb API](https://www.omdbapi.com/) für Filmmetadaten.
## 5) Optional: PushOver
1. Registriere dich kostenlos auf [omdbapi.com](https://www.omdbapi.com/apikey.aspx)
2. Bestätige deine E-Mail-Adresse
3. Notiere deinen API-Key – du gibst ihn später in den Einstellungen ein
Für Push-Nachrichten bei Erfolg/Fehler:
---
- Account/App auf [pushover.net](https://pushover.net)
- `pushover_token` und `pushover_user` später in den `Settings` setzen
## Optionale Voraussetzungen
## Abschluss-Checkliste
### PushOver (Benachrichtigungen)
Für mobile Push-Benachrichtigungen bei Fertigstellung oder Fehlern:
- App kaufen auf [pushover.net](https://pushover.net) (~5 USD einmalig)
- **User Key** und **API Token** notieren
---
## Checkliste
- [ ] Node.js >= 20.19.0 installiert (`node --version`)
- [ ] `makemkvcon` installiert (`makemkvcon --version`)
- [ ] `HandBrakeCLI` installiert (`HandBrakeCLI --version`)
- [ ] `mediainfo` installiert (`mediainfo --Version`)
- [ ] DVD/Blu-ray Laufwerk vorhanden (`ls /dev/sr*`)
- [ ] OMDb API-Key beschafft
- [ ] Node.js 20.x verfügbar
- [ ] `makemkvcon`, `HandBrakeCLI`, `mediainfo` ausführbar
- [ ] Laufwerk erkannt
- [ ] OMDb Key bereit

130
docs/getting-started/quickstart.md
View File

@@ -1,114 +1,70 @@
# Schnellstart – Erster kompletter Job
# Erster Lauf
Diese Seite führt durch den typischen ersten Lauf.
Dieser Ablauf zeigt einen vollständigen Job aus Anwendersicht: von Disc-Erkennung bis fertiger Datei.
---
## 1. Dashboard öffnen und Disc einlegen
## 1) Starten
Erwartung:
```bash
cd ripster
./start.sh
```
- Status wechselt auf `DISC_DETECTED` bzw. `Medium erkannt`
- im Bereich `Disk-Information` sind Laufwerksdaten sichtbar
Öffne `http://localhost:5173`.
Wenn nichts passiert: `Laufwerk neu lesen`.
---
## 2. Analyse starten
## 2) Disc einlegen
Aktion im Dashboard:
Pipeline wechselt auf `DISC_DETECTED`.
- `Analyse starten`
Falls nötig manuell neu scannen:
Erwartung:
```bash
curl -X POST http://localhost:3001/api/pipeline/rescan-disc
```
- Status `ANALYZING`
- danach Metadaten-Dialog
---
## 3. Metadaten auswählen
## 3) Analyse starten
Im Dialog `Metadaten auswählen`:
Klicke im Dashboard auf `Analyse starten`.
1. OMDb-Suche nutzen oder manuell eintragen
2. passenden Treffer markieren
3. `Auswahl übernehmen`
Intern:
## 4. Auf den nächsten Zustand reagieren
- Job wird angelegt
- MakeMKV-Analyse läuft (`ANALYZING`)
- UI wechselt in Metadatenauswahl (`METADATA_SELECTION`)
- Normalfall ohne vorhandenes RAW: `RIPPING` -> `MEDIAINFO_CHECK` -> `READY_TO_ENCODE`
- bei vorhandenem RAW: direkt `MEDIAINFO_CHECK` -> `READY_TO_ENCODE`
- bei unklarer Blu-ray-Playlist: `WAITING_FOR_USER_DECISION` (Playlist auswählen und übernehmen)
---
## 5. Review in `READY_TO_ENCODE`
## 4) Metadaten bestätigen
Im aufgeklappten Job (`Pipeline-Status`):
Im Dialog:
- Encode-Titel wählen
- Audio-/Subtitle-Spuren prüfen
- optional User-Preset auswählen
- optional Pre-/Post-Skripte bzw. Ketten hinzufügen
- OMDb-Ergebnis wählen oder manuell eintragen
- bei Playlist-Abfrage ggf. `selectedPlaylist` wählen
Dann `Encoding starten`.
Nach Bestätigung startet Ripster automatisch weiter.
## 6. Encoding überwachen
---
Während `ENCODING`:
## 5) Pipeline-Pfade
- Fortschritt + ETA im Dashboard
- Live-Log im `Pipeline-Status`
- Queue- und Skript/Cron-Status parallel beobachtbar
Abhängig von Job/RAW-Situation:
## 7. Ergebnis prüfen
- **kein RAW vorhanden** -> `RIPPING`
- **RAW vorhanden** -> `MEDIAINFO_CHECK`
- **mehrdeutige Playlist** -> `WAITING_FOR_USER_DECISION`
Bei `FINISHED`:
Wenn Parallel-Limit erreicht ist, wird der Job in die Queue eingereiht.
1. Seite `Historie` öffnen
2. Job in Details öffnen
3. Output-Pfad, Status und Log prüfen
---
## Typische Folgeaktionen
## 6) Review (`READY_TO_ENCODE`)
Im Review-Panel:
- Titel auswählen (falls mehrere)
- Audio-/Subtitle-Tracks auswählen
- optional User-Preset anwenden
- optional Pre-/Post-Skripte und Ketten hinzufügen
Mit `Encoding starten` wird `confirm-encode` + Start ausgelöst.
---
## 7) Encoding (`ENCODING`)
Während Encoding:
- Live-Fortschritt/ETA über WebSocket
- Pre-Encode-Ausführungen laufen vor HandBrake
- Post-Encode-Ausführungen laufen nach HandBrake
Wichtig:
- Pre-Encode-Fehler -> Job endet in `ERROR`
- Post-Encode-Fehler -> Job kann `FINISHED` bleiben, aber mit Fehlerhinweis im Status/Log
---
## 8) Abschluss (`FINISHED`)
Ergebnis:
- Ausgabe in `movie_dir` (ggf. profilspezifisch)
- Job in Historie sichtbar
- Logs im konfigurierten `log_dir`
---
## Nützliche API-Shortcuts
```bash
# Pipeline-Snapshot
curl http://localhost:3001/api/pipeline/state
# Queue-Snapshot
curl http://localhost:3001/api/pipeline/queue
# Jobs
curl http://localhost:3001/api/history
```
- Falsches OMDb-Match: in `Historie` -> `OMDb neu zuordnen`
- Neue Encodierung aus RAW: `RAW neu encodieren`
- Prüfung komplett neu aufbauen: `Review neu starten`