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

Upload

Browse Source
This commit is contained in:
mboehmlaender
2026-03-04 14:48:56 +00:00
parent 31d3e36597
commit 3b293bb743
11 changed files with 1116 additions and 310 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,144 +1,330 @@
# Schnellstart
# Schnellstart – Vollständiger Workflow
Nach der [Installation](installation.md) und [Konfiguration](configuration.md) kannst du sofort mit dem ersten Rip beginnen.
Nach der [Installation](installation.md) und [Konfiguration](configuration.md) führt diese Seite Schritt für Schritt durch den ersten Rip – mit allen Details aus dem Code.
---
## 1. Ripster starten
## Übersicht: Pipeline-Zustände
```mermaid
stateDiagram-v2
direction LR
[*] --> IDLE
IDLE --> DISC_DETECTED: Disc eingelegt
DISC_DETECTED --> METADATA_SELECTION: Analyse gestartet
METADATA_SELECTION --> READY_TO_START: Metadaten bestätigt\n(keine Obfuskierung)
METADATA_SELECTION --> WAITING_FOR_USER_DECISION: Obfuskierung erkannt\n→ Playlist wählen
WAITING_FOR_USER_DECISION --> READY_TO_START: Playlist bestätigt
READY_TO_START --> MEDIAINFO_CHECK: Vorhandene Raw-Datei\ngefunden
READY_TO_START --> RIPPING: Ripping starten
RIPPING --> MEDIAINFO_CHECK: MakeMKV fertig
MEDIAINFO_CHECK --> READY_TO_ENCODE: Track-Review bereit
READY_TO_ENCODE --> ENCODING: Encode bestätigt
ENCODING --> FINISHED: Erfolg
ENCODING --> ERROR: Fehler
RIPPING --> ERROR: Fehler
```
---
## Schritt 1 – Ripster starten
```bash
cd ripster
./start.sh
```
Öffne [http://localhost:5173](http://localhost:5173) im Browser.
Öffne [http://localhost:5173](http://localhost:5173) im Browser. Das Dashboard zeigt `IDLE`.
---
## 2. Dashboard
## Schritt 2 – Disc einlegen → `DISC_DETECTED`
Das Dashboard zeigt den aktuellen Pipeline-Status:
Lege eine DVD oder Blu-ray ein. Der `diskDetectionService` pollt das Laufwerk alle `disc_poll_interval_ms` Millisekunden (Standard: 5 Sekunden).
```
Status: IDLE – Bereit
Warte auf Disc...
```
**Was passiert im Code:**
---
- `diskDetectionService` emittiert `disc:inserted` mit Geräteinformationen
- `pipelineService.onDiscInserted()` wird aufgerufen
- Dashboard zeigt Badge **"Neue Disc erkannt"**
- Der **"Analyse starten"**-Button wird aktiv
## 3. Disc einlegen
Lege eine DVD oder Blu-ray in das Laufwerk ein. Ripster erkennt die Disc automatisch (Polling-Intervall konfigurierbar, Standard: 5 Sekunden) und wechselt in den Status **ANALYZING**.
!!! tip "Manuelle Analyse"
Falls die Disc nicht automatisch erkannt wird, kann über die API eine manuelle Analyse ausgelöst werden:
!!! tip "Manuelle Auslösung"
Falls die automatische Erkennung nicht greift:
```bash
curl -X POST http://localhost:3001/api/pipeline/analyze
```
---
## 4. Analyse abwarten
## Schritt 3 – Analyse starten → `METADATA_SELECTION`
MakeMKV analysiert die Disc-Struktur. Dieser Vorgang dauert je nach Disc **30 Sekunden bis 5 Minuten**.
Klicke auf **"Analyse starten"** oder warte auf automatischen Start.
Der Fortschritt wird live im Dashboard angezeigt.
**Was passiert im Code:**
1. Ein neuer Job-Datensatz wird in der Datenbank angelegt (`status: METADATA_SELECTION`)
2. Ripster versucht, den Titel automatisch aus dem Disc-Label/Modell zu ermitteln
3. Mit diesem erkannten Titel wird sofort eine **OMDb-Suche** ausgelöst
4. Der `MetadataSelectionDialog` öffnet sich im Frontend mit den vorgeladenen Suchergebnissen
**Erkannter Titel:** Der Disc-Label (z. B. `INCEPTION`) wird als Suchbegriff verwendet. Falls kein Label vorhanden, bleibt das Suchfeld leer.
---
## 5. Metadaten auswählen
## Schritt 4 – Metadaten auswählen (`MetadataSelectionDialog`)
Nach der Analyse öffnet sich der **Metadaten-Dialog**:
Der Dialog zeigt vorgeladene OMDb-Suchergebnisse. Du kannst:
1. **Titel suchen**: Gib den Filmtitel in die Suchleiste ein
2. **Ergebnis auswählen**: Wähle den passenden Film aus der OMDb-Liste
3. **Playlist wählen** *(nur Blu-ray)*: Bei Blu-rays mit mehreren Playlists zeigt Ripster eine Analyse der wahrscheinlich korrekten Playlist an
4. **Bestätigen**: Klicke auf "Bestätigen"
### 4a) OMDb-Suchergebnis wählen
!!! info "Playlist-Obfuskierung"
Einige Blu-rays enthalten absichtlich viele Fake-Playlists. Ripster analysiert diese automatisch und schlägt die wahrscheinlich korrekte Playlist vor.
```
┌─────────────────────────────────────────────────┐
│ Suche: [Inception ] 🔍 │
├─────────────────────────────────────────────────┤
│ ▶ Inception (2010) · Movie · tt1375666 │
│ Inception: ... · Series · ... │
├─────────────────────────────────────────────────┤
│ [Auswahl übernehmen] │
└─────────────────────────────────────────────────┘
```
- Suche durch Titel anpassen und Enter drücken
- Typ-Filter: `movie` / `series` umschalten möglich
- Einen Eintrag anklicken, dann **"Auswahl übernehmen"**
### 4b) Manuelle Eingabe (ohne OMDb)
Falls kein passendes Ergebnis gefunden wird:
- Titel, Jahr und IMDb-ID manuell eingeben
- OMDb-Poster wird übersprungen
**Was passiert nach Bestätigung:**
Ripster ruft `pipelineService.selectMetadata()` auf und führt sofort eine **Playlist-Analyse** durch:
- MakeMKV wird im Info-Modus gestartet
- Alle Titel und deren Segment-Reihenfolgen werden analysiert
- Das Ergebnis entscheidet über den nächsten Zustand (→ Schritt 5)
---
## 6. Ripping starten
## Schritt 5 – Playlist-Situation (zwei Wege)
Nach der Metadaten-Auswahl wechselt der Status zu **READY_TO_START**.
### 5a) Keine Obfuskierung → `READY_TO_START`
Klicke auf **"Starten"** – MakeMKV beginnt mit dem Ripping.
Der Dialog schließt sich automatisch. Die empfohlene Playlist wird still übernommen. Weiter zu **Schritt 6**.
### 5b) Obfuskierung erkannt → `WAITING_FOR_USER_DECISION`
Der **Playlist-Auswahl-Dialog** erscheint **zusätzlich** (nach dem Metadaten-Dialog):
```
┌───────────────────────────────────────────────────────────────┐
│ Playlist-Auswahl │
│ Es wurden mehrere Titel mit ähnlicher Laufzeit gefunden. │
│ Bitte wähle die korrekte Playlist: │
├───────────┬──────────┬────────┬──────────────────────────────┤
│ Playlist │ Laufzeit │ Score │ Bewertung │
├───────────┼──────────┼────────┼──────────────────────────────┤
│ ● 00800 │ 2:28:05 │ +18 │ wahrscheinlich korrekt │
│ │ │ │ (lineare Segmentfolge) │
├───────────┼──────────┼────────┼──────────────────────────────┤
│ ○ 00801 │ 2:28:12 │ −4 │ Auffällige Segmentreihenfolge │
├───────────┼──────────┼────────┼──────────────────────────────┤
│ ○ 00900 │ 2:28:05 │ −32 │ Fake-Struktur │
│ │ │ │ (alternierendes Sprungmuster) │
└───────────┴──────────┴────────┴──────────────────────────────┘
847 Playlists insgesamt · 3 relevante Kandidaten (≥ 15 min)
Empfehlung: 00800 (vorausgewählt)
[Playlist bestätigen]
```
- Die empfohlene Playlist ist **vorausgewählt** (Radio-Button)
- Score und Bewertungslabel helfen bei der Entscheidung
- Nach Bestätigung: Pipeline wechselt zu `READY_TO_START`
!!! info "Scoring-Details"
Wie die Scores berechnet werden, erklärt die [Playlist-Analyse](../pipeline/playlist-analysis.md)-Seite.
---
## Schritt 6 – Ripping starten → `RIPPING`
**Vorher prüft Ripster:** Existiert bereits eine Raw-Datei für diesen Job?
- **Ja, Raw-Datei vorhanden** → Direkt zu Schritt 7 (Track-Review), kein erneutes Ripping
- **Nein** → MakeMKV-Ripping startet
Klicke auf **"Starten"** im Dashboard.
**Was MakeMKV ausführt (MKV-Modus):**
```bash
makemkvcon mkv disc:0 all /mnt/raw/Inception-2010/ \
--minlength=900 -r
```
**Was MakeMKV ausführt (Backup-Modus):**
```bash
makemkvcon backup disc:0 /mnt/raw/Inception-2010-backup/ \
--decrypt -r
```
**Live-Fortschritt** wird aus der MakeMKV-Ausgabe geparst:
```
PRGV:2048,0,65536 → Fortschritt wird berechnet und per WebSocket gesendet
PRGT:5011,0,"Sichern..." → Aktueller Task-Name
```
**Typische Dauer:**
- DVD: 20–40 Minuten
- DVD: 20–45 Minuten
- Blu-ray: 45–120 Minuten
---
## 7. Encode-Review
## Schritt 7 – Track-Review → `READY_TO_ENCODE`
Nach dem Ripping analysiert MediaInfo die Track-Struktur. Im **Encode-Review** kannst du:
Nach dem Ripping (oder direkt bei vorhandener Raw-Datei) startet der **HandBrake-Scan**:
- **Audio-Tracks** auswählen (z. B. Deutsch + Englisch)
- **Untertitel-Tracks** auswählen
- Überflüssige Tracks deaktivieren
```bash
HandBrakeCLI --scan -i <quelle> -t 0
```
Klicke auf **"Encodierung bestätigen"**.
Dieser Scan liest alle Tracks aus ohne zu encodieren. Ripster baut daraus den Encode-Plan mit automatischer Vorauswahl:
**Status: `MEDIAINFO_CHECK`** – läuft automatisch, kein Benutzereingriff
Danach öffnet sich das **Encode-Review-Panel** (`READY_TO_ENCODE`):
```
┌─────────────────────────────────────────────────────────────────┐
│ Encode-Review │
│ Titel: Disc Title 1 · Laufzeit: 2:28:05 · 28 Kapitel │
├─────────────────────────────────────────────────────────────────┤
│ Audio-Spuren │
├──────┬─────────────────────────────┬───────────────────────────┤
│ ☑ │ Track 1: English (AC3, 5.1) │ Copy (ac3) │
│ ☑ │ Track 2: Deutsch (DTS, 5.1) │ Fallback Transcode (av_aac)│
│ ☐ │ Track 3: Français (AC3, 2.0) │ Nicht übernommen │
├──────┴─────────────────────────────┴───────────────────────────┤
│ Untertitel-Spuren │
├──────┬─────────────────────────────┬────────┬──────┬──────────┤
│ ☑ │ Track 1: Deutsch │ Einbr.☐ │Forc.☐│Default☑ │
│ ☐ │ Track 2: English │ Einbr.☐ │Forc.☐│Default☐ │
├──────┴─────────────────────────────┴────────┴──────┴──────────┤
│ [Encode bestätigen] │
└─────────────────────────────────────────────────────────────────┘
```
### Audio-Track-Aktionen verstehen
| Symbol/Text | Bedeutung |
|------------|-----------|
| `Copy (ac3)` | Track wird **verlustfrei** direkt übernommen |
| `Copy (truehd)` | TrueHD-Track wird direkt übernommen |
| `Transcode (av_aac)` | Track wird zu AAC umgewandelt |
| `Fallback Transcode (av_aac)` | Copy nicht möglich → automatisch zu AAC |
| `Preset-Default (HandBrake)` | HandBrake-Preset entscheidet |
| `Nicht übernommen` | Track ist nicht ausgewählt |
### Untertitel-Flags
| Flag | Bedeutung |
|------|-----------|
| **Einbrennen** | Untertitel werden fest ins Video gebrannt (nur ein Track möglich) |
| **Forced** | Nur erzwungene Untertitel-Einblendungen übernehmen |
| **Default** | Diese Spur wird beim Abspielen automatisch aktiviert |
### Vorauswahl-Regeln
Die Tracks mit `☑` wurden nach der Regel aus den Einstellungen automatisch vorausgewählt (`selectedByRule: true`). Die Auswahl kann frei geändert werden.
Klicke **"Encode bestätigen"** um fortzufahren.
---
## 8. Encoding
## Schritt 8 – Encoding → `ENCODING`
HandBrake encodiert die Datei mit dem konfigurierten Preset.
HandBrake startet mit dem finalisierten Plan:
**Fortschrittsanzeige:**
- Aktueller Prozentsatz
```bash
HandBrakeCLI \
-i /dev/sr0 \
-o "/mnt/movies/Inception (2010).mkv" \
-t 1 \
--preset "H.265 MKV 1080p30" \
-a 1,2 \
-E copy:ac3,av_aac \
-s 1 \
--subtitle-default 1
```
**Live-Fortschritt** wird aus HandBrake-stderr geparst:
```
Encoding: task 1 of 1, 73.50 % (45.23 fps, avg 44.12 fps, ETA 00h12m34s)
```
Das Dashboard zeigt:
- Fortschrittsbalken (0–100 %)
- Aktuelle Encoding-Geschwindigkeit (FPS)
- Geschätzte Restzeit (ETA)
- Encoding-Geschwindigkeit (FPS)
**Typische Dauer (abhängig von CPU/GPU und Preset):**
- Schnelles Preset (`fast`): 0.5× Echtzeit
- Standard-Preset: 1–3× Echtzeit
- Langsames Preset (`slow`): 5–10× Echtzeit
---
## 9. Fertig!
Status wechselt zu **FINISHED**. Die encodierte Datei liegt im konfigurierten `movie_dir`.
## Schritt 9 – Fertig! → `FINISHED`
```
/mnt/nas/movies/
└── Inception (2010).mkv ← Fertige Datei
└── Inception (2010).mkv ✓ Encodierung abgeschlossen
```
!!! success "PushOver-Benachrichtigung"
Falls PushOver konfiguriert ist, erhältst du eine Push-Benachrichtigung auf dein Mobilgerät.
- Job-Status in der Datenbank: `FINISHED`
- PushOver-Benachrichtigung (falls konfiguriert)
- Eintrag in der [History](http://localhost:5173/history) mit vollständigen Logs
---
## Workflow-Zusammenfassung
## Fehlerbehandlung
```
Disc einlegen
↓
ANALYZING (MakeMKV analysiert)
↓
METADATA_SELECTION (Titel & Playlist wählen)
↓
READY_TO_START → [Starten]
↓
RIPPING (MakeMKV rippt)
↓
MEDIAINFO_CHECK (Track-Analyse)
↓
READY_TO_ENCODE → [Bestätigen]
↓
ENCODING (HandBrake encodiert)
↓
FINISHED ✓
```
### Job im Status `ERROR`
1. **Dashboard**: Details-Button → Log-Ausgabe prüfen
2. **Retry**: Job vom Fehlerzustand neu starten (behält Metadaten)
3. **History**: Vollständige Logs und Fehlerdetails
### Häufige Fehlerursachen
| Fehler | Ursache | Lösung |
|-------|---------|--------|
| MakeMKV: Lizenzfehler | Abgelaufene Beta-Lizenz | Neue Lizenz im [MakeMKV-Forum](https://www.makemkv.com/forum/viewtopic.php?t=1053) |
| HandBrake: Preset nicht gefunden | Preset-Name falsch | `HandBrakeCLI --preset-list` prüfen |
| Keine Disc erkannt | Laufwerk-Berechtigungen | `sudo chmod a+rw /dev/sr0` |
| Falsches Video (zerstückelt) | Falsche Playlist | Job re-encodieren mit anderer Playlist |
| OMDb: Keine Ergebnisse | API-Key fehlt oder Titel nicht gefunden | Einstellungen prüfen; manuell eingeben |
---
## Was tun bei Fehlern?
## Kurzübersicht aller Schritte
Falls ein Job in den Status **ERROR** wechselt:
1. Klicke auf **"Details"** im Dashboard
2. Prüfe die Log-Ausgabe
3. Klicke auf **"Retry"** um den Job erneut zu versuchen
Logs findest du auch in der [History-Seite](http://localhost:5173/history).
| # | Status | Benutzeraktion | Was Ripster tut |
|--|--------|---------------|----------------|
| 1 | `IDLE` | Disc einlegen | Disc-Polling erkennt Disc |
| 2 | `DISC_DETECTED` | "Analyse starten" klicken | Job anlegen, OMDb vorsuchen |
| 3 | `METADATA_SELECTION` | Film im Dialog auswählen | Playlist-Analyse durchführen |
| 4a | `READY_TO_START` | — | Empfehlung automatisch übernommen |
| 4b | `WAITING_FOR_USER_DECISION` | Playlist manuell wählen | Auf Bestätigung warten |
| 5 | `READY_TO_START` | "Starten" klicken | MakeMKV-Ripping starten |
| 6 | `RIPPING` | Warten | MakeMKV rippt, Fortschritt streamen |
| 7 | `MEDIAINFO_CHECK` | Warten | HandBrake-Scan, Encode-Plan bauen |
| 8 | `READY_TO_ENCODE` | Tracks prüfen + bestätigen | Auswahl in Plan übernehmen |
| 9 | `ENCODING` | Warten | HandBrake encodiert, Fortschritt streamen |
| 10 | `FINISHED` | — | Datei fertig, Benachrichtigung senden |