derbarnimer/unraid-video-preloader
🎬 Smart video preloading for Plex & Jellyfin - Eliminates buffering by caching videos in RAM
2.0K
derbarnimer/unraid-video-preloader repository overview
🎬 Unraid Video Preloader
Smart video caching for Plex & Jellyfin | Intelligentes Video-Caching für Plex & Jellyfin
🇬🇧 English
What is this?
Unraid Video Preloader is a Docker application that intelligently preloads video files into RAM cache. This eliminates buffering when starting videos on Plex, Jellyfin, or other media servers.
✨ Features
- Smart Preloading - Loads beginning and end of video files into cache
- Tautulli Integration - Preloads most-watched movies and next episodes of currently watching series
- Live Monitoring - Automatically caches next episodes when someone is watching a series
- Plex Integration - Preloads "On Deck" / Continue Watching content
- Auto-Scheduler - Cron-based automatic preloading
- Time Profiles - Different preload sizes for day/evening/night
- Web Interface - Beautiful UI for configuration and monitoring
- Plex Webhooks - React to play events in real-time
- RAM Protection - Automatically stops when RAM usage is high
- Multi-Language - Full English and German interface support
- Path Mappings - Configure path translations between Plex and container
🚀 Quick Start
# docker-compose.yml
services:
video-preloader:
image: derbarnimer/unraid-video-preloader:latest
container_name: video-preloader
restart: unless-stopped
cap_add:
- SYS_PTRACE
ports:
- "8080:8000"
volumes:
- ./config:/config
- /mnt/user:/data:ro # Your media library (read-only)
environment:
- TZ=Europe/Berlin
docker-compose up -d
Then open http://YOUR_IP:8080 in your browser.
⚙️ Configuration
All settings are available in the web interface:
| Setting | Description |
|---|---|
| Video Paths | Directories to scan (e.g., /data/movies, /data/tv) |
| Priority Paths | Loaded first (e.g., /data/tv/Currently Watching) |
| Exclude Patterns | Skip files matching pattern (e.g., */Samples/*) |
| Preload Size | MB to load from start/end of files |
| Max RAM Usage | Stop preloading above this percentage |
| Scheduler | Cron expression for automatic runs |
| Tautulli | URL and API key for integration |
| Live Monitoring | Auto-cache next episodes during playback |
| Plex | URL and token for On Deck feature |
📡 Live Monitoring
When enabled, the preloader monitors active Tautulli streams every 60 seconds. If someone is watching a series episode, the next 3 episodes are automatically cached. This ensures seamless playback when binge-watching!
| Setting | Description |
|---|---|
| Check Interval | How often to check for active streams (default: 60s) |
| Episodes to Preload | Number of next episodes to cache (default: 3) |
🔌 API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/api/stats | GET | Current status and RAM usage |
/api/logs | GET | Last 20 log lines |
/api/history | GET | Preload run history |
/api/preload | POST | Preload a single file |
/api/cache-status | GET | Check if file is cached |
/api/webhook/plex | POST | Receive Plex webhooks |
/api/test-tautulli | GET | Test Tautulli connection |
/api/test-plex | GET | Test Plex connection |
/api/test-live-monitoring | GET | Test live monitoring detection |
/api/set-language | GET | Switch UI language (en/de) |
📡 Plex Webhook Setup
- Go to Plex → Settings → Webhooks
- Add:
http://YOUR_PRELOADER_IP:8080/api/webhook/plex - The preloader will now react to play events
🇩🇪 Deutsch
Was ist das?
Unraid Video Preloader ist eine Docker-Anwendung, die Video-Dateien intelligent in den RAM-Cache lädt. Das eliminiert Buffering beim Starten von Videos auf Plex, Jellyfin oder anderen Media-Servern.
✨ Features
- Intelligentes Preloading - Lädt Anfang und Ende von Video-Dateien in den Cache
- Tautulli-Integration - Preloadet meistgesehene Filme und nächste Folgen aktueller Serien
- Live-Monitoring - Cached automatisch nächste Episoden wenn jemand eine Serie schaut
- Plex-Integration - Preloadet "On Deck" / Weiterschauen-Inhalte
- Auto-Scheduler - Cron-basiertes automatisches Preloading
- Zeit-Profile - Unterschiedliche Preload-Größen für Tag/Abend/Nacht
- Web-Interface - Schöne UI für Konfiguration und Monitoring
- Plex Webhooks - Reagiert in Echtzeit auf Wiedergabe-Events
- RAM-Schutz - Stoppt automatisch bei hoher RAM-Auslastung
- Mehrsprachig - Vollständige Deutsch/Englisch-Unterstützung
- Pfad-Mappings - Pfadübersetzung zwischen Plex und Container konfigurieren
🚀 Schnellstart
# docker-compose.yml
services:
video-preloader:
image: derbarnimer/unraid-video-preloader:latest
container_name: video-preloader
restart: unless-stopped
cap_add:
- SYS_PTRACE
ports:
- "8080:8000"
volumes:
- ./config:/config
- /mnt/user:/data:ro # Deine Medienbibliothek (nur lesen)
environment:
- TZ=Europe/Berlin
docker-compose up -d
Dann öffne http://DEINE_IP:8080 im Browser.
⚙️ Konfiguration
Alle Einstellungen sind im Web-Interface verfügbar:
| Einstellung | Beschreibung |
|---|---|
| Video-Pfade | Verzeichnisse zum Scannen (z.B. /data/movies, /data/tv) |
| Prioritäts-Pfade | Werden zuerst geladen (z.B. /data/tv/Aktuell) |
| Exclude-Patterns | Dateien überspringen (z.B. */Samples/*) |
| Preload-Größe | MB vom Anfang/Ende der Dateien laden |
| Max RAM-Nutzung | Preloading stoppen über diesem Prozentsatz |
| Scheduler | Cron-Ausdruck für automatische Durchläufe |
| Tautulli | URL und API-Key für Integration |
| Live-Monitoring | Automatisches Caching während Wiedergabe |
| Plex | URL und Token für On Deck Feature |
📡 Live-Monitoring
Wenn aktiviert, prüft der Preloader alle 60 Sekunden aktive Tautulli-Streams. Wenn jemand eine Serien-Episode schaut, werden automatisch die nächsten 3 Episoden gecacht. Das sorgt für nahtloses Binge-Watching!
| Einstellung | Beschreibung |
|---|---|
| Prüf-Intervall | Wie oft nach aktiven Streams geprüft wird (Standard: 60s) |
| Episoden zum Vorladen | Anzahl der nächsten Episoden zum Cachen (Standard: 3) |
🔌 API-Endpunkte
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/api/stats | GET | Aktueller Status und RAM-Nutzung |
/api/logs | GET | Letzte 20 Log-Zeilen |
/api/history | GET | Preload-Verlauf |
/api/preload | POST | Einzelne Datei preloaden |
/api/cache-status | GET | Prüfen ob Datei gecacht ist |
/api/webhook/plex | POST | Plex-Webhooks empfangen |
/api/test-tautulli | GET | Tautulli-Verbindung testen |
/api/test-plex | GET | Plex-Verbindung testen |
/api/test-live-monitoring | GET | Live-Monitoring-Erkennung testen |
/api/set-language | GET | UI-Sprache wechseln (en/de) |
📡 Plex Webhook einrichten
- Gehe zu Plex → Einstellungen → Webhooks
- Hinzufügen:
http://PRELOADER_IP:8080/api/webhook/plex - Der Preloader reagiert nun auf Wiedergabe-Events
📸 Screenshots
Screenshots coming soon / Screenshots folgen
🛠️ Development
# Clone
git clone https://github.com/hoktaar/unraid-video-preloader.git
cd unraid-video-preloader
# Run locally
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
📄 License / Lizenz
MIT License - see LICENSE
Tag summary
Content type
Image
Digest
sha256:24aff82ae…
Size
145.6 MB
Last updated
11 months ago
docker pull derbarnimer/unraid-video-preloader