kurmann-plex-downloader 2.2.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.
• Unattended Filmsuche: Suche per Titel nach Filmen und erhalte strukturierte Treffer mit Rating-Key, Titel und Jahr – ohne interaktive Rückfragen.
• Unattended Film-Download: Lade einen Film direkt per Titel herunter, ohne interaktive Rückfragen – skriptbar und automatisierbar. Unterstützt auch geplante Nacht-Downloads via --night.
• 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. Unattended Film-Download (neu in 2.1.0)

Der Befehl movie download-first lädt das erste Suchresultat für einen Filmtitel direkt herunter – ohne interaktive Rückfragen. Er eignet sich ideal für Skripte und automatisierte Abläufe.

plex-dl movie download-first "Inception"

Verhalten:

1. Verbindet sich mit dem konfigurierten Plex-Server.
2. Sucht in den Film-Bibliotheken nach dem angegebenen Titel.
3. Wählt das erste Suchresultat aus.
4. Lädt den Film herunter.
5. Existierende Dateien werden stillschweigend übersprungen (kein Prompt).

Ausgabe:

• Ergebnisdaten auf stdout, z. B.: downloaded: Inception (2010)
• Fehler- und Diagnosemeldungen auf stderr

Exit-Codes:

Code	Bedeutung
0	Download erfolgreich
1	Kein Treffer oder Download fehlgeschlagen
2	Fehlende oder ungültige Konfiguration

Optionen:

# Anderen Download-Pfad angeben
plex-dl movie download-first "The Matrix" --download-path ~/Downloads

# Download auf 2 Uhr morgens verschieben (unattended, kein Prompt)
plex-dl movie download-first "War Machine" --night

# Hilfe anzeigen
plex-dl movie download-first --help

Nachtmodus (--night):

Mit dem Flag --night wird der Download bis 2 Uhr morgens verzögert – vollständig unattended und ohne interaktive Rückfragen. Die Statusmeldungen erscheinen auf stderr:

Geplanter Nacht-Download um 2:00 Uhr
Aktuelle Zeit: 22:15:00
Zielzeit: 14.03.2026 02:00:00
Wartezeit: 3 Stunden, 44 Minuten
Warte bis 2 Uhr morgens … (Ctrl+C zum Abbrechen)

Hinweis: download-first ist eine Convenience-Funktion und wählt bewusst das erste Suchresultat. Für deterministischen Download per eindeutiger ID ist movie download --rating-key <id> als spätere Erweiterung geplant.

4. Unattended Filmsuche (neu in 2.2.0)

Der Befehl movie search sucht nach Filmen in den Plex-Bibliotheken und zeigt die Treffer als Tabelle an – ohne Download. Er eignet sich ideal als Grundlage für spätere Skripte, die gezielt per Rating-Key herunterladen wollen.

plex-dl movie search "Dune"

Erwartete Ausgabe:

                 Suchergebnisse für 'Dune'
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━┓
┃ Rating-Key ┃ Titel              ┃ Jahr ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━┩
│ 123456     │ Dune               │ 2021 │
│ 123789     │ Dune: Part Two     │ 2024 │
│ 124000     │ Dune               │ 1984 │
└────────────┴────────────────────┴──────┘

Verhalten:

1. Verbindet sich mit dem konfigurierten Plex-Server.
2. Sucht in den Film-Bibliotheken nach dem angegebenen Titel.
3. Zeigt alle Treffer als Tabelle an – ohne Download.
4. Der Rating-Key kann für spätere deterministische Downloads per movie download --rating-key verwendet werden.

Ausgabe:

• Ergebnistabelle auf stdout
• Fehler- und Diagnosemeldungen auf stderr

Exit-Codes:

Code	Bedeutung
0	Suche erfolgreich (auch bei 0 Treffern)
1	Allgemeiner Fehler (z. B. Verbindungsfehler)
2	Fehlende oder ungültige Konfiguration

Optionen:

# Anzahl Treffer begrenzen
plex-dl movie search "Dune" --limit 5

# Hilfe anzeigen
plex-dl movie search --help

5. Suchen & Herunterladen (interaktiv)

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)
│       │   └── scheduler.py      # Zeitplanungslogik (Nacht-Download-Berechnung)
│       ├── 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, movie)
│       │   ├── movie.py          # Unterbefehlsgruppe 'movie' (download-first, search, …)
│       │   └── interactive.py    # Interaktive Sitzungslogik
│       └── modules/
│           ├── downloader.py     # Download-Logik
│           ├── rclone_mover.py   # Medienserver-Integration
│           └── cleanup.py        # Temporäre Dateien bereinigen

Änderungsverlauf

2.2.0 – 2026-03-13

• Neuer unattended CLI-Befehl plex-dl movie search "<titel>" für die Filmsuche ohne Download
• Suchergebnisse enthalten Rating-Key, Titel und Jahr – als Grundlage für spätere deterministische Downloads
• --limit-Option für die Suche (Standard: 10 Treffer)
• Öffentliche API-Methode search_movies() als stabiler Einstiegspunkt dokumentiert und genutzt

2.1.0 – 2026-03-13

• Neuer unattended CLI-Befehl plex-dl movie download-first "<titel>" für den direkten Film-Download per Titel ohne interaktive Rückfragen
• Neuer --night-Flag: verschiebt den Download unattended bis 2 Uhr morgens (vollständig skriptbar)
• Neue movie-Unterbefehlsgruppe als Grundlage für spätere Befehle (movie search, movie download --rating-key)
• Neue öffentliche API-Methoden search_movies() und download_first_movie_by_title() in der API-Fassade
• Neues Modell MediaMatch für typisierte Suchresultate ohne rohe Plex-Objekte in der öffentlichen API
• Neues Modul core/scheduler.py mit wiederverwendbarer Zeitplanungslogik für Nacht-Downloads
• download_video() unterstützt jetzt skip_existing=True für den unattended Pfad ohne interaktiven Prompt

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
• 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

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.