Initial commit mit MkDocs-Dokumentation
This commit is contained in:
159
docs/pipeline/encoding.md
Normal file
159
docs/pipeline/encoding.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Encode-Planung
|
||||
|
||||
`encodePlan.js` analysiert die MediaInfo-Ausgabe und erstellt einen strukturierten Encode-Plan mit Track-Auswahl.
|
||||
|
||||
---
|
||||
|
||||
## Ablauf
|
||||
|
||||
```
|
||||
MediaInfo-JSON
|
||||
↓
|
||||
Track-Parsing (Video, Audio, Untertitel)
|
||||
↓
|
||||
Sprach-Normalisierung (ISO 639-1 → 639-3)
|
||||
↓
|
||||
Codec-Klassifizierung (copy-kompatibel / transcode)
|
||||
↓
|
||||
Encode-Plan generieren
|
||||
↓
|
||||
Benutzer-Review im Frontend
|
||||
↓
|
||||
HandBrake-CLI-Argumente aufbauen
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Encode-Plan-Format
|
||||
|
||||
Der generierte Plan wird als JSON im Job-Datensatz gespeichert:
|
||||
|
||||
```json
|
||||
{
|
||||
"inputFile": "/mnt/raw/Inception_t00.mkv",
|
||||
"outputFile": "/mnt/movies/Inception (2010).mkv",
|
||||
"preset": "H.265 MKV 1080p30",
|
||||
"audioTracks": [
|
||||
{
|
||||
"index": 1,
|
||||
"codec": "dts",
|
||||
"language": "deu",
|
||||
"channels": 6,
|
||||
"label": "Deutsch (DTS, 5.1)",
|
||||
"copyCompatible": false,
|
||||
"selected": true
|
||||
},
|
||||
{
|
||||
"index": 2,
|
||||
"codec": "truehd",
|
||||
"language": "eng",
|
||||
"channels": 8,
|
||||
"label": "English (TrueHD, 7.1)",
|
||||
"copyCompatible": true,
|
||||
"selected": true
|
||||
}
|
||||
],
|
||||
"subtitleTracks": [
|
||||
{
|
||||
"index": 1,
|
||||
"language": "deu",
|
||||
"label": "Deutsch",
|
||||
"selected": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sprach-Normalisierung
|
||||
|
||||
MediaInfo liefert Sprachcodes in verschiedenen Formaten. `encodePlan.js` normalisiert diese auf **ISO 639-3**:
|
||||
|
||||
| MediaInfo-Output | Normalisiert |
|
||||
|----------------|-------------|
|
||||
| `de` | `deu` |
|
||||
| `German` | `deu` |
|
||||
| `en` | `eng` |
|
||||
| `English` | `eng` |
|
||||
| `fr` | `fra` |
|
||||
| `ja` | `jpn` |
|
||||
|
||||
---
|
||||
|
||||
## Codec-Klassifizierung
|
||||
|
||||
HandBrake kann einige Codecs direkt kopieren (ohne Transcoding):
|
||||
|
||||
| Codec | Copy-kompatibel | HandBrake-Encoder |
|
||||
|-------|----------------|------------------|
|
||||
| `ac3` | ✅ Ja | `copy:ac3` |
|
||||
| `aac` | ✅ Ja | `copy:aac` |
|
||||
| `mp3` | ✅ Ja | `copy:mp3` |
|
||||
| `truehd` | ✅ Ja | `copy:truehd` |
|
||||
| `eac3` | ✅ Ja | `copy:eac3` |
|
||||
| `dts` | ❌ Nein | `ffaac` (transcode) |
|
||||
| `dtshd` | ❌ Nein | `ffaac` (transcode) |
|
||||
|
||||
!!! info "DTS-Transcoding"
|
||||
HandBrake unterstützt kein DTS-Passthrough in den Standard-Builds. DTS-Tracks werden zu AAC transcodiert, es sei denn, du verwendest einen speziellen HandBrake-Build mit DTS-Unterstützung.
|
||||
|
||||
---
|
||||
|
||||
## HandBrake-CLI-Argumente
|
||||
|
||||
Aus dem Encode-Plan generiert `commandLine.js` die HandBrake-Argumente:
|
||||
|
||||
```bash
|
||||
HandBrakeCLI \
|
||||
--input "/mnt/raw/Inception_t00.mkv" \
|
||||
--output "/mnt/movies/Inception (2010).mkv" \
|
||||
--preset "H.265 MKV 1080p30" \
|
||||
--audio 1,2 \
|
||||
--aencoder copy:truehd,ffaac \
|
||||
--subtitle 1 \
|
||||
--subtitle-default 1
|
||||
```
|
||||
|
||||
### Zusätzliche Argumente
|
||||
|
||||
Über die Einstellung `handbrake_extra_args` können beliebige HandBrake-Argumente ergänzt werden:
|
||||
|
||||
```
|
||||
--crop 0:0:0:0 --loose-anamorphic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dateiname-Template
|
||||
|
||||
Die Ausgabedatei wird über das konfigurierte Template benannt:
|
||||
|
||||
```
|
||||
Template: {title} ({year})
|
||||
Ergebnis: Inception (2010).mkv
|
||||
```
|
||||
|
||||
Verfügbare Platzhalter:
|
||||
|
||||
| Platzhalter | Wert |
|
||||
|------------|------|
|
||||
| `{title}` | Filmtitel von OMDb |
|
||||
| `{year}` | Erscheinungsjahr |
|
||||
| `{imdb_id}` | IMDb-ID (z.B. `tt1375666`) |
|
||||
| `{type}` | `movie` oder `series` |
|
||||
|
||||
Sonderzeichen im Dateinamen werden automatisch sanitisiert (`:`, `/`, `?` etc. werden entfernt oder ersetzt).
|
||||
|
||||
---
|
||||
|
||||
## Re-Encoding
|
||||
|
||||
Abgeschlossene Jobs können mit geänderten Einstellungen neu encodiert werden:
|
||||
|
||||
1. Job in der History auswählen
|
||||
2. "Re-Encode" klicken
|
||||
3. Neue Track-Auswahl treffen (oder bestehende übernehmen)
|
||||
4. Encoding startet mit aktuellen Einstellungen
|
||||
|
||||
Dies ist nützlich, wenn sich das HandBrake-Preset oder die Track-Auswahl geändert hat, ohne die zeitintensive Ripping-Phase zu wiederholen.
|
||||
31
docs/pipeline/index.md
Normal file
31
docs/pipeline/index.md
Normal file
@@ -0,0 +1,31 @@
|
||||
# Pipeline
|
||||
|
||||
Der Pipeline-Abschnitt beschreibt den Kern-Workflow von Ripster.
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :material-state-machine: **Workflow & Zustände**
|
||||
|
||||
---
|
||||
|
||||
Der vollständige Ripping-Workflow mit allen Zustandsübergängen.
|
||||
|
||||
[:octicons-arrow-right-24: Workflow](workflow.md)
|
||||
|
||||
- :material-film: **Encode-Planung**
|
||||
|
||||
---
|
||||
|
||||
Wie Ripster Audio- und Untertitel-Tracks analysiert und Encode-Pläne erstellt.
|
||||
|
||||
[:octicons-arrow-right-24: Encoding](encoding.md)
|
||||
|
||||
- :material-playlist-check: **Playlist-Analyse**
|
||||
|
||||
---
|
||||
|
||||
Erkennung von Blu-ray Playlist-Obfuskierung und Auswahl der korrekten Playlist.
|
||||
|
||||
[:octicons-arrow-right-24: Playlist-Analyse](playlist-analysis.md)
|
||||
|
||||
</div>
|
||||
119
docs/pipeline/playlist-analysis.md
Normal file
119
docs/pipeline/playlist-analysis.md
Normal file
@@ -0,0 +1,119 @@
|
||||
# Playlist-Analyse
|
||||
|
||||
Einige Blu-rays verwenden **Playlist-Obfuskierung** als Kopierschutz-Mechanismus. Ripster erkennt dieses Muster und hilft bei der Auswahl der korrekten Playlist.
|
||||
|
||||
---
|
||||
|
||||
## Das Problem: Playlist-Obfuskierung
|
||||
|
||||
Moderne Blu-rays können Hunderte von Playlists enthalten, von denen nur eine den eigentlichen Film enthält. Die anderen sind:
|
||||
|
||||
- **Kurze Dummy-Playlists** (wenige Sekunden bis Minuten)
|
||||
- **Umgeordnete Segmente** (falsche Reihenfolge der Film-Segmente)
|
||||
- **Duplizierte Inhalte** (mehrere Playlists mit gleichem Inhalt, verschiedenen Timestamps)
|
||||
|
||||
Dies macht es schwierig, die korrekte Playlist manuell zu identifizieren.
|
||||
|
||||
---
|
||||
|
||||
## Ripsters Analyse-Algorithmus
|
||||
|
||||
`playlistAnalysis.js` analysiert alle von MakeMKV erkannten Playlists nach mehreren Kriterien:
|
||||
|
||||
### 1. Laufzeit-Matching
|
||||
|
||||
Die erwartete Laufzeit (aus OMDb-Metadaten) wird mit der Playlist-Laufzeit verglichen:
|
||||
|
||||
```
|
||||
Filmtitel: Inception (2010)
|
||||
OMDb-Laufzeit: 148 Minuten
|
||||
|
||||
Playlist 00800.mpls: 148:22 → ✅ Match
|
||||
Playlist 00801.mpls: 1:23 → ❌ Zu kurz
|
||||
Playlist 00900.mpls: 148:25 → ✅ Match (Duplikat?)
|
||||
```
|
||||
|
||||
### 2. Titel-Ähnlichkeit
|
||||
|
||||
Playlists mit Namen, die dem Filmtitel ähneln, werden bevorzugt.
|
||||
|
||||
### 3. Segment-Validierung
|
||||
|
||||
Die Playlist-Segmente werden auf logische Reihenfolge geprüft.
|
||||
|
||||
### 4. Häufigkeits-Analyse
|
||||
|
||||
Bei mehreren Kandidaten: Welche Segment-Kombination kommt am häufigsten vor?
|
||||
|
||||
---
|
||||
|
||||
## Benutzer-Interface
|
||||
|
||||
Wenn Playlist-Obfuskierung erkannt wird, zeigt Ripster im `MetadataSelectionDialog` eine Playlist-Auswahl:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Playlist auswählen │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ ★ 00800.mpls 2:28:05 ✓ Empfohlen (Laufzeit passt) │
|
||||
│ 00801.mpls 0:01:23 Kurz (wahrscheinlich Menü) │
|
||||
│ 00900.mpls 2:28:12 Mögliche Alternative │
|
||||
│ 00901.mpls 0:00:45 Kurz │
|
||||
│ ... ... ... │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Hinweis: 847 Playlists gefunden – Analyse empfiehlt │
|
||||
│ Playlist 00800.mpls als Hauptfilm. │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Analyse-Ergebnis-Format
|
||||
|
||||
```json
|
||||
{
|
||||
"candidates": [
|
||||
{
|
||||
"playlist": "00800.mpls",
|
||||
"duration": "2:28:05",
|
||||
"durationSeconds": 8885,
|
||||
"score": 0.95,
|
||||
"recommended": true,
|
||||
"reasons": ["Laufzeit stimmt mit OMDb überein", "Häufigste Segment-Kombination"]
|
||||
},
|
||||
{
|
||||
"playlist": "00900.mpls",
|
||||
"duration": "2:28:12",
|
||||
"durationSeconds": 8892,
|
||||
"score": 0.72,
|
||||
"recommended": false,
|
||||
"reasons": ["Ähnliche Laufzeit", "Seltene Segment-Kombination"]
|
||||
}
|
||||
],
|
||||
"totalPlaylists": 847,
|
||||
"recommendation": "00800.mpls"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Manuelle Auswahl
|
||||
|
||||
Falls die automatische Empfehlung nicht korrekt ist:
|
||||
|
||||
1. Wähle eine andere Playlist aus der Liste
|
||||
2. Beachte die Laufzeit-Angabe
|
||||
3. Vergleiche mit der erwarteten Filmlänge (aus OMDb oder Disc-Hülle)
|
||||
|
||||
!!! tip "Tipp"
|
||||
Bei Blu-rays von bekannten Filmen kannst du die korrekte Playlist oft über Foren wie [MakeMKV-Forum](https://www.makemkv.com/forum/) verifizieren.
|
||||
|
||||
---
|
||||
|
||||
## Konfiguration
|
||||
|
||||
Die Playlist-Analyse ist automatisch aktiv. Einstellbar ist:
|
||||
|
||||
| Parameter | Beschreibung |
|
||||
|----------|-------------|
|
||||
| `makemkv_min_length_minutes` | Mindestlänge, um als Hauptfilm-Kandidat zu gelten (Standard: 15 Min) |
|
||||
222
docs/pipeline/workflow.md
Normal file
222
docs/pipeline/workflow.md
Normal file
@@ -0,0 +1,222 @@
|
||||
# Workflow & Zustände
|
||||
|
||||
Der Ripping-Workflow von Ripster ist als **State Machine** implementiert. Jeder Zustand hat klar definierte Übergangsbedingungen und Aktionen.
|
||||
|
||||
---
|
||||
|
||||
## Zustandsdiagramm
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
direction LR
|
||||
[*] --> IDLE
|
||||
|
||||
IDLE --> ANALYZING: Disc erkannt\n(automatisch)
|
||||
ANALYZING --> METADATA_SELECTION: MakeMKV-Analyse\nabgeschlossen
|
||||
METADATA_SELECTION --> READY_TO_START: Benutzer wählt\nMetadaten + Playlist
|
||||
|
||||
READY_TO_START --> RIPPING: Benutzer startet\nden Job
|
||||
|
||||
RIPPING --> MEDIAINFO_CHECK: MKV/Backup\nerstellt
|
||||
MEDIAINFO_CHECK --> READY_TO_ENCODE: Track-Analyse\nabgeschlossen
|
||||
|
||||
READY_TO_ENCODE --> ENCODING: Benutzer bestätigt\nEncode + Tracks
|
||||
|
||||
ENCODING --> FINISHED: HandBrake\nfertig
|
||||
FINISHED --> IDLE: Disc auswerfen /\nneue Disc
|
||||
|
||||
RIPPING --> ERROR: Fehler
|
||||
ENCODING --> ERROR: Fehler
|
||||
ANALYZING --> ERROR: Fehler
|
||||
ERROR --> IDLE: cancelPipeline()\noder retryJob()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Zustandsbeschreibungen
|
||||
|
||||
### IDLE
|
||||
|
||||
**Ausgangszustand.** Ripster wartet auf eine Disc.
|
||||
|
||||
- `diskDetectionService` pollt das Laufwerk (Intervall konfigurierbar)
|
||||
- Bei Disc-Erkennung: Automatischer Übergang zu `ANALYZING`
|
||||
- WebSocket-Event: `DISC_DETECTED`
|
||||
|
||||
---
|
||||
|
||||
### ANALYZING
|
||||
|
||||
**MakeMKV analysiert die Disc-Struktur.**
|
||||
|
||||
```bash
|
||||
makemkvcon -r info disc:0
|
||||
```
|
||||
|
||||
- Liest Titel-Informationen, Playlist-Liste, Track-Details
|
||||
- Fortschritt wird über WebSocket übertragen
|
||||
- Bei Blu-ray: Playlist-Liste für spätere Analyse gesammelt
|
||||
- Dauer: 30 Sekunden bis 5 Minuten
|
||||
|
||||
**Ausgabe:** JSON-Struktur mit allen Titeln und Playlists
|
||||
|
||||
---
|
||||
|
||||
### METADATA_SELECTION
|
||||
|
||||
**Wartet auf Benutzer-Eingabe.**
|
||||
|
||||
- `MetadataSelectionDialog` wird im Frontend angezeigt
|
||||
- Benutzer sucht in OMDb nach dem Filmtitel
|
||||
- Benutzer wählt einen Eintrag aus den Suchergebnissen
|
||||
- Bei Blu-ray: Playlist-Auswahl (mit Empfehlung durch `playlistAnalysis.js`)
|
||||
|
||||
**Übergang:** `selectMetadata(jobId, omdbData, playlist)` aufrufen
|
||||
|
||||
---
|
||||
|
||||
### READY_TO_START
|
||||
|
||||
**Metadaten bestätigt, bereit zum Starten.**
|
||||
|
||||
- Job-Datensatz in Datenbank mit Metadaten aktualisiert
|
||||
- Start-Button im Dashboard aktiv
|
||||
- Benutzer kann Metadaten noch mal ändern
|
||||
|
||||
**Übergang:** `startJob(jobId)` aufrufen
|
||||
|
||||
---
|
||||
|
||||
### RIPPING
|
||||
|
||||
**MakeMKV rippt die Disc.**
|
||||
|
||||
=== "MKV-Modus (Standard)"
|
||||
|
||||
```bash
|
||||
makemkvcon mkv disc:0 all /path/to/raw/ \
|
||||
--minlength=900
|
||||
```
|
||||
|
||||
Erstellt MKV-Datei(en) direkt aus den gewählten Titeln.
|
||||
|
||||
=== "Backup-Modus"
|
||||
|
||||
```bash
|
||||
makemkvcon backup disc:0 /path/to/raw/backup/ \
|
||||
--decrypt
|
||||
```
|
||||
|
||||
Erstellt vollständiges Disc-Backup inkl. Menüs.
|
||||
|
||||
**Live-Updates:** Fortschritt wird zeilenweise aus MakeMKV-Ausgabe geparst:
|
||||
|
||||
```
|
||||
PRGC:5012,0,2048 → Fortschritt: X%
|
||||
PRGT:5011,0,"..." → Aktueller Task
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### MEDIAINFO_CHECK
|
||||
|
||||
**MediaInfo analysiert die gerippte Datei.**
|
||||
|
||||
```bash
|
||||
mediainfo --Output=JSON /path/to/raw/file.mkv
|
||||
```
|
||||
|
||||
- Liest alle Audio-, Untertitel- und Video-Tracks
|
||||
- Extrahiert Codec-Informationen (DTS, TrueHD, AC-3, ...)
|
||||
- Bestimmt Sprachcodes (ISO 639)
|
||||
- Erstellt Encode-Plan via `encodePlan.js`
|
||||
|
||||
---
|
||||
|
||||
### READY_TO_ENCODE
|
||||
|
||||
**Encode-Plan erstellt, wartet auf Bestätigung.**
|
||||
|
||||
- `MediaInfoReviewPanel` wird im Frontend angezeigt
|
||||
- Benutzer kann Audio- und Untertitel-Tracks de/aktivieren
|
||||
- Vorgeschlagene Tracks basierend auf Sprach-Einstellungen
|
||||
|
||||
**Übergang:** `confirmEncode(jobId, trackSelection)` aufrufen
|
||||
|
||||
---
|
||||
|
||||
### ENCODING
|
||||
|
||||
**HandBrake encodiert die Datei.**
|
||||
|
||||
```bash
|
||||
HandBrakeCLI \
|
||||
--input /path/to/raw.mkv \
|
||||
--output /path/to/movies/Inception\ \(2010\).mkv \
|
||||
--preset "H.265 MKV 1080p30" \
|
||||
--audio 1,2 \
|
||||
--subtitle 1
|
||||
```
|
||||
|
||||
**Live-Updates:** Fortschritt wird aus HandBrake-stderr geparst:
|
||||
|
||||
```
|
||||
Encoding: task 1 of 1, 73.50 %
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### FINISHED
|
||||
|
||||
**Job erfolgreich abgeschlossen.**
|
||||
|
||||
- Ausgabedatei liegt im konfigurierten `movie_dir`
|
||||
- Job-Status in Datenbank auf `FINISHED` gesetzt
|
||||
- PushOver-Benachrichtigung (falls konfiguriert)
|
||||
- WebSocket-Event: `JOB_COMPLETE`
|
||||
|
||||
---
|
||||
|
||||
### ERROR
|
||||
|
||||
**Fehler aufgetreten.**
|
||||
|
||||
- Fehlerdetails im Job-Datensatz gespeichert
|
||||
- Fehler-Logs verfügbar in der History
|
||||
- **Retry**: Job kann vom Fehlerzustand neu gestartet werden
|
||||
- **Abbrechen**: Pipeline zurück zu IDLE
|
||||
|
||||
---
|
||||
|
||||
## Abbrechen & Retry
|
||||
|
||||
### Pipeline abbrechen
|
||||
|
||||
```http
|
||||
POST /api/pipeline/cancel
|
||||
```
|
||||
|
||||
- Sendet SIGINT an aktiven Prozess
|
||||
- Wartet auf graceful exit (Timeout: 10 Sekunden)
|
||||
- Falls kein graceful exit: SIGKILL
|
||||
- Pipeline-Zustand zurück zu IDLE
|
||||
|
||||
### Job wiederholen
|
||||
|
||||
```http
|
||||
POST /api/pipeline/retry/:jobId
|
||||
```
|
||||
|
||||
- Setzt Job-Status zurück auf `READY_TO_START`
|
||||
- Behält Metadaten und Playlist-Auswahl
|
||||
- Pipeline neu starten mit vorhandenen Daten
|
||||
|
||||
### Re-Encode
|
||||
|
||||
```http
|
||||
POST /api/pipeline/reencode/:jobId
|
||||
```
|
||||
|
||||
- Encodiert bestehende Raw-MKV neu
|
||||
- Nützlich für geänderte Encoding-Einstellungen
|
||||
- Kein neues Ripping erforderlich
|
||||
Reference in New Issue
Block a user