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

docs: Doku für Skript-Integration und neue Pipeline-Zustände

Browse Source
This commit is contained in:
mboehmlaender
2026-03-05 10:04:50 +00:00
parent 3957773854
commit 922d3e753d
7 changed files with 543 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

156
docs/api/pipeline.md
View File

@@ -27,28 +27,49 @@ Gibt den aktuellen Pipeline-Zustand zurück.
}
```
**States:**
**Pipeline-Zustände:**
| Wert | Beschreibung |
|------|-------------|
| `IDLE` | Wartet auf Disc |
| `ANALYZING` | MakeMKV analysiert |
| `METADATA_SELECTION` | Wartet auf Benutzer |
| `DISC_DETECTED` | Disc erkannt, wartet auf Benutzer |
| `METADATA_SELECTION` | Disc-Scan läuft / Metadaten-Dialog |
| `WAITING_FOR_USER_DECISION` | Mehrere Playlist-Kandidaten – manuelle Auswahl |
| `READY_TO_START` | Bereit zum Starten |
| `RIPPING` | Rippen läuft |
| `MEDIAINFO_CHECK` | Track-Analyse |
| `READY_TO_ENCODE` | Wartet auf Bestätigung |
| `ENCODING` | Encoding läuft |
| `RIPPING` | MakeMKV-Ripping läuft |
| `MEDIAINFO_CHECK` | HandBrake-Scan & Encode-Plan-Erstellung |
| `READY_TO_ENCODE` | Wartet auf Encode-Bestätigung |
| `ENCODING` | HandBrake encodiert |
| `POST_ENCODE_SCRIPTS` | Post-Encode-Skripte laufen |
| `FINISHED` | Abgeschlossen |
| `ERROR` | Fehler |
**Kontext-Felder (state-abhängig):**
Beim Zustand `WAITING_FOR_USER_DECISION` enthält die Response zusätzlich:
```json
{
"state": "WAITING_FOR_USER_DECISION",
"context": {
"playlistAnalysis": {
"evaluatedCandidates": [...],
"recommendation": { "playlistId": "00800", "score": 18 },
"manualDecisionRequired": true,
"manualDecisionReason": "multiple_candidates_after_min_length"
},
"playlistCandidates": ["00800", "00801", "00900"]
}
}
```
---
## POST /api/pipeline/analyze
Startet eine manuelle Disc-Analyse (ohne Disc-Detection-Trigger).
Startet eine manuelle Disc-Analyse.
**Request:** Kein Body erforderlich
**Request:** Kein Body
**Response:**
@@ -65,11 +86,7 @@ Startet eine manuelle Disc-Analyse (ohne Disc-Detection-Trigger).
Erzwingt eine erneute Disc-Erkennung.
**Response:**
```json
{ "ok": true }
```
**Response:** `{ "ok": true }`
---
@@ -81,27 +98,17 @@ Sucht in der OMDb-API nach einem Filmtitel.
| Parameter | Typ | Beschreibung |
|----------|-----|-------------|
| `q` | string | Suchbegriff (Filmtitel) |
| `q` | string | Suchbegriff |
| `type` | string | `movie` oder `series` (optional) |
**Beispiel:**
```
GET /api/pipeline/omdb/search?q=Inception&type=movie
```
**Beispiel:** `GET /api/pipeline/omdb/search?q=Inception&type=movie`
**Response:**
```json
{
"results": [
{
"imdbId": "tt1375666",
"title": "Inception",
"year": "2010",
"type": "movie",
"poster": "https://m.media-amazon.com/images/..."
}
{ "imdbId": "tt1375666", "title": "Inception", "year": "2010", "type": "movie", "poster": "https://..." }
]
}
```
@@ -110,7 +117,7 @@ GET /api/pipeline/omdb/search?q=Inception&type=movie
## POST /api/pipeline/select-metadata
Bestätigt Metadaten und Playlist-Auswahl für den aktuellen Job.
Bestätigt Metadaten und optionale Playlist-Auswahl.
**Request:**
@@ -124,31 +131,28 @@ Bestätigt Metadaten und Playlist-Auswahl für den aktuellen Job.
"type": "movie",
"poster": "https://..."
},
"playlist": "00800.mpls"
"selectedPlaylist": "00800"
}
```
`playlist` ist optional und nur bei Blu-rays relevant.
!!! info "Playlist-Felder"
`selectedPlaylist` ist optional. Wird es beim ersten Aufruf weggelassen (kein Obfuskierungsverdacht), wird die Empfehlung automatisch übernommen.
**Response:**
Beim zweiten Aufruf aus dem `WAITING_FOR_USER_DECISION`-Dialog reicht es, nur `jobId` + `selectedPlaylist` zu schicken – `omdb` kann dann weggelassen werden.
```json
{ "ok": true }
```
**Response:** `{ "ok": true }`
---
## POST /api/pipeline/start/:jobId
Startet den Ripping-Prozess für einen vorbereiteten Job.
Startet den Ripping-Prozess.
**URL-Parameter:** `jobId` – ID des Jobs
**URL-Parameter:** `jobId`
**Response:**
**Response:** `{ "ok": true, "message": "Ripping gestartet" }`
```json
{ "ok": true, "message": "Ripping gestartet" }
```
**Sonderfall:** Falls für den Job bereits eine Raw-Datei vorhanden ist, wird das Ripping übersprungen und direkt der HandBrake-Scan gestartet.
**Fehlerfälle:**
- `404` – Job nicht gefunden
@@ -158,40 +162,45 @@ Startet den Ripping-Prozess für einen vorbereiteten Job.
## POST /api/pipeline/confirm-encode/:jobId
Bestätigt die Encode-Konfiguration mit Track-Auswahl.
Bestätigt die Encode-Konfiguration mit Track-Auswahl und Post-Encode-Skripten.
**URL-Parameter:** `jobId` – ID des Jobs
**URL-Parameter:** `jobId`
**Request:**
```json
{
"audioTracks": [1, 2],
"subtitleTracks": [1]
"selectedEncodeTitleId": 1,
"selectedTrackSelection": {
"1": {
"audioTrackIds": [1, 2],
"subtitleTrackIds": [1]
}
},
"selectedPostEncodeScriptIds": ["script-abc123", "script-def456"]
}
```
Track-Indizes entsprechen den 1-basierten Track-Nummern aus dem Encode-Plan.
| Feld | Typ | Beschreibung |
|------|-----|-------------|
| `selectedEncodeTitleId` | number | HandBrake-Titel-ID (aus dem Encode-Plan) |
| `selectedTrackSelection` | object | Pro Titel: Audio- und Untertitel-Track-IDs |
| `selectedPostEncodeScriptIds` | string[] | Skript-IDs in Ausführungsreihenfolge (optional) |
**Response:**
!!! note "Track-IDs"
Die Track-IDs entsprechen den `id`-Feldern aus dem Encode-Plan (`encode_plan_json`), nicht den rohen HandBrake-Track-Nummern.
```json
{ "ok": true, "message": "Encoding gestartet" }
```
**Response:** `{ "ok": true, "message": "Encoding gestartet" }`
---
## POST /api/pipeline/cancel
Bricht den aktuellen Pipeline-Prozess ab.
Bricht den aktiven Pipeline-Prozess ab.
**Response:**
**Response:** `{ "ok": true, "message": "Pipeline abgebrochen" }`
```json
{ "ok": true, "message": "Pipeline abgebrochen" }
```
Der laufende Prozess wird mit SIGINT beendet (Fallback: SIGKILL nach Timeout).
SIGINT → graceful exit (10 s Timeout) → SIGKILL.
---
@@ -199,13 +208,7 @@ Der laufende Prozess wird mit SIGINT beendet (Fallback: SIGKILL nach Timeout).
Wiederholt einen fehlgeschlagenen Job.
**URL-Parameter:** `jobId` – ID des Jobs
**Response:**
```json
{ "ok": true, "message": "Job wird wiederholt" }
```
**Response:** `{ "ok": true, "message": "Job wird wiederholt" }`
**Fehlerfälle:**
- `404` – Job nicht gefunden
@@ -215,35 +218,28 @@ Wiederholt einen fehlgeschlagenen Job.
## POST /api/pipeline/resume-ready/:jobId
Setzt einen Job im Status `READY_TO_ENCODE` zurück in die aktive Pipeline.
Reaktiviert einen Job im Status `READY_TO_ENCODE` in die aktive Pipeline (z. B. nach Neustart).
**URL-Parameter:** `jobId` – ID des Jobs
**Response:**
```json
{ "ok": true }
```
**Response:** `{ "ok": true }`
---
## POST /api/pipeline/reencode/:jobId
Startet ein erneutes Encoding für einen abgeschlossenen Job (ohne erneutes Ripping).
**URL-Parameter:** `jobId` – ID des Jobs
Encodiert eine abgeschlossene Raw-MKV erneut – ohne Ripping.
**Request:**
```json
{
"audioTracks": [1, 2],
"subtitleTracks": [1]
"selectedEncodeTitleId": 1,
"selectedTrackSelection": {
"1": { "audioTrackIds": [1, 2], "subtitleTrackIds": [1] }
},
"selectedPostEncodeScriptIds": ["script-abc123"]
}
```
**Response:**
Gleiche Struktur wie `confirm-encode` – ermöglicht andere Track-Auswahl und Skripte als beim ersten Encoding.
```json
{ "ok": true, "message": "Re-Encoding gestartet" }
```
**Response:** `{ "ok": true, "message": "Re-Encoding gestartet" }`

133
docs/api/settings.md
View File

@@ -113,6 +113,139 @@ Sendet eine Test-Benachrichtigung über PushOver.
---
## Skript-Verwaltung
Post-Encode-Skripte werden über eigene Endpunkte unter `/api/settings/scripts` verwaltet.
### GET /api/settings/scripts
Gibt alle konfigurierten Skripte zurück.
**Response:**
```json
{
"scripts": [
{
"id": "script-abc123",
"name": "Zu Plex verschieben",
"command": "/home/michael/scripts/move-to-plex.sh",
"description": "Verschiebt die fertige Datei ins Plex-Verzeichnis",
"createdAt": "2024-01-15T10:00:00.000Z"
}
]
}
```
---
### POST /api/settings/scripts
Legt ein neues Post-Encode-Skript an.
**Request:**
```json
{
"name": "Zu Plex verschieben",
"command": "/home/michael/scripts/move-to-plex.sh",
"description": "Verschiebt die fertige Datei ins Plex-Verzeichnis"
}
```
| Feld | Typ | Pflicht | Beschreibung |
|------|-----|---------|-------------|
| `name` | string | ✅ | Anzeigename |
| `command` | string | ✅ | Shell-Befehl oder absoluter Skriptpfad |
| `description` | string | — | Optionale Beschreibung |
**Response:**
```json
{
"ok": true,
"script": {
"id": "script-abc123",
"name": "Zu Plex verschieben",
"command": "/home/michael/scripts/move-to-plex.sh"
}
}
```
---
### PUT /api/settings/scripts/:scriptId
Aktualisiert ein vorhandenes Skript.
**URL-Parameter:** `scriptId`
**Request:** Gleiche Felder wie beim Anlegen (alle optional).
```json
{ "name": "Zu Jellyfin verschieben", "command": "/home/michael/scripts/move-to-jellyfin.sh" }
```
**Response:** `{ "ok": true }`
---
### DELETE /api/settings/scripts/:scriptId
Löscht ein Skript.
**URL-Parameter:** `scriptId`
**Response:** `{ "ok": true }`
!!! warning "Referenzen in Jobs"
Wenn das Skript in laufenden oder abgeschlossenen Jobs referenziert wird, wird es trotzdem gelöscht. In zukünftigen Encode-Reviews erscheint es nicht mehr.
---
### POST /api/settings/scripts/:scriptId/test
Führt ein Skript mit Platzhalter-Umgebungsvariablen aus (Testlauf).
**URL-Parameter:** `scriptId`
**Response (Erfolg):**
```json
{
"ok": true,
"exitCode": 0,
"stdout": "Testausgabe des Skripts",
"stderr": "",
"durationMs": 245
}
```
**Response (Fehler):**
```json
{
"ok": false,
"exitCode": 1,
"stdout": "",
"stderr": "Datei nicht gefunden: /home/michael/scripts/move-to-plex.sh",
"durationMs": 12
}
```
**Platzhalter-Werte beim Testlauf:**
| Variable | Testwert |
|---------|---------|
| `RIPSTER_OUTPUT_PATH` | `/tmp/ripster-test-output.mkv` |
| `RIPSTER_JOB_ID` | `0` |
| `RIPSTER_TITLE` | `Test Film` |
| `RIPSTER_YEAR` | `2024` |
| `RIPSTER_IMDB_ID` | `tt0000000` |
| `RIPSTER_RAW_PATH` | `/tmp/ripster-test-raw.mkv` |
---
## Einstellungs-Schlüssel Referenz
Eine vollständige Liste aller Einstellungs-Schlüssel: