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

1.0.0 1.0.0 final
Deploy Docs to GitHub Pages / Build Documentation (push) Has been cancelled
Details
Deploy Docs to GitHub Pages / Deploy to GitHub Pages (push) Has been cancelled
Details

Browse Source
This commit is contained in:
mboehmlaender
2026-06-12 09:48:45 +02:00
parent 04acda6400
commit c6d884dc3f
16 changed files with 1517 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+183 -208
View File
@@ -1,257 +1,232 @@
# Ripster
Ripster ist eine lokale Web-Anwendung für halbautomatisches Disc-Ripping, Audiobook-Verarbeitung und Datei-Konvertierung. Plugin-basierte Architektur mit MakeMKV + HandBrake + FFmpeg, inklusive Metadaten-Auswahl, Track-Review, Queue, Skripten/Ketten und Job-Historie.
Ripster ist eine lokale Web-Anwendung für Disc-Ripping, Audiobook-Verarbeitung und Datei-Konvertierung. Das System kombiniert MakeMKV, HandBrake, FFmpeg, `cdparanoia`, `mkvmerge`, SQLite und eine React-Oberfläche zu einer durchgehenden Pipeline mit Queue, Historie, Downloads, Skript-Automation und Echtzeitstatus per WebSocket.
---
## Funktionsumfang
## Was Ripster kann
### Medien-Workflows
- Blu-ray-Ripping und -Encoding
- DVD-Ripping und -Encoding
- Audio-CD-Ripping und -Encoding
- Audiobook-Verarbeitung aus `.aax`
- Datei-Converter für Audio-, Video- und ISO-Dateien
### Disc-Ripping & Encoding
- Disc-Erkennung mit Pipeline-Status in Echtzeit (WebSocket)
- Medienprofil-Erkennung (Blu-ray/DVD/CD/Sonstiges) aus Device-/Filesystem-Heuristik
- Metadaten-Suche und Zuordnung über OMDb
- MakeMKV-Analyse und Rip (`mkv` oder `backup`) mit profilspezifischen Settings
- HandBrake-Review und Encoding mit Track-Auswahl, User-Presets, Extra-Args
- **Audio-CD-Ripping** mit cdparanoia + Encoding nach FLAC/MP3/Opus/Vorbis (experimentell)
### Video (Blu-ray / DVD)
- automatische Disc-Erkennung, Rescan einzelner Laufwerke und Live-Status im Ripper
- Metadaten-Suche über TMDB für Filme und Serien
- HandBrake-Review mit Playlist-/Titel-Auswahl, Audio-/Untertitel-Track-Auswahl und Encode-Vorschau
- MakeMKV-Rip mit profilspezifischen Modi und Zusatzargumenten
- HandBrake-Encoding mit User-Presets, offiziellen HandBrake-Presets und Extra-Args
- Serien-Workflows für DVD- und Blu-ray-Discs inkl. Episoden-Zuordnung und Batch-Encoding
- Multipart-Movie-Workflows über mehrere Discs inkl. Merge-Job via `mkvmerge`
- Re-Encode aus RAW, Review-Neustart, Encode-Neustart, Retry und Resume laufender/unterbrochener Jobs
### Audiobook-Verarbeitung
- **AAX/Audible-Dateien** verarbeiten (Activation Bytes, DRM-Handling)
- FFmpeg-basiertes Kapitel-Splitting
- Ausgabeformate: M4B, MP3, FLAC mit Metadaten
- MusicBrainz-Metadaten-Lookup
### Audio-CD
- TOC-Analyse und Rip mit `cdparanoia`
- MusicBrainz-Suche und Übernahme von Album-/Track-Metadaten
- Track-Auswahl und Ausgabe als FLAC, WAV, MP3, Opus oder Ogg Vorbis
- RAW-Wiederverwendung und CD-Review-/Encode-Neustart aus vorhandenen Daten
### Datei-Converter
- **Generische Audio/Video-Dateien** konvertieren (MKV, MP4, FLAC, MP3, u. v. m.)
- Datei-Explorer mit Upload, Umbenennen, Verschieben, Löschen
- Automatischer Verzeichnis-Scan (Polling konfigurierbar)
### Audiobooks
- Upload und Verarbeitung von Audible-/AAX-Dateien
- Activation-Bytes-Cache für DRM-geschützte Titel
- Metadaten- und Kapitelanreicherung über Audnex plus lokale Probe-Daten
- Ausgabe als M4B, MP3 oder FLAC
- Einzeldatei oder kapitelweises Splitten
### Automatisierung & Verwaltung
- Pre- und Post-Encode-Ausführungen (Skripte und/oder Skript-Ketten)
- Pipeline-Queue mit Job- und Nicht-Job-Einträgen (`script`, `chain`, `wait`)
- Cron-Jobs für Skripte/Ketten (inkl. Logs und manueller Auslösung)
- **Aktivitäts-Tracking**: Laufende und abgeschlossene Aktionen in Echtzeit im Ripper
- Download-Queue: Ausgabedateien als ZIP herunterladen
- Historie mit Re-Encode, Review-Neustart, File-/Job-Löschung und Orphan-Import
- Hardware-Monitoring (CPU/RAM/GPU/Storage) im Ripper
### Converter
- Dateibaum und Datei-Explorer für das Converter-RAW-Verzeichnis
- Upload, Ordner anlegen, Umbenennen, Verschieben und Löschen
- Jobs aus Dateiauswahl erzeugen, Dateien bestehenden Jobs zuweisen oder daraus entfernen
- Audio-/Video-Erkennung und automatische RAW-Scans per Polling
- TMDB-Metadatenzuordnung für passende Video-Jobs
## Tech-Stack
### Automation, Betrieb und Verwaltung
- Queue mit normalen Jobs sowie zusätzlichen `script`-, `chain`- und `wait`-Einträgen
- Pre-/Post-Encode-Skripte und Skript-Ketten
- Cron-Jobs für Skripte und Ketten inkl. Validierung, Logs und manueller Auslösung
- Download-Queue für ZIP-Archive aus Historienjobs
- Historie mit Detailansicht, Re-Encode, Review-/Encode-Neustart, Retry und Löschfunktionen
- `/database`-Ansicht für Orphan-RAW-Ordner (Import oder Löschen vorhandener RAW-Daten)
- Hardware-Monitoring mit Live-Werten und Verlaufshistorie
- Pushover-Benachrichtigungen für zentrale Pipeline-Ereignisse
- MakeMKV-Betakey-Prüfung/-Übernahme und Cover-Art-Recovery
- Backend: Node.js, Express, SQLite, WebSocket (`ws`) – **Plugin-Architektur**
- Frontend: React, Vite, PrimeReact
- Externe Tools: `makemkvcon`, `HandBrakeCLI`, `mediainfo`, `ffmpeg`/`ffprobe`, `cdparanoia`
## Oberfläche
## Dokumentation
- `Ripper`: Disc-Erkennung, Pipeline-Status, Queue, Review-Dialoge und aktive Jobs
- `Converter`: Dateibaum, Uploads und Converter-Jobs
- `Audiobooks`: AAX-Uploads und Audiobook-Jobs
- `Settings`: Pfade, Tools, Templates, Queue, Monitoring, Notifications, Scripts, Chains, Presets
- `Historie`: abgeschlossene und fehlerhafte Jobs mit Folgeaktionen
- `Downloads`: vorbereitete ZIP-Downloads
- `Database`: Orphan-RAW-Verwaltung (im Expertenmodus)
- Zusatzansichten: `Hardware` und `TMDB Migration`
- Ausführliche Dokumentation: https://mboehmlaender.github.io/ripster/
## Installation
## Voraussetzungen
Der korrekte Bootstrap läuft über `setup.sh`. `setup.sh` lädt das passende `install.sh` aus dem gewünschten Branch und startet es mit denselben Parametern.
- Debian 11/12 oder Ubuntu 22.04/24.04
- root-Rechte + Internetzugang
- optisches Laufwerk (oder gemountete Quelle) für Disc-Ripping
- Netzwerk-Zugang für Audiobook-Upload und Datei-Converter optional
Unterstützte Systeme laut Installer:
- Debian
- Ubuntu
- Linux Mint
- Pop!_OS
## Schnellstart (`install.sh`)
Auf Debian 11/12 oder Ubuntu 22.04/24.04 (root erforderlich):
Standardinstallation:
```bash
wget -qO install.sh https://raw.githubusercontent.com/Mboehmlaender/ripster/main/install.sh
sudo bash install.sh
curl -fsSL https://raw.githubusercontent.com/Mboehmlaender/ripster/main/setup.sh | bash -s -- --branch dev
```
Alternativ direkt per Pipe:
Alternativ per Datei:
```bash
curl -fsSL https://raw.githubusercontent.com/Mboehmlaender/ripster/main/install.sh | sudo bash
wget -qO setup.sh https://raw.githubusercontent.com/Mboehmlaender/ripster/main/setup.sh
bash setup.sh --branch dev
```
`install.sh` übernimmt u. a.:
Hinweise:
- `setup.sh` nutzt bei Bedarf `sudo`; root-Rechte und Internetzugang sind erforderlich.
- Ohne `--branch` bietet `setup.sh` lokal eine Branch-Auswahl an. Bei `curl | bash` sollte `--branch` gesetzt werden.
- Der eigentliche Installer ist `install.sh`; `setup.sh` ist der empfohlene Einstiegspunkt.
- Node.js 20 (falls nötig)
- Basistools inkl. `mediainfo`, `ffmpeg`, `ffprobe`
- CD-Ripping-Tools (`cdparanoia`, `flac`, `lame`, `opus-tools`, `vorbis-tools`)
- MakeMKV
- HandBrake CLI (Auswahl Standard/CPU oder GPU/NVDEC-Binary für HW-Encoding)
- nginx
- Repository-Checkout, npm-Install, Frontend-Build, systemd-Service (`ripster-backend`)
Danach ist Ripster unter `http://<Server-IP>` erreichbar.
Wichtige Optionen:
Wichtige Standardparameter für den Installationslauf:
```bash
sudo bash install.sh --branch dev # Branch wählen (Default im Skript: dev)
sudo bash install.sh --dir /opt/ripster # Installationspfad
sudo bash install.sh --user ripster # Service-User
sudo bash install.sh --port 3001 # Backend-Port
sudo bash install.sh --host 192.168.1.10 # Host/IP für nginx/CORS
sudo bash install.sh --no-makemkv # MakeMKV überspringen
sudo bash install.sh --no-handbrake # HandBrake überspringen
sudo bash install.sh --no-nginx # nginx-Setup überspringen
sudo bash install.sh --reinstall # Update (Daten bleiben erhalten)
sudo bash install.sh --help # Hilfe anzeigen
bash setup.sh --branch dev --dir /opt/ripster --user ripster --port 3001 --host 192.168.1.10
```
Verfügbare Optionen:
- `--branch <branch>`
- `--dir <pfad>`
- `--user <benutzer>`
- `--port <port>`
- `--host <hostname|ip>`
- `--no-makemkv`
- `--no-handbrake`
- `--no-nginx`
- `--no-system-deps`
- `--reinstall`
- `--help`
Was der Installer typischerweise einrichtet:
- Node.js 20
- `ffmpeg`, `ffprobe`, `mediainfo`, `mkvtoolnix`
- CD-Tools (`cdparanoia`, `flac`, `lame`, `opus-tools`, `vorbis-tools`)
- optional MakeMKV
- optional HandBrakeCLI
- optional nginx
- Repository-Checkout bzw. Update
- npm-Abhängigkeiten, Frontend-Build und `ripster-backend`-systemd-Service
## Update
Standard-Update einer bestehenden Installation:
```bash
sudo bash /opt/ripster/install.sh --reinstall --branch dev
```
Wenn die Installation mit abweichenden Kernparametern eingerichtet wurde, diese beim Update wieder mitgeben:
```bash
sudo bash /opt/ripster/install.sh --reinstall --branch dev --dir /opt/ripster --user ripster --port 3001 --host 192.168.1.10
```
Alternativ kann auch erneut über `setup.sh` gebootstrapped werden:
```bash
curl -fsSL https://raw.githubusercontent.com/Mboehmlaender/ripster/main/setup.sh | bash -s -- --branch dev --reinstall
```
`--reinstall` aktualisiert die Installation und behält die persistenten Daten der bestehenden Instanz bei.
## Entwicklung
Schnellstart für lokale Entwicklung:
```bash
./start.sh
```
`start.sh` prüft Node.js, installiert fehlende Abhängigkeiten und startet Backend und Frontend im Dev-Modus.
Wichtige npm-Skripte:
- `npm run dev`
- `npm run dev:backend`
- `npm run dev:frontend`
- `npm run build:frontend`
- `npm run start`
## Konfiguration
### UI-Settings (empfohlen)
Die meisten Einstellungen werden in der Weboberfläche unter `Settings` gepflegt und in SQLite gespeichert. Dazu gehören insbesondere:
- Pfade und Output-Templates für Blu-ray, DVD, Serie, CD, Audiobook, Converter, Downloads und Logs
- Tool-Kommandos für MakeMKV, HandBrake, MediaInfo, FFmpeg, FFprobe, `cdparanoia` und `mkvmerge`
- Laufwerksmodus, Disc-Erkennung und Queue-/Parallelisierungsregeln
- Hardware-Monitoring, Logging, Expert Mode und Cover-Art-Recovery
- TMDB-Zugangsdaten, Pushover, Skripte, Skript-Ketten, User-Presets und Preset-Defaults
Die meisten Einstellungen werden in der App unter `Settings` gepflegt und in SQLite gespeichert:
Zusätzliche Bootstrap-/Override-Variablen:
- Pfade: `Raw Ausgabeordner`, `Film Ausgabeordner`, `Log Ordner` (jeweils mit Blu-ray/DVD/Audiobook-Varianten)
- Pfade Converter: `Converter Raw-Ordner`, `Converter Ausgabe (Video)`, `Converter Ausgabe (Audio)`
- Tools: `MakeMKV Kommando`, `HandBrake Kommando`, `Mediainfo Kommando`, `FFmpeg Kommando`, `FFprobe Kommando`
- Profile: medientyp-spezifische Felder für Blu-ray/DVD/Sonstiges (z. B. Preset, Zusatzargumente, Ausgabeformat)
- Audiobook: Output-Template, RAW-Template
- Converter: erlaubte Endungen, Auto-Scan-Intervall, Output-Templates
- Queue/Monitoring: `Parallele Jobs`, `Hardware Monitoring aktiviert`, `Hardware Monitoring Intervall (ms)`
- Benachrichtigungen: PushOver
Backend:
- `PORT`
- `DB_PATH`
- `LOG_DIR`
- `LOG_LEVEL`
- `CORS_ORIGIN`
- `DEFAULT_TEMP_DIR`
- `DEFAULT_RAW_DIR`
- `DEFAULT_MOVIE_DIR`
- `DEFAULT_SERIES_DIR`
- `DEFAULT_CD_DIR`
- `DEFAULT_AUDIOBOOK_RAW_DIR`
- `DEFAULT_AUDIOBOOK_DIR`
- `DEFAULT_DOWNLOAD_DIR`
- `DEFAULT_CONVERTER_RAW_DIR`
- `DEFAULT_CONVERTER_MOVIE_DIR`
- `DEFAULT_CONVERTER_AUDIO_DIR`
### Umgebungsvariablen
Frontend:
- `VITE_API_BASE`
- `VITE_WS_URL`
Backend (`backend/src/config.js`):
## Daten, Logs und API
- `PORT` (Default: `3001`)
- `DB_PATH` (Default: `backend/data/ripster.db`)
- `LOG_DIR` (Default: `backend/logs`)
- `CORS_ORIGIN` (Default: `*`)
- `LOG_LEVEL` (`debug|info|warn|error`, Default: `info`)
- Standard-DB: `backend/data/ripster.db`
- Standard-Logs: `backend/logs`
- Standard-Outputs liegen relativ zum Datenverzeichnis, sofern in den Settings nichts anderes gesetzt ist.
- Das Schema wird beim Start geprüft und fehlende DB-Elemente werden migriert.
Frontend (Vite):
REST-Gruppen:
- `/api/health`
- `/api/pipeline/*`
- `/api/converter/*`
- `/api/history/*`
- `/api/downloads/*`
- `/api/settings/*`
- `/api/crons/*`
- `/api/runtime/*`
- `VITE_API_BASE` (Default: `/api`)
- `VITE_WS_URL` (optional, überschreibt automatische WS-URL)
- optional für Remote-Dev: `VITE_PUBLIC_ORIGIN`, `VITE_ALLOWED_HOSTS`, `VITE_HMR_PROTOCOL`, `VITE_HMR_HOST`, `VITE_HMR_CLIENT_PORT`
## Logs und Daten
Log-Ziel ist primär der in den Settings gepflegte `log_dir`.
- Backend-Logs: `<log_dir>/backend/backend-latest.log` und Tagesdateien
- Job-Logs: `<log_dir>/job-<id>.process.log`
- DB: `backend/data/ripster.db`
Hinweis: Beim DB-Init wird das Schema geprüft und fehlende Elemente werden migriert.
Realtime:
- WebSocket unter `/ws`
## Projektstruktur
```text
ripster/
backend/
src/
plugins/ # Plugin-System (BluRay, DVD, CD, Audiobook, Converter)
routes/
services/
db/
utils/
frontend/
src/
pages/ # Ripper, Settings, History, Converter, Downloads, Database
components/
api/
db/schema.sql
start.sh
db/
docs/
install.sh
install-dev.sh
setup.sh
start.sh
```
## API-Überblick
## Dokumentation
**Health**
- `GET /api/health`
Ausführlichere Dokumentation liegt in `docs/` und veröffentlicht unter:
**Pipeline**
- `GET /api/pipeline/state`
- `POST /api/pipeline/analyze`
- `POST /api/pipeline/rescan-disc`
- `POST /api/pipeline/select-metadata`
- `POST /api/pipeline/start/:jobId`
- `POST /api/pipeline/confirm-encode/:jobId`
- `POST /api/pipeline/cancel`
- `POST /api/pipeline/retry/:jobId`
- `POST /api/pipeline/reencode/:jobId`
- `POST /api/pipeline/restart-review/:jobId`
- `POST /api/pipeline/restart-encode/:jobId`
- `POST /api/pipeline/resume-ready/:jobId`
- `GET /api/pipeline/queue`
- `POST /api/pipeline/queue/reorder`
- `POST /api/pipeline/queue/entry`
- `DELETE /api/pipeline/queue/entry/:entryId`
**Converter**
- `GET /api/converter/tree`
- `GET /api/converter/browse`
- `POST /api/converter/scan`
- `POST /api/converter/create-jobs`
- `POST /api/converter/upload`
- `POST /api/converter/jobs/from-selection`
- `GET /api/converter/jobs`
- `GET /api/converter/jobs/:jobId`
- `POST /api/converter/jobs/:jobId/start`
- `POST /api/converter/jobs/:jobId/cancel`
- `DELETE /api/converter/jobs/:jobId`
- `DELETE /api/converter/files`
- `POST /api/converter/files/rename`
- `POST /api/converter/files/move`
- `POST /api/converter/files/folder`
**Downloads**
- `GET /api/downloads`
- `GET /api/downloads/summary`
- `POST /api/downloads/history/:jobId`
- `GET /api/downloads/:id/file`
- `DELETE /api/downloads/:id`
**History**
- `GET /api/history`
- `GET /api/history/:id`
- `GET /api/history/database`
- `GET /api/history/orphan-raw`
- `POST /api/history/orphan-raw/import`
- `POST /api/history/:id/omdb/assign`
- `POST /api/history/:id/delete-files`
- `POST /api/history/:id/delete`
**Settings**
- `GET /api/settings`
- `PUT /api/settings/:key`
- `PUT /api/settings`
- `GET/POST/PUT/DELETE /api/settings/scripts...`
- `GET/POST/PUT/DELETE /api/settings/script-chains...`
- `GET/POST/PUT/DELETE /api/settings/user-presets...`
- `POST /api/settings/pushover/test`
**Cron-Jobs**
- `GET /api/crons`
- `POST /api/crons`
- `GET /api/crons/:id`
- `PUT /api/crons/:id`
- `DELETE /api/crons/:id`
- `GET /api/crons/:id/logs`
- `POST /api/crons/:id/run`
- `POST /api/crons/validate-expression`
**Runtime-Aktivitäten**
- `GET /api/activities`
- `POST /api/activities/:id/cancel`
- `POST /api/activities/:id/next-step`
- `POST /api/activities/clear-recent`
## Troubleshooting
- WebSocket verbindet nicht:
- prüfen, ob Frontend über Vite-Proxy läuft (`/ws` -> Backend)
- bei Reverse-Proxy Upgrade-Header für `/ws` setzen
- Keine Disc erkannt:
- in den Settings `Laufwerksmodus` auf `Explizites Device` stellen und `Device Pfad` setzen (z. B. `/dev/sr0`)
- HandBrake/MakeMKV Fehler:
- CLI-Binaries im `PATH` prüfen
- Preset-Name mit `HandBrakeCLI -z` prüfen
- Startfehler wegen Schema:
- `db/schema.sql` vorhanden halten
## Sicherheit
- Keine echten Tokens/Passwörter ins Repository committen.
- Lokale Secrets in `.env` oder in Settings pflegen, aber nicht versionieren.
https://mboehmlaender.github.io/ripster/