ripster/README.md

Ripster

Ripster ist eine lokale Web-Anwendung für halbautomatisches Disc-Ripping mit MakeMKV + HandBrake inklusive Metadaten-Auswahl, Titel-/Spurprüfung und Job-Historie.

---

Neu seit letztem Release

• Profil-spezifische Einstellungen – Separate Konfiguration für Blu-ray und DVD: eigene Pfade, HandBrake-Presets, Rip-Modi, Extra-Args, Dateinamen-Templates; automatische Auflösung anhand des erkannten Medientyps
• Cron-Job-System – Skripte und Skript-Ketten zeitgesteuert ausführen; eigener Expression-Parser, Ausführungs-Logs, manuelle Auslösung, PushOver-Integration pro Job
• User-Presets – benannte HandBrake-Preset-Sammlungen (Preset + Extra-Args) pro Medientyp anlegen und im Review-Panel auswählen
• DVD-/Blu-ray-Erkennung verbessert – robuste Media-Profil-Erkennung aus UDF/ISO9660-Dateisystemtyp, Laufwerk-Modell und Disc-Label; Medientyp-Indikator in der UI
• Pre-Encode-Ausführungen – Skripte und Ketten können nun auch vor dem Encode-Schritt ausgeführt werden (zusätzlich zu Post-Encode)
• Sortierbare Skripte & Ketten – Reihenfolge über Drag & Drop festlegen; wird persistent gespeichert
• Granulares PushOver – je Event konfigurierbar (Metadaten bereit, Rip-Start, Encode-Start, Fertig, Fehler, Abbruch, Re-Encode)
• rip_successful-Flag in Jobs – separates Feld zur Nachverfolgung ob der Rip-Schritt abgeschlossen wurde (unabhängig vom Encode-Status)
• handbrake_restart_delete_incomplete_output – unvollständige Ausgabe wird beim Encode-Neustart automatisch gelöscht

---

Was Ripster kann

• Disc-Erkennung mit Pipeline-Status in Echtzeit (WebSocket)
• Robuste Erkennung von Blu-ray, DVD und CD (UDF/ISO9660-Heuristik + Laufwerk-Modell)
• Metadaten-Suche und Zuordnung über OMDb
• MakeMKV-Analyse und Rip (MKV oder Backup-Modus)
• HandBrake-Encode mit Preset + Extra-Args + Track-Override
• Manuelle Playlist-/Titel-Auswahl bei komplexen Blu-rays
• Pre- und Post-Encode-Skripte & Skript-Ketten (inkl. Drag-and-Drop-Sortierung)
• Cron-Jobs: Skripte und Ketten zeitgesteuert ausführen (eigener Expression-Parser, Logs, PushOver)
• Historie mit Re-Encode, Löschfunktionen und Detailansicht
• Dateibasierte Logs (Backend + Job-Prozesslogs)

Tech-Stack

• Backend: Node.js, Express, SQLite, WebSocket (ws)
• Frontend: React, Vite, PrimeReact
• Externe Tools: makemkvcon, HandBrakeCLI, mediainfo

Voraussetzungen

• Linux-System mit optischem Laufwerk (oder gemountete Quelle)
• Node.js >= 20.19.0 (siehe .nvmrc)
• Installierte CLI-Tools im PATH:
  • makemkvcon
  • HandBrakeCLI
  • mediainfo

Schnellstart

./start.sh

start.sh erledigt:

1. Node-Version prüfen/umschalten (inkl. nvm/node@20-Fallback)
2. Dependencies installieren (Root, Backend, Frontend)
3. Dev-Umgebung starten (backend + frontend)

Danach:

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001/api

Stoppen:

./kill.sh

Manueller Start

npm install
npm --prefix backend install
npm --prefix frontend install
npm run dev

Einzeln starten:

npm run dev:backend
npm run dev:frontend

Frontend Build:

npm run build:frontend

Backend (ohne Dev-Mode):

npm run start

Konfiguration

1) UI-Settings (empfohlen)

Die meisten Einstellungen werden in der App unter Settings gepflegt und in SQLite gespeichert:

• Pfade: raw_dir, movie_dir, log_dir
• Tools: makemkv_command, handbrake_command, mediainfo_command
• Encode: handbrake_preset, handbrake_extra_args, output_extension, filename_template
• Laufwerk/Scan: drive_mode, drive_device, Polling
• Benachrichtigungen: PushOver

2) Umgebungsvariablen

Backend (backend/src/config.js):

• PORT (Default: 3001)
• DB_PATH (Default: backend/data/ripster.db)
• LOG_DIR (Fallback-Logpfad, Default: backend/logs)
• CORS_ORIGIN (Default: *)
• LOG_LEVEL (debug|info|warn|error, Default: info)

Frontend (Vite):

• VITE_API_BASE (Default: /api)
• VITE_WS_URL (optional, überschreibt automatische WS-URL)
• VITE_PUBLIC_ORIGIN, VITE_ALLOWED_HOSTS, VITE_HMR_* (Remote-Dev/HMR)

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 (inkl. Job-/Settings-Daten)

Hinweis: Beim DB-Init wird das Schema gegen die Soll-Struktur abgeglichen und migriert.

Projektstruktur

ripster/
  backend/
    src/
      routes/
      services/
      db/
      utils/
  frontend/
    src/
      pages/
      components/
      api/
  start.sh
  kill.sh
  deploy-ripster.sh

API-Überblick

Pipeline

• GET /api/pipeline/state
• POST /api/pipeline/analyze
• POST /api/pipeline/start/:jobId
• POST /api/pipeline/confirm-encode/:jobId

History

• GET /api/history
• GET /api/history/:id

Settings

• GET /api/settings
• PUT /api/settings

Cron-Jobs (neu)

• 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

Troubleshooting

• WebSocket verbindet nicht:
  • prüfen, ob Frontend über Vite-Proxy läuft (/ws -> Backend)
  • bei Reverse-Proxy VITE_PUBLIC_ORIGIN/HMR korrekt setzen
• Keine Disc erkannt:
  • drive_mode=explicit testen und drive_device setzen (z. B. /dev/sr0)
• HandBrake/MakeMKV Fehler:
  • CLI-Binaries im PATH prüfen
  • Preset-Name exakt wie in HandBrakeCLI -z hinterlegen
• Startfehler wegen Schema:
  • sicherstellen, dass die erwartete Schema-Datei vorhanden ist (db/schema.sql)

Sicherheit

• Keine echten Tokens/Passwörter ins Repository committen.
• Lokale Secrets in .env oder in Settings pflegen, aber nicht versionieren.