kurmann-plex-downloader 2.0.0

CLI Tool zum Downloaden von Original-Dateien aus Plex

Plex Downloader CLI

Ein modernes Kommandozeilen-Tool (CLI), um Filme und TV Shows von einem Plex-Server in Originalqualität (Direct Stream) herunterzuladen.

Entwickelt von Patrick Kurmann mit Python, Typer und Rich.

Features

• Neueste Inhalte: Zeige die 12 neuesten Filme oder TV-Serien an, die deiner Plex-Bibliothek hinzugefügt wurden.
• Interaktive Suche: Suche blitzschnell nach Filmen und TV Shows in deinen Plex-Bibliotheken.
• TV Show Support: Lade ganze Serien, einzelne Episoden oder alle Episoden ab einer bestimmten Episode bis zum Ende der Staffel herunter.
• Geplanter Download: Plane Downloads für 2 Uhr morgens direkt im interaktiven Ablauf.
• Medienserver-Integration: Automatisches Verschieben von Downloads zum Medienserver (lokal oder per rclone zu NAS/Cloud).
• Originalqualität: Lädt die rohe Videodatei (z. B. MKV, MP4) herunter, ohne Transcodierung oder Qualitätsverlust.
• Schicke UI: Fortschrittsbalken, farbige Ausgaben und formatierte Tabellen.
• Sicherer Login: Verbindet sich mit deinen Plex-Zugangsdaten und nutzt Tokens zur Authentifizierung.
• Konfigurierbar: Speichert deine Einstellungen (Server, Token, Pfad) lokal ab.

Installation

Option 1: Installation via PyPI (Empfohlen)

pipx install kurmann-plex-downloader

Oder mit pip in einer virtuellen Umgebung:

pip install kurmann-plex-downloader

Option 2: Installation via pipx aus GitHub

pipx install git+https://github.com/kurmann/plex-downloader.git

Option 3: Lokale Entwicklung

Wenn du den Code verändern oder erweitern möchtest:

1. Repository klonen:

git clone https://github.com/kurmann/plex-downloader.git
cd plex-downloader

2. Abhängigkeiten installieren (empfohlen: uv):

uv sync

Oder mit pip:

pip install -e ".[dev]"

Benutzung

Sobald das Tool installiert ist, steht dir der Befehl plex-dl systemweit zur Verfügung.

1. Ersteinrichtung (Konfiguration)

Bevor du starten kannst, musst du dich einmalig einloggen und den gewünschten Server auswählen.

plex-dl init

Folge den Anweisungen im Terminal, um dich bei plex.tv einzuloggen und deinen Server zu wählen.

Hinweis: init ist für die Ersteinrichtung gedacht. Um einzelne Einstellungen (Server, Download-Pfad) anzupassen, nutze config set:

plex-dl config set server_name "Neuer Server"
plex-dl config set download_path ~/Downloads

2. Interaktiven Auswahl- und Download-Flow starten

Starte den interaktiven Flow explizit mit dem select-Unterbefehl:

plex-dl select

Im Hauptmenü kannst du:

• Option 1: Nach Filmen oder TV-Serien suchen
• Option 2: Die 12 neuesten Filme anzeigen
• Option 3: Die 12 neuesten TV-Serien anzeigen

Nach der Anzeige der Liste kannst du einen Film oder eine Serie auswählen, in die Warteschlange legen und herunterladen.

Hinweis: plex-dl ohne Unterbefehl zeigt nur die Hilfe an. Die interaktive Sitzung muss explizit mit plex-dl select gestartet werden.

3. Suchen & Herunterladen

Starte plex-dl select und wähle im Hauptmenü Option 1, dann gib einen Film- oder Serientitel ein. Das Tool zeigt dir alle Treffer an und lässt dich auswählen, welchen du laden möchtest.

Für TV Shows wirst du gefragt, ob du die ganze Serie, nur eine bestimmte Episode oder alle Episoden ab einer bestimmten Episode bis zum Ende der Staffel herunterladen möchtest.

Geplanter Download (Nachtmodus)

Nach der Auswahl des gewünschten Inhalts wirst du interaktiv gefragt, ob der Download sofort oder um 2 Uhr morgens starten soll:

Wann möchtest du den Download starten?
1. Jetzt sofort
2. Um 2:00 Uhr morgens

Im Nachtmodus (Option 2):

• Wartet die Anwendung aktiv bis 2 Uhr morgens
• Zeigt die verbleibende Wartezeit alle 60 Sekunden an
• Führt den Download automatisch um 2 Uhr aus

Beispiel:

# Interaktiven Flow starten und im Menü suchen
plex-dl select

# Nach der Auswahl des Inhalts wirst du gefragt:
# "Wann möchtest du den Download starten?"
# 1. Jetzt sofort
# 2. Um 2:00 Uhr morgens

4. Medienserver-Integration

Bei der Erstkonfiguration (plex-dl init) kannst du ein oder mehrere Download-Ziele konfigurieren. Nach jedem erfolgreichen Download werden die Dateien automatisch in das gewählte Ziel verschoben.

Beispiele:

• Lokaler Pfad: /mnt/media oder ~/Media
• rclone Remote: mynas:media/plex (für NAS oder Cloud-Speicher)

Vorteile:

• Automatische Organisation der Medienbibliothek
• Bei Serien wird jede Episode sofort nach Download verschoben → Platz wird für die nächste Episode frei
• Unterstützt sowohl lokale als auch Remote-Ziele via rclone

Hinweis: Falls rclone nicht installiert ist, erfolgt bei lokalen Pfaden ein automatischer Fallback auf Python's Standardmethoden.

Konfiguration

Die Konfigurationsdatei wird standardmäßig hier gespeichert: ~/.config/plex-downloader/config.toml

Konfigurationswerte werden über dedizierte Unterbefehle gelesen und geschrieben:

# Wert setzen
plex-dl config set token <dein-plex-token>
plex-dl config set server_name "Mein Plex Server"
plex-dl config set download_path ~/Downloads/plex

# Einzelnen Wert abfragen
plex-dl config get server_name

# Alle Werte anzeigen
plex-dl config list

Unterstützte Konfigurationsschlüssel:

Schlüssel	Beschreibung
token	Plex Authentifizierungs-Token
server_name	Name deines Plex-Servers
download_path	Temporäres Verzeichnis für Downloads
targets	Liste von Zielverzeichnissen (via plex-dl init)

Hinweis: targets (Zielverzeichnisse) werden über plex-dl init oder die interaktive Erstkonfiguration gepflegt, da es sich um eine Liste von Objekten handelt.

Projektstruktur

Dieses Projekt nutzt das moderne src-Layout für Python-Pakete:

plex-downloader/
├── pyproject.toml       # Abhängigkeiten & Entry Point
├── src/
│   └── plex_downloader/
│       ├── __init__.py
│       ├── main.py      # Kompatibilitäts-Layer (Re-Exporte)
│       ├── core/
│       │   └── config.py         # Konfigurationsmanagement (reine I/O-Funktionen)
│       ├── api/
│       │   ├── models.py         # Request/Result-Datenmodelle
│       │   └── facade.py         # Öffentliche API-Fassade
│       ├── services/
│       │   └── plex_service.py   # Plex-Server-Verbindung
│       ├── cli/
│       │   ├── app.py            # Typer-CLI (Subcommands: init, config, select)
│       │   └── interactive.py    # Interaktive Sitzungslogik
│       └── modules/
│           ├── downloader.py     # Download-Logik
│           ├── rclone_mover.py   # Medienserver-Integration
│           └── cleanup.py        # Temporäre Dateien bereinigen

Änderungsverlauf

Unveröffentlicht

• Konfigurationsformat von YAML auf TOML umgestellt (config.toml)
• Neue Unterbefehle config set, config get, config list für nicht-interaktive Konfigurationsverwaltung
• Automatische Migration von config.yaml nach config.toml beim ersten Start

2.0.0 – 2026-03-13

• Geschichtete Architektur eingeführt (core/, api/, cli/, services/)
• Neuer Unterbefehl init für die Erstkonfiguration
• Neuer Unterbefehl select für den interaktiven Download-Flow
• plex-dl ohne Unterbefehl zeigt jetzt die Hilfe an
• PyPI-Distribution als kurmann-plex-downloader vorbereitet

1.4 – 2026-02-17

• Edition-Spalte wird ausgeblendet, wenn keine Editionen vorhanden sind
• Emby-Namenskonvention für Verzeichnis- und Dateinamen
• Bis zu 10 Suchergebnisse (vorher 5)

1.3 – 2026-02-09

• Download-Dauer und Dateigrösse werden angezeigt
• Persistente Warteschlange über Suche und Listenansicht
• Mehrere Download-Ziele konfigurierbar

Vollständige Historie: CHANGELOG.md

Lizenz

Dieses Projekt ist unter der MIT Lizenz veröffentlicht. Siehe LICENSE für Details.

Haftungsausschluss

Dieses Tool ist nur für den persönlichen Gebrauch gedacht. Bitte respektiere das Urheberrecht und lade nur Inhalte herunter, an denen du die Rechte besitzt oder auf die du legitimen Zugriff hast.