yt-upload ist eine Python- und Docker-basierte Automatisierungslösung zur ereignisbasierten Überwachung von Video-Verzeichnissen und zum automatischen Upload auf YouTube via native REST API v3, FFmpeg und inotify.
Das Tool verarbeitet eingehende Videodateien, extrahiert eingebettete Metadaten sowie Cover-Thumbnails, zerlegt Videos bei Bedarf verlustfrei in Segmente (z. B. bei Dateien > 10 Stunden) und ordnet sie dynamisch Playlists zu.
- Direkte HTTP REST API v3: Native Implementierung für Resumable Chunk-Uploads ohne schwerfällige externe API-Wrapper.
- Inotify-Ordnerüberwachung: Überwacht
IN_DIRim Dämon-Modus (-D) in Echtzeit auf Dateiveränderungen (.mp4,.mkv,.mov,.m4v,.webm) über einen eigenen, abhängigkeitsfreien ctypes-Wrapper (Linux und FreeBSD ≥ 14.5), inklusive Polling-Fallback auf Systemen ohne inotify. - Drei flexible Betriebsmodi:
- Dämon-Modus (
-D/--daemon): Dauerhafter Hintergrunddienst zur automatischen Überwachung. - Auto-Batch (
-a/--auto): Einmaliges Abarbeiten eines Verzeichnisses mit anschließendem Beenden. - Manuell (CLI): Upload einzelner Videodateien mit voller Parameterkontrolle.
- Dämon-Modus (
- Metadaten- & Thumbnail-Extraktion: Liest Titel, Beschreibung, PURL, Genre, Aufnahmedatum und Artist via
ffprobeaus. Extrahiert automatisch Thumbnails aus MKV-Attachments (JPEG, PNG und WebP, z. B. vonyt-dlp --embed-thumbnail), MP4-Covern oder generiert ein Frame-Thumbnail. - Verlustfreies FFmpeg-Splitting: Zertrennt Videos mit einer Laufzeit von über 10 Stunden (36.000 Sekunden) automatisch und ohne Qualitätsverlust (
-c copy) in durchnummerierte Segmente. - Dynamische Playlist-Verwaltung: Erstellt und verknüpft Ziel-Playlists automatisch (z. B. auf Basis des
ARTIST-Tags viaENABLE_DYNAMIC_PLAYLISTS). - Erzwungen privat pro Artist: Videos bestimmter Artists (
ARTIST-Tag, z. B. Twitch-Kanal von tw-recorder) werden über die Sektion[force_private]bzw.FORCE_PRIVATE_ARTISTSimmer alsprivatehochgeladen, etwa um sie vor der Freigabe in YouTube Studio ab 18 einzustufen (per API nicht möglich). - Robustes Retry & Health-Check: Prüft Videodateien vor dem Upload auf unvollständige Schreibvorgänge / fehlende
moov-Atome. Bereits erfolgreich hochgeladene Segmente werden bei einem Fehler im nächsten Segment nicht erneut hochgeladen (Fortschritt wird pro Datei persistiert) - fehlgeschlagene Jobs mit Teilfortschritt oder einem reinen API-Kontingent-Limit (quotaExceeded) landen inRETRY_DIR, komplett fehlerhafte inCORRUPT_DIR. Ein optionaleryt-upload-retry.timer(siehe unten) verschiebtRETRY_DIR-Inhalte periodisch automatisch zurück nachIN_DIR. - Aufräumen von
DONE_DIR: Ein optionaleryt-upload-purge.timer(yt-upload --purge-done) löscht hochgeladene Originale, sobald sie länger alsdone_retention_days(Standard 7 Tage) inDONE_DIRliegen.CORRUPT_DIR/RETRY_DIRbleiben unangetastet.
Eine Übersicht der internen Architektur (Module, Datenfluss, Diagramm) findet sich in ARCHITECTURE.md.
Erstelle die benötigten Ordnerstrukturen auf deinem Host-System:
mkdir -p videos/in videos/work videos/done videos/corrupt videos/retry log oauth etc/yt-upload/conf.dHinterlege deine Google OAuth Secrets unter oauth/client_secrets.json. Eine Beispielvorlage für die Datei:
{
"installed": {
"client_id": "DEINE_CLIENT_ID.apps.googleusercontent.com",
"project_id": "DEIN_PROJECT_ID",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_secret": "DEIN_CLIENT_SECRET",
"redirect_uris": ["http://localhost"]
}
}Am einfachsten musst du die Platzhalter gar nicht von Hand ersetzen: Die Google Cloud Console bietet genau diese Datei fertig zum Download an (Schritte unten). Die Werte bedeuten:
| Platzhalter | Was es ist | Wo du es findest |
|---|---|---|
DEINE_CLIENT_ID |
Die öffentliche Kennung deines OAuth-Clients. Der vollständige Wert endet immer auf .apps.googleusercontent.com (z. B. 123456789012-abc…xyz.apps.googleusercontent.com) - diesen Teil also nicht doppelt anhängen. |
Google Auth Platform → Clients (bzw. APIs & Dienste → Anmeldedaten), Spalte „Client-ID“ deines Desktop-Clients |
DEIN_PROJECT_ID |
Die ID deines Google-Cloud-Projekts (z. B. yt-upload-123456), nicht der Anzeigename. Rein informativ: get-token und yt-upload lesen das Feld nicht aus, es darf also auch fehlen. |
Projektauswahl oben in der Console bzw. IAM & Verwaltung → Einstellungen |
DEIN_CLIENT_SECRET |
Das Geheimnis zum OAuth-Client (beginnt meist mit GOCSPX-). Damit tauscht get-token den Login-Code gegen den Refresh-Token und yt-upload später den Refresh-Token gegen kurzlebige Access-Tokens. |
Wird beim Anlegen des Clients angezeigt und steckt in der heruntergeladenen JSON-Datei. Neuere Clients zeigen das Secret danach nicht mehr vollständig an - dann unter dem Client ein neues Secret hinzufügen. |
Die übrigen Felder (auth_uri, token_uri, auth_provider_x509_cert_url, redirect_uris) sind für alle Nutzer gleich und bleiben wie in der Vorlage.
Einmalige Einrichtung in der Google Cloud Console:
- Projekt anlegen oder ein vorhandenes auswählen.
- Unter APIs & Dienste → Bibliothek die YouTube Data API v3 aktivieren.
- Unter Google Auth Platform (früher OAuth-Zustimmungsbildschirm) die App einrichten: Zielgruppe Extern, App-Name und Support-Mail eintragen. Solange die App im Status Testen ist, das Google-Konto des YouTube-Kanals als Testnutzer hinzufügen - Achtung: im Testmodus läuft der Refresh-Token nach 7 Tagen ab und
get-tokenmuss neu laufen. Für Dauerbetrieb die App auf In Produktion stellen (für die private Nutzung genügt das ohne Google-Verifizierung; beim Login erscheint dann einmalig der Hinweis „Google hat diese App nicht überprüft“, den du über Erweitert → Weiter zu … bestätigst). - Unter Clients (bzw. Anmeldedaten → Anmeldedaten erstellen → OAuth-Client-ID) einen Client vom Typ Desktop-App anlegen. Nicht „Webanwendung“: Nur Desktop-Clients akzeptieren den Redirect auf
http://localhost, denget-tokenverwendet, ohne dass du Redirect-URIs eintragen musst. - Direkt im Anschluss JSON herunterladen und als
client_secrets.jsonspeichern (Docker:oauth/client_secrets.json, Bare-Metal:/etc/yt-upload/client_secrets.json). Die Datei hat bereits das obige Format mit"installed": {…}.
Die Scopes (youtube.upload und youtube, letzterer für die Playlist-Verwaltung) fordert get-token selbst an; in der Console musst du dafür nichts eintragen. Die client_secrets.json gehört nicht in ein Git-Repo oder Image. Client-ID und Secret landen von get-token zusätzlich in der erzeugten Credentials-Datei, daher gilt der Schutz per systemd-creds (siehe unten) für beide.
Führe das mitgelieferte Authentifizierungsskript im Container aus:
docker run --rm -it \
-v $(pwd)/oauth:/app/oauth \
ghcr.io/chaos7x/yt-upload:latest /usr/local/bin/get_tokenStandardmäßig zeigt get-token/get_token einen Link an, den du im Browser öffnest; nach dem Login bricht die Seite ab (Seite nicht gefunden) - kopiere in dem Fall die komplette URL aus der Adresszeile zurück ins Terminal. Dieser Copy-Paste-Schritt ist bewusst der Standard, da er unabhängig davon funktioniert, ob get-token und dein Browser auf demselben Rechner laufen (z. B. Docker auf einem entfernten Server/NAS, Browser auf deinem PC).
Läuft get-token dagegen auf demselben Rechner wie dein Browser (z. B. Bare-Metal-Desktop-Nutzung, oder Docker mit explizit publiziertem Port 8080), kannst du den Redirect automatisch abfangen lassen und dir das Copy-Paste sparen:
OAUTH_LOCAL_SERVER=true get-tokenWelcher YouTube-Kanal? Den Ziel-Kanal bestimmt allein der Login in diesem Schritt, nicht die client_secrets.json: Client-ID, Project-ID und Secret identifizieren nur deine App (das Google-Cloud-Projekt). Melde dich mit dem Google-Konto an, dem der Kanal gehört; hat das Konto mehrere Kanäle (Brand-Accounts), fragt Google dabei, welcher verwendet werden soll. Der erzeugte Refresh-Token ist an genau diesen Kanal gebunden, alle Uploads und Playlists landen dort. Das Konto, dem das Cloud-Projekt gehört, darf ein anderes sein (im Testmodus muss das Kanal-Konto dann als Testnutzer eingetragen sein). Zum Kanalwechsel get-token einfach erneut ausführen und beim Login den anderen Kanal wählen.
docker run -d \
--name yt-upload \
--hostname yt-upload \
--restart unless-stopped \
--security-opt no-new-privileges:true \
-u "11107:11108" \
-e TZ=Europe/Berlin \
-e ENABLE_DYNAMIC_PLAYLISTS=true \
-e HOME=/tmp \
-v $(pwd)/oauth:/app/oauth:rw \
-v $(pwd)/yt-upload-data:/srv/media-pipeline:rw \
-v $(pwd)/log:/log:rw \
ghcr.io/chaos7x/yt-upload:latestservices:
yt-upload:
image: ghcr.io/chaos7x/yt-upload:${IMAGE_VERSION:-latest}
container_name: yt-upload
hostname: yt-upload
restart: unless-stopped
security_opt:
- no-new-privileges:true
user: "11107:11108"
environment:
- TZ=Europe/Berlin
- ENABLE_DYNAMIC_PLAYLISTS=true
- HOME=/tmp
- ENABLE_DESCRIPTION_CENSOR=true
- DESCRIPTION_BLACKLIST=onlyfans.com,fansly.com,loyalfans.com,manyvids.com,pornhub.com,chaturbate.com,stake.com,csgoroll.com,hellcase.com,1xbet.com,adf.ly,shorte.st
env_file:
- .env
volumes:
- oauth:/app/oauth
# Kompletter Datenzustand (incoming/work/done/corrupt/retry) in einem
# einzigen Bind-Mount direkt auf /srv/media-pipeline - trifft damit
# exakt den Code-Default, keine ENV-Umbiegung nötig. "incoming" ist
# der einzige Unterordner davon, in den auch fetchbridge hineinschreibt.
# Zeigt auf denselben gemeinsamen /srv/media-pipeline-Host-Baum
# wie tw-recorders und fetchbridges Compose-Dateien: fetchbridge
# braucht recordings/ UND incoming/ als EINEN gemeinsamen Mount, sonst
# scheitert dessen os.rename() zwischen beiden mit EXDEV (siehe
# fetchbridges docker-compose.yaml.example).
- yt-upload-data:/srv/media-pipeline
- log:/log
# Optional: eigene upload.conf statt der im Image mitgelieferten
# Beispielkonfiguration nutzen (einzelne Datei, kein ganzes Verzeichnis):
# - ./upload.conf:/etc/yt-upload/upload.conf:ro
tty: true
stdin_open: true
volumes:
oauth:
driver: local
driver_opts:
type: none
o: bind
device: "./oauth"
yt-upload-data:
driver: local
driver_opts:
type: none
o: bind
device: "/srv/media-pipeline"
log:
driver: local
driver_opts:
type: none
o: bind
device: "./log"user: "11107:11108" oben ist nur ein Platzhalter. yt-upload-data zeigt bereits auf denselben Host-Pfad /srv/media-pipeline, den auch die Bare-Metal-/.deb-Installationen von fetchbridge/tw-recorder nutzen - Container und Bare-Metal teilen sich den Baum also ohne weitere Anpassung (bei docker run entsprechend -v /srv/media-pipeline:/srv/media-pipeline:rw).
/srv/media-pipeline gehört dort root:media-pipeline mit Modus 2775 (setgid, bewusst ohne Sticky-Bit) - Schreib-/Löschrecht hängt also rein an der Gruppe, nicht an der UID oder dem Datei-Owner. Die GID im user:-Feld muss deshalb mit der echten Host-Gruppe übereinstimmen, sonst gibt's Permission denied:
getent group media-pipeline # z.B. media-pipeline:x:998:Die zweite Zahl in user: "<uid>:<gid>" durch diese echte GID ersetzen (z.B. user: "11107:998") - die UID (erste Zahl) ist frei wählbar, da sie für die Zugriffsrechte auf dieses Verzeichnis keine Rolle spielt.
Die systemd-Timer-/Cron-Lösung aus dem Bare-Metal-Abschnitt (siehe unten) greift in Docker nicht - der Container läuft als Single-Process ohne eigenen Cron/systemd. --requeue-retries selbst funktioniert aber unverändert, da es keinen Instanz-Lock braucht und daher problemlos neben dem bereits laufenden -D-Prozess im selben Container ausgeführt werden kann - die Terminierung übernimmt stattdessen der Docker-Host per docker exec in den laufenden Container hinein:
# Host-Crontab (crontab -e auf dem Docker-Host)
0 3 * * * docker exec yt-upload yt-upload --requeue-retriesNutzt der Host selbst systemd, geht das genauso als Timer (analog zu yt-upload-retry.timer, nur mit docker exec statt direktem Aufruf):
# /etc/systemd/system/yt-upload-retry-docker.service
[Unit]
Description=yt-upload (Docker) - Requeue liegen gebliebener Dateien aus RETRY_DIR
[Service]
Type=oneshot
ExecStart=/usr/bin/docker exec yt-upload yt-upload --requeue-retries# /etc/systemd/system/yt-upload-retry-docker.timer
[Unit]
Description=Periodischer Requeue liegen gebliebener Dateien aus RETRY_DIR (yt-upload, Docker)
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target(yt-upload im docker exec-Aufruf ist hier der container_name aus der Compose-Datei oben, nicht der Befehl - bei abweichendem Namen entsprechend anpassen.)
Auch das Aufräumen von DONE_DIR (--purge-done, Details im Bare-Metal-Abschnitt) läuft im Container nicht von selbst: der Container startet nur yt-upload -D, und der Dämon löscht bewusst nichts. Ohne einen der folgenden Aufrufe bleibt DONE_DIR also unverändert. Wie beim Retry startet der Docker-Host einen zweiten, kurzlebigen Prozess im laufenden Container (kein Instanz-Lock, läuft problemlos neben -D). Am Container bzw. an der docker-compose.yaml muss dafür nichts geändert werden; die Frist (DONE_RETENTION_DAYS, Standard 7, 0 = aus) gilt ohne weitere Angabe:
# Host-Crontab (crontab -e auf dem Docker-Host)
30 4 * * * docker exec yt-upload yt-upload --purge-doneOder als systemd-Timer auf dem Host:
# /etc/systemd/system/yt-upload-purge-docker.service
[Unit]
Description=yt-upload (Docker) - Loeschen alter Dateien aus DONE_DIR
[Service]
Type=oneshot
ExecStart=/usr/bin/docker exec yt-upload yt-upload --purge-done# /etc/systemd/system/yt-upload-purge-docker.timer
[Unit]
Description=Periodisches Loeschen alter Dateien aus DONE_DIR (yt-upload, Docker)
[Timer]
OnCalendar=daily
RandomizedDelaySec=1h
Persistent=true
[Install]
WantedBy=timers.targetsystemctl daemon-reload
systemctl enable --now yt-upload-purge-docker.timerEine abweichende Frist entweder dauerhaft per DONE_RETENTION_DAYS in environment/.env des Containers oder nur für diesen Aufruf: docker exec -e DONE_RETENTION_DAYS=14 yt-upload yt-upload --purge-done. Einmalig von Hand geht dasselbe jederzeit ohne Timer.
Wer die Terminierung lieber komplett in der docker-compose.yaml selbst abbilden will statt auf dem Host, kann einen Scheduler-Sidecar wie ofelia ergänzen, der per Labels denselben docker exec-Aufruf übernimmt:
services:
yt-upload:
# ... wie oben ...
labels:
ofelia.enabled: "true"
ofelia.job-exec.retry.schedule: "@daily"
ofelia.job-exec.retry.command: "yt-upload --requeue-retries"
ofelia.job-exec.purge.schedule: "@daily"
ofelia.job-exec.purge.command: "yt-upload --purge-done"
ofelia:
image: mcuadros/ofelia:latest
command: daemon --docker
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
depends_on:
- yt-upload
⚠️ Warnung: Das setzt Zugriff auf den Docker-Socket (/var/run/docker.sock) imofelia-Container voraus - wer den Socket kontrolliert, kann darüber jeden Container auf dem Host starten, stoppen und inspizieren, faktisch also Root-Rechte auf dem gesamten Host, nicht nur aufyt-upload. Selbst:ro(read-only) mountet nur die Socket-Datei schreibgeschützt, verhindert aber nicht, dass die Docker-API darüber beliebige neue, privilegierte Container starten kann. Für die meisten Setups ist der schlankere Host-Cron/-Timer von oben (kein zusätzlicher Container, kein Socket-Mount) deshalb die sicherere Wahl - dieser Weg ist nur für Umgebungen gedacht, die dieses Risiko bewusst eingehen wollen.
yt-upload läuft auch direkt auf dem Host, ganz ohne Container. Systemabhängigkeiten kommen bewusst über den jeweiligen Paketmanager statt über PyPI - pip installiert ausschließlich das eigene Package:
# System-Abhängigkeiten
apt install python3-pip python3-setuptools python3-requests ffmpeg
# (unter Alpine/anderen Distros entsprechend: apk add / dnf install ...)
cd /pfad/zu/yt-upload
pip install --break-system-packages --no-deps .Danach stehen die Befehle yt-upload und get-token systemweit zur Verfügung (yt-upload --version zum Testen). get-token führt denselben interaktiven OAuth-Flow wie im Docker-Setup (Schritt 3 oben) aus, liest client_secrets.json dabei aber standardmäßig von /etc/yt-upload/client_secrets.json (per CLIENT_SECRETS_FILE-Umgebungsvariable anpassbar) und schreibt die Credentials nach /etc/yt-upload/youtube-upload-credentials.json - derselbe Pfad, den auch der yt-upload-Dienst selbst als Standard erwartet (keine /app/oauth-Docker-Konvention auf Bare-Metal). Existiert bereits der dedizierte yt-upload-Systemuser (Dämon-Paket installiert), chownt get-token die Datei automatisch auf ihn, damit der Dämon sie lesen kann, auch wenn get-token selbst als root/Admin lief. Für ein Update genügt ein erneuter pip install ...-Aufruf im aktualisierten Repo-Verzeichnis.
Die Logdatei landet je nach Umgebung automatisch am sinnvollsten Ort (/var/log/yt-upload/, sofern beschreibbar und ein klassischer Syslog-Daemon läuft, sonst nur auf stdout/journald) - siehe LOG_FILE-Umgebungsvariable, falls ein fester Pfad gewünscht ist. Läuft ein Syslog-Daemon, rotiert die App die Datei bewusst nicht selbst (kein RotatingFileHandler) - das übernimmt das mitgelieferte /etc/logrotate.d/yt-upload (nur im .deb-Paket enthalten; bei einer reinen pip-Installation ohne .deb selbst einrichten, falls gewünscht). Nur bei explizit gesetztem LOG_FILE oder einem gemounteten Docker-/log-Volume rotiert die App eigenständig, da dort sonst niemand rotieren würde.
Jedes GitHub Release enthält zwei .deb-Anhänge, aufgeteilt nach Nutzung - keine manuelle pip-Installation nötig:
yt-upload_<version>_all.deb- CLI, Python-Package und Config (/etc/yt-upload/upload.conf). Reicht für den rein manuellen Datei-Modus (yt-upload video.mp4 ...) und Auto-Batch (-a).apt/dpkglöstpython3-requests/ffmpegautomatisch mit auf.yt-upload-daemon_<version>_all.deb- nur für den Dämon-Modus (-D) nötig: systemd-Service und dedizierter Systemuser (yt-upload). Hängt vonyt-uploadin exakt derselben Version ab, zieht es also automatisch mit.
Nur die CLI ohne Dämon-Overhead (Systemuser, nie aktivierter systemd-Service):
wget https://github.com/chaos7x/yt-upload/releases/latest/download/yt-upload_<version>_all.deb
apt install ./yt-upload_<version>_all.debFür den Dauerbetrieb zusätzlich das Daemon-Paket installieren (zieht yt-upload automatisch nach, falls noch nicht vorhanden):
wget https://github.com/chaos7x/yt-upload/releases/latest/download/yt-upload-daemon_<version>_all.deb
apt install ./yt-upload-daemon_<version>_all.debDas Daemon-Paket legt den Systemuser und den systemd-Service an, startet ihn aber bewusst nicht automatisch. IN_DIR/WORK_DIR/DONE_DIR/CORRUPT_DIR/RETRY_DIR zeigen automatisch einheitlich (Docker wie Bare-Metal) auf /srv/media-pipeline/{incoming,work,done,corrupt,retry} - IN_DIR ist davon dasselbe Verzeichnis, in das fetchbridges TARGET_DIR schreibt, die anderen vier sind rein interner Zustand. Das .deb-Postinst legt alle fünf mit der gemeinsamen Gruppe (media-pipeline) an. Wer davon abweichende Pfade will, kann sie wie gehabt über [paths] in /etc/yt-upload/upload.conf überschreiben. Vor dem ersten Start noch get-token einmalig manuell ausführen (kein Service, siehe oben), dann:
systemctl enable --now yt-uploadDevuan / Debian ohne systemd (sysvinit-core, OpenRC): Das Daemon-Paket bringt zusätzlich ein klassisches /etc/init.d/yt-upload-Skript mit, das daemon-postinst automatisch anstelle des systemd-Service registriert, wenn kein systemd läuft - ebenfalls deaktiviert (update-rc.d … defaults-disabled, kein Start beim Booten). Die mitgelieferte .service-Datei unter /usr/lib/systemd/system/ bleibt dort einfach ungenutzt liegen, wie bei Debian-Paketen üblich. Aktivieren und starten:
update-rc.d yt-upload enable
service yt-upload startDateien in RETRY_DIR (z.B. nach einem tagesaktuellen API-Kontingent-Limit quotaExceeded, oder mit bereits teilweise hochgeladenen Segmenten) bleiben dort, bis sie manuell zurück nach IN_DIR verschoben werden. Das yt-upload-daemon-Paket bringt dafür optional einen systemd-Timer mit, der das automatisch übernimmt:
systemctl enable --now yt-upload-retry.timerLäuft standardmäßig einmal täglich (OnCalendar=daily, siehe yt-upload-retry.timer - passend zu Googles täglichem Kontingent-Reset, per systemctl edit yt-upload-retry.timer beliebig anpassbar) und ruft dabei nur yt-upload --requeue-retries auf - ein einmaliger, kurzlebiger Aufruf ohne eigenen Cooldown im Code: ein zu früh erneut versuchter quotaExceeded-Fall scheitert einfach sofort wieder (kostet kein zusätzliches Kontingent) und landet erneut in RETRY_DIR. Das Timer-Intervall ist damit die einzige Stellschraube für die Retry-Kadenz. Bereits hochgeladene Segmente gehen dabei nie verloren (Fortschritt wird anhand des Dateinamens automatisch wiedergefunden).
Ohne systemd übernimmt cron dieselbe Aufgabe: /etc/cron.d/yt-upload-retry wird bereits mitinstalliert, allerdings standardmäßig deaktiviert (die Zeitplan-Zeile ist auskommentiert) - zum Aktivieren einfach einkommentieren:
sed -i 's/^#0 3/0 3/' /etc/cron.d/yt-upload-retryErfolgreich hochgeladene Originale bleiben in DONE_DIR liegen. yt-upload --purge-done löscht dort alle Dateien, die seit mindestens done_retention_days Tagen (in upload.conf unter [settings] bzw. DONE_RETENTION_DAYS, Standard 7, 0 = nie löschen) in DONE_DIR liegen. Gezählt wird ab der Ankunft in DONE_DIR (ctime der Datei), nicht ab dem Aufnahme- oder Downloaddatum - ein altes yt-dlp-Video wird also nicht direkt nach dem Upload gelöscht. Nur reguläre Dateien direkt in DONE_DIR, keine Unterverzeichnisse, Symlinks oder Dotfiles; CORRUPT_DIR und RETRY_DIR werden nie angefasst. Wie der Retry-Timer läuft das als eigener, kurzlebiger Oneshot-Dienst ohne Netzwerkzugriff und wird nicht automatisch aktiviert:
systemctl enable --now yt-upload-purge.timerDer Timer prüft täglich, die Frist selbst steht nur in der Config. Ohne systemd liegt /etc/cron.d/yt-upload-purge deaktiviert bei:
sed -i 's/^#30 4/30 4/' /etc/cron.d/yt-upload-purgeJedes Release enthält neben den .deb-Dateien auch FreeBSD-Pakete, je eines für FreeBSD 14 und 15 (…-freebsd14.pkg / …-freebsd15.pkg, gebaut von freebsd/build-pkg.py). Sie hängen fest an Python 3.11 (python311), damit Interpreter und Python-Abhängigkeiten zusammenpassen:
pkg install python311 py311-requests ffmpeg
pkg add yt-upload-<version>-freebsd14.pkg yt-upload-daemon-<version>-freebsd14.pkgDas CLI-Paket yt-upload legt /etc/yt-upload/upload.conf aus der Vorlage an, falls noch keine existiert. yt-upload-daemon bringt das rc.d-Skript mit und legt den Dienstuser, die Gruppe media-pipeline und die Verzeichnisse unter /srv/media-pipeline an, genau wie das Debian-Paket. Der Dienst wird dabei bewusst nicht aktiviert, die nötigen sysrc/service-Befehle zeigt pkg nach der Installation an. Noch nicht auf einem echten FreeBSD-System getestet.
Für FreeBSD ≥ 14.5 (native inotify in der libc) liegt unter freebsd/rc.d/yt-upload ein rc.d-Skript bei, das Pendant zum systemd-Service aus debian/. Ohne das fertige Paket geht die Einrichtung auch von Hand und aktiviert den Dienst ebenfalls nicht von selbst. Bisher nur gegen die Doku geschrieben, noch nicht auf einem echten FreeBSD-System getestet.
# Abhängigkeiten (py311 an die installierte Python-Version anpassen)
pkg install python3 py311-pip py311-requests ffmpeg
cd /pfad/zu/yt-upload
pip install --no-deps .
# Dienstuser und gemeinsame Pipeline-Gruppe (wie debian/postinst)
pw groupshow media-pipeline >/dev/null 2>&1 || pw groupadd media-pipeline
pw usershow yt-upload >/dev/null 2>&1 || pw useradd yt-upload -d /nonexistent -s /usr/sbin/nologin -G media-pipeline
install -d -o root -g media-pipeline -m 2775 /srv/media-pipeline /srv/media-pipeline/incoming /srv/media-pipeline/work /srv/media-pipeline/done /srv/media-pipeline/corrupt /srv/media-pipeline/retry
install -d /etc/yt-upload
# rc.d-Skript installieren und aktivieren
install -m 755 freebsd/rc.d/yt-upload /usr/local/etc/rc.d/yt-upload
sysrc yt_upload_enable=YES
service yt-upload startVor dem service yt-upload start wie unter Linux /etc/yt-upload/upload.conf anlegen (Vorlage: upload.conf.example) und einmalig get-token ausführen. Optionaler täglicher Retry-Requeue per cron (FreeBSD liest /usr/local/etc/cron.d/):
echo '0 3 * * * yt-upload /usr/local/bin/yt-upload --requeue-retries >/dev/null 2>&1' > /usr/local/etc/cron.d/yt-upload-retryEbenso optional das tägliche Löschen alter Dateien in DONE_DIR (done_retention_days, Standard 7 Tage):
echo '30 4 * * * yt-upload /usr/local/bin/yt-upload --purge-done >/dev/null 2>&1' > /usr/local/etc/cron.d/yt-upload-purgeDas Skript startet yt-upload -D über daemon(8) (Neustart bei Absturz, Userwechsel inkl. media-pipeline-Zusatzgruppe) und leitet die Ausgabe an syslog weiter (Tag yt-upload, landet standardmäßig in /var/log/messages). Weitere Einstellungen (yt_upload_runas, yt_upload_args, yt_upload_env) stehen im Kopf des Skripts.
./build-pyz.sh baut aus src/ je ein selbst-enthaltenes .pyz pro Eintrag in [project.scripts] (yt-upload.pyz und get-token.pyz) samt requests - läuft auf jedem System mit einem nackten python3, ganz ohne vorherige pip install/apt install:
./build-pyz.sh
./yt-upload.pyz --version
./get-token.pyzCREDENTIALS_FILE ist per Env-Var überschreibbar (config.py) - das lässt sich mit LoadCredentialEncrypted= (systemd >= 250) kombinieren, um die OAuth-Credentials-Datei nicht mehr dauerhaft als Klartext auf der Platte liegen zu haben. Anders als eine App-seitige Verschlüsselung mit Schlüssel direkt daneben ist das ein echter Gewinn: der yt-upload-Systemuser selbst braucht dafür nie Lesezugriff auf den Master-Key - nur systemd (PID 1, root) entschlüsselt beim Service-Start und reicht dem Prozess ausschließlich eine Kopie in einem privaten, nur für ihn lesbaren tmpfs-Verzeichnis durch.
get-token und der yt-upload-Dienst nutzen bare-metal standardmäßig beide /etc/yt-upload/youtube-upload-credentials.json (ohne /app/oauth, das ist nur die Docker-Konvention) - keine manuelle CREDENTIALS_FILE-Konfiguration nötig, bevor es weitergeht:
Am saubersten über ein Override-Snippet statt direkt in der von .deb/systemd verwalteten Unit-Datei (bleibt so update-sicher):
# 1. Vorhandene Klartext-Datei verschlüsseln (einmalig, als root; Standard ist
# --with-key=auto: bindet automatisch an einen vorhandenen TPM2-Chip
# zusätzlich zum maschinen-eigenen Schlüssel unter
# /var/lib/systemd/credential.secret - ganz ohne manuelle Angabe.
# --with-key=tpm2 erzwingt AUSSCHLIESSLICH TPM2, ohne den Host-Schlüssel)
systemd-creds encrypt \
--name=youtube-credentials \
/etc/yt-upload/youtube-upload-credentials.json \
/etc/yt-upload/youtube-upload-credentials.json.cred
# 2. Override-Datei anlegen statt die Unit direkt zu editieren
systemctl edit yt-uploadIm Editor, der sich dabei öffnet, folgendes Override-Snippet einfügen:
[Service]
LoadCredentialEncrypted=youtube-credentials:/etc/yt-upload/youtube-upload-credentials.json.cred
Environment=CREDENTIALS_FILE=%d/youtube-credentials(%d ist der systemd-Specifier für $CREDENTIALS_DIRECTORY, das private tmpfs mit der entschlüsselten Kopie.)
# 3. Erst NACH erfolgreichem Test (systemctl restart yt-upload, Logs prüfen) das
# Original entfernen - shred statt rm, damit nichts unverschlüsselt auf der SSD/im
# Dateisystem-Journal hängen bleibt
systemctl restart yt-upload
shred -u /etc/yt-upload/youtube-upload-credentials.jsonget-token selbst bleibt davon unberührt - es muss weiterhin einmalig interaktiv laufen und die Klartext-Datei erst erzeugen, bevor sie in Schritt 1 verschlüsselt wird.
Hinweis zu den Dateirechten: Die von systemd nach $CREDENTIALS_DIRECTORY gelieferte, entschlüsselte Kopie zeigt bei systemd >= 254.3 bewusst 0440 (-r--r-----+) statt 0600 - der eigentliche Zugriffsschutz läuft dort über eine ACL (user:<dienst-user>:r--), nicht über die klassischen Mode-Bits (siehe systemd/systemd#29435). yt-upload erkennt das anhand von $CREDENTIALS_DIRECTORY und überspringt für solche Pfade den sonst üblichen "Datei zu offen berechtigt"-Check samt automatischer chmod 600-Korrektur - Letztere würde auf dem read-only tmpfs ohnehin nur mit EROFS fehlschlagen und unnötig eine Warnung ins Log schreiben.
Es gibt drei Dockerfiles für unterschiedliche Basis-Images - alle bauen dasselbe yt_upload-Package ein, nur der Installationsweg passt sich an die jeweilige Distribution an:
| Dockerfile | Basis | Installationsweg |
|---|---|---|
Dockerfile (Standard) |
debian:trixie-slim |
Zweistufiger Build, pip install --no-deps in einer separaten Builder-Stage, System-Pakete (requests) über apt |
Dockerfile.alpine |
alpine:3 |
Wie oben, aber apk statt apt |
Dockerfile.pyimg |
python:3-slim |
Einstufig, alles über pip (inkl. requests direkt aus den in pyproject.toml deklarierten Dependencies) |
Alle drei Varianten lassen kein Build-Tooling (pip/setuptools, sofern nicht ohnehin Teil des Basis-Images) im finalen Laufzeit-Image zurück.
yt-upload [-h] [-v] [-f PATH] [-a] [-D] [--healthcheck] [--requeue-retries]
[--purge-done] [-t TITLE]
[--title-template TEMPLATE]
[-d DESCRIPTION | --description-file PATH]
[-c CATEGORY] [--tags TAGS] [--privacy {public,private,unlisted}]
[--thumbnail PATH] [--playlist PLAYLIST] [--publish-at ISO_DATE]
[--license {youtube,creativeCommon}] [--location LOCATION]
[--recording-date DATE] [--default-language LANG]
[--default-audio-language LANG] [--embeddable {true,false}]
[--credentials-file PATH] [--client-secrets PATH]
[--chunksize BYTES] [--open-link]
[file ...]
Unter /etc/yt-upload/ befindet sich die upload.conf. Diese wird sowohl im Container als auch bei einer Bare-Metal-Installation gelesen. Für Snippets steht zusätzlich das conf.d-Verzeichnis zur Verfügung.
Mit -f/--config PATH lässt sich stattdessen eine eigene Config-Datei angeben, z.B. für manuelle Uploads als normaler User (yt-upload -f ~/yt-upload.conf video.mp4). Sie ersetzt upload.conf und conf.d für diesen Aufruf komplett (nicht gemischt, nicht angegebene Werte fallen auf die eingebauten Defaults zurück), Umgebungsvariablen gelten weiterhin. Für einen eigenen Token als normaler User darin credentials_file unter [paths] setzen, da die System-Credentials-Datei nur für den yt-upload-User lesbar ist.
# ==============================================================================
# YouTube Video Uploader Configuration Example
# Pfad: /etc/yt-upload/upload.conf oder conf.d/*.conf
# ==============================================================================
[paths]
# Verzeichnis für neu eingehende Videodateien
#in_dir = /srv/media-pipeline/incoming
# Temporäres Arbeitsverzeichnis während der Verarbeitung/Splittings
#work_dir = /srv/media-pipeline/work
# Zielverzeichnis für erfolgreich hochgeladene und archivierte Dateien
#done_dir = /srv/media-pipeline/done
# Zielverzeichnis für fehlerhafte oder unvollständige Dateien
#corrupt_dir = /srv/media-pipeline/corrupt
# Zielverzeichnis für Dateien, bei denen bereits mind. ein Segment erfolgreich
# hochgeladen wurde, bevor ein Fehler auftrat (getrennt von corrupt_dir, um
# Doppel-Uploads bereits hochgeladener Segmente bei einem erneuten Lauf zu vermeiden)
#retry_dir = /srv/media-pipeline/retry
# Pfad zur zentralen Logdatei
#log_file = /log/upload.log
# Pfad zu den Google OAuth Credentials. Ohne diese Angabe: /app/oauth/... in
# Docker (siehe dortiges Bind-Mount), sonst /etc/yt-upload/... auf Bare-Metal.
#credentials_file = /etc/yt-upload/youtube-upload-credentials.json
[settings]
# Erstellt/Ermittelt automatisch Playlists basierend auf dem 'ARTIST'-Tag (true/false)
#enable_dynamic_playlists = false
# Startzeit aus dem RECORDING_START-Tag der Datei (schreibt tw-recorder) als
# Zeile "Aufnahmestart: TT.MM.JJJJ HH:MM <Zone>" der Beschreibung voranstellen.
# Zeitzone über die TZ-Umgebungsvariable (ohne TZ: UTC). Unabhängig davon wird
# die Startzeit als recordingDate an YouTube übergeben. (true/false)
#add_start_time_to_description = true
# Standard-Sichtbarkeit für hochgeladene Videos (public, private, unlisted)
#privacy_status = unlisted
# Standard-Kategorie (Name oder YouTube Category ID, z.B. 22)
#default_category = Entertainment
# Standardsprache für Titel, Beschreibung und Audio (ISO 639-1 Code)
#default_language = de
# Einbetten der Videos auf externen Websites erlauben (true/false)
#allow_embedding = true
# Standard-Beschreibungstext, falls keine Metadaten/CLI-Argumente vorhanden sind
#default_description = Automatischer Upload via Script.
# Standard-Tags (kommagetrennt)
#default_tags = Upload, Video
# Automatische Thumbnail-Generierung via FFmpeg aktivieren (true/false)
#auto_generate_thumbnail = true
# Mindestintervall in Sekunden für den Auto-Thumbnail Frame-Grab
#auto_thumb_min_sec = 15
# Maximalintervall in Sekunden für den Auto-Thumbnail Frame-Grab
#auto_thumb_max_sec = 120
# Bei Namenskonflikten in DONE/CORRUPT Dateien überschreiben statt umzubenennen (true/false)
#allow_overwrite = true
# Dateien in done_dir nach so vielen Tagen löschen (ab Ankunft in done_dir;
# 0 = nie). Wirkt nur mit `yt-upload --purge-done` (yt-upload-purge.timer)
#done_retention_days = 7
# Aktiviert die Zensurfunktion für die description
#enable_description_censor = false
[blacklist]
# Adult / NSFW
#onlyfans.com = true
#fansly.com = true
#loyalfans.com = true
#manyvids.com = true
#pornhub.com = true
#chaturbate.com = true
# Gambling & Skins
#stake.com = true
#csgoroll.com = true
#hellcase.com = true
#1xbet.com = true
# Adfly & Spammige Shortener
#adf.ly = true
#shorte.st = true
[force_private]
# Videos dieser Artists (ARTIST-Tag der Datei, bei tw-recorder der Twitch-Kanal,
# bei yt-dlp der Uploader) immer als 'private' hochladen, unabhängig von
# privacy_status - z.B. um sie vor der Freigabe in YouTube Studio ab 18
# einzustufen (die Altersbeschränkung lässt sich per API nicht setzen).
# Groß-/Kleinschreibung egal; --privacy auf der Kommandozeile hat Vorrang.
# Zusätzlich per Umgebungsvariable: FORCE_PRIVATE_ARTISTS=kanal1,kanal2
#streamername = true-
-D,--daemonStartet den Dauerüberwachungs-Dämon viainotify(ohne Argumente). -
-a,--autoVerarbeitet alle Videos inIN_DIR(Standard:/srv/media-pipeline/incoming) im Batch-Modus und beendet sich danach. -
--healthcheckPrüft nur den Heartbeat des laufenden Dämons und beendet sich sofort - für DockerHEALTHCHECKgedacht, nicht für den interaktiven Gebrauch. -
--requeue-retriesVerschiebt alle Dateien ausRETRY_DIRzurück nachIN_DIRund beendet sich sofort - für einen periodischen systemd-Timer gedacht (sieheyt-upload-retry.timerweiter oben), kann aber auch manuell aufgerufen werden. -
--purge-doneLöscht Dateien, die seit mindestensdone_retention_daysTagen (Standard:7,0= aus) inDONE_DIRliegen, und beendet sich sofort - für einen periodischen systemd-Timer gedacht (sieheyt-upload-purge.timerweiter oben). -
-t,--titleTEXTSetzt explizit den Videotitel (überschreibt ausgelesene Metadaten). -
file [file ...]Mehrere Videodateien in einem Aufruf hochladen (yt-upload video1.mp4 video2.mp4 ...), nacheinander mit denselben Metadaten. Bricht auf einmal ab, falls eine der Dateien nicht existiert, statt teilweise zu verarbeiten. -
--title-templateTEMPLATE(Standard:{title} (Teil {n}/{total})) Nur wirksam bei mehreren Dateien und explizit gesetztem-t/--title: numeriert den gemeinsamen Titel pro Datei durch (Platzhalter{title},{n},{total}). Ohne explizites-tbehält jede Datei ihren eigenen, aus Metadaten/Dateiname abgeleiteten Titel. -
-c,--categoryNAME/IDName oder YouTube Category-ID (z. B.Entertainment,Gaming,22). -
-d,--descriptionTEXTBeschreibungstext für das Video. -
--description-filePATHLiest den Beschreibungstext stattdessen aus einer Textdatei (z. B. für längere, mehrzeilige Beschreibungen ohne Shell-Escaping). Schließt sich mit-d/--descriptiongegenseitig aus. -
--embeddable{true,false}Erlaubt (true, Standard) oder verbietet (false) das Einbetten des Videos auf externen Webseiten. -
--privacySTATUSSichtbarkeit des Videos (public,unlisted[Standard],private). -
--playlistNAMEName der Ziel-Playlist (wird automatisch erstellt, falls nicht vorhanden). -
--chunksizeBYTESChunk-Größe für Resumable Uploads in Bytes (Standard:268435456= 256 MiB, auf ein Vielfaches von 256 KiB gerundet - zwingende Vorgabe der YouTube API). Läuftyt-uploadinteraktiv in einem echten Terminal, zeigt sich pro Chunk-Grenze ein Live-Fortschrittsbalken (Prozent, Transferrate, ETA) auf stderr statt der sonst üblichen Logzeile - für einen glatteren Balken kleinere Werte wählen. Im Dämon-/Container-Betrieb (kein TTY) bleibt es bei der Logzeile. -
--open-linkÖffnet nach erfolgreichem Upload die Video-URL im Standardbrowser.
-
ENABLE_DYNAMIC_PLAYLISTS- Standard:
false - Beschreibung: Bei
truewird derARTIST-Tag aus den Videometadaten automatisch als Playlist-Name genutzt.
- Standard:
-
ADD_START_TIME_TO_DESCRIPTION- Standard:
true - Beschreibung: Stellt der Beschreibung die Startzeit aus dem
RECORDING_START-Tag der Datei voran (schreibt tw-recorder ab 1.8.0) (Aufnahmestart: 01.10.2026 22:15 CEST, Zeitzone perTZ). Dateien ohne dieses Tag (z.B. yt-dlp-Downloads) bleiben unverändert. Bei gesplitteten Videos bekommt jeder Teil seine eigene Startzeit. Die Startzeit geht außerdem immer alsrecordingDatean YouTube, das dort aber nur das Datum anzeigt.
- Standard:
-
DONE_RETENTION_DAYS- Standard:
7 - Beschreibung: Mindestalter in Tagen (ab Ankunft in
DONE_DIR), ab dem--purge-doneeine Datei löscht.0schaltet das Löschen ab. Wirkt nur, wenn--purge-doneperiodisch aufgerufen wird.
- Standard:
-
TZ- Standard:
UTC - Beschreibung: Zeitzone für Logs und Anwendungszeitstempel (z. B.
Europe/Berlin).
- Standard:
-
HOME- Standard:
/app - Beschreibung: Pfad für benutzerspezifische Konfigurationen/Caches (im Container meist
/tmpfür Read-Only-Support).
- Standard:
-
LOG_LEVEL- Standard:
INFO - Beschreibung:
DEBUG/INFO/WARNING/ERROR/CRITICAL(case-insensitive), ein ungültiger Wert fällt sicher auf den Standard zurück. Hat immer Vorrang vorDEBUG.
- Standard:
-
DEBUG- Standard:
0 - Beschreibung: Setze auf
trueoder1, um erweiterte Log-Ausgaben für Entwickler zu aktivieren - abwärtskompatible Kurzform fürLOG_LEVEL=DEBUG, nur wirksam fallsLOG_LEVELnicht gesetzt ist.
- Standard:
Sämtliche Pfade aus dem [paths]-Abschnitt der upload.conf (siehe oben) lassen sich zusätzlich per gleichnamiger, großgeschriebener Umgebungsvariable überschreiben (z. B. RETRY_DIR, LOG_FILE, CREDENTIALS_FILE) - Umgebungsvariablen haben dabei immer Vorrang vor der Konfigurationsdatei.
/srv/media-pipeline/incoming: Eingangsverzeichnis für neue Videodateien - dasselbe Verzeichnis, in dasfetchbridgesTARGET_DIRschreibt./srv/media-pipeline/work: Temporäres Arbeitsverzeichnis während Analyse, Splitting und Upload./srv/media-pipeline/done: Archivverzeichnis für erfolgreich verarbeitete Originaldateien./srv/media-pipeline/corrupt: Zielverzeichnis für beschädigte, nicht lesbare oder komplett fehlgeschlagene Videodateien./srv/media-pipeline/retry: Zielverzeichnis für Dateien mit Teilfortschritt (mind. ein Segment bereits hochgeladen, dann ein Fehler) - manuell zurück nach/srv/media-pipeline/incomingverschieben, um den Rest nachzuholen.
work/done/corrupt/retry sind rein interner Zustand von yt-upload - kein anderer Dienst liest oder schreibt dort, sie liegen nur der Einfachheit halber im selben /srv/media-pipeline-Namespace wie incoming.
Reguläre Releases folgen vX.Y.Z (SemVer) und entstehen manuell zusammen mit einer echten Code-Änderung.
Zusätzlich prüft ein monatlicher Workflow (os-patch-release.yml, 1. jeden Monats), ob das Debian-/Alpine-Basis-Image ungenutzte Security-Patches hat, die docker-refresh.yml's wöchentliches latest-Update zwar schon mitnimmt, die aber an den fixen vX.Y.Z-Tags vorbeilaufen (die frieren für immer auf ihrem Build-Zeitpunkt ein). Findet der Workflow etwas, hängt er eine vierte Versionsstelle an, die ausschließlich für solche reinen OS-Patch-Releases reserviert ist: v1.5.1 → v1.5.1.1 → v1.5.1.2 (jeweils ohne Code-Änderung, nur aktualisierte System-Pakete). Bleibt die vierte Stelle bei Nichts-zu-patchen-Läufen einfach aus, gibt es auch keinen neuen Tag - kein Rauschen in der Release-Historie.
Der nächste echte Code-Release setzt diese vierte Stelle nicht fort, sondern lässt sie weg: auf v1.5.1.2 folgt bei einer echten Änderung v1.5.2, nicht v1.5.2.0 oder v1.5.1.3.
Ein neues Docker-Image kann über das mitgelieferte Shell-Skript gebaut werden:
./build.sh # Nutzt Name & Version aus pyproject.toml, Standard-Dockerfile
./build.sh 2.0.0 # Explizite Version, Standard-Dockerfile
./build.sh alpine # Version aus pyproject.toml, Dockerfile.alpine
./build.sh 2.0.0 pyimg # Explizite Version, Dockerfile.pyimgName und Standard-Version werden automatisch aus pyproject.toml gelesen - ein explizit übergebenes Versions-Argument überschreibt das.
apt install python3-pytest # oder: pip install -r requirements-test.txt
pytest -v
ruff check src/yt_upload/Dieses Projekt steht unter der GNU General Public License v3.0 (GPLv3).