Files
Homelab--Bratonein-Kontroll…/Kapitel 13/Tutorial.md

20 KiB
Raw Blame History

🛠️ Kapitel 13 Clipper (Tutorial)


Einleitung

Clips sind der beste Weg, lange Streams in kurze, teilbare Highlights zu verwandeln. Unser Ziel in diesem Kapitel: Wir bauen ein System, das neue Videos automatisch erkennt, sinnvolle Stellen analysiert, passende Highlights schneidet und die Ergebnisse in Nextcloud ablegt inklusive Titeln und Hashtags für jede Plattform. Der Clipper selbst übernimmt dabei die technische Verarbeitung, während n8n für Steuerung, Analyse und Benachrichtigungen sorgt. Das System bleibt dadurch flexibel, ressourcenschonend und jederzeit erweiterbar.


Voraussetzungen

  • Proxmox LXC mit Debian 12 (Bookworm)
  • Nextcloud (Pflicht, Zielort für Clips & Metadaten)
  • n8n-Instanz (Automatisierung, Steuerung Clipper, Analyse, Metadaten-Erzeugung)
  • Twitch-Entwickler-Account inkl. API-Key (für VOD- und Clip-Zugriff)
  • Optional: RTMP-Server, falls VODs lokal aufgezeichnet werden
  • Ressourcen für den LXC: 1 vCPU, 12 GB RAM, 10 GB Speicher reichen aus
  • Grundwissen: SSH-Verbindung, Nano-Editor, Basiskenntnisse in n8n

Vorbereitung

Wir beginnen mit einem frischen Debian12LXC in Proxmox, benennen ihn clipper und vergeben die im Abschnitt oben genannten Ressourcen. Danach bringen wir das System auf Stand und installieren die Grundwerkzeuge:

apt update && apt upgrade -y
apt install -y curl unzip ffmpeg inotify-tools

Eine korrekte Systemzeit ist entscheidend, da Schnittmarken später auf exakten Sekunden basieren. Prüfe die Zeit mit:

timedatectl status

Wenn hier UTC steht und du lieber „Europe/Berlin“ nutzen willst:

timedatectl list-timezones | grep Europe
timedatectl set-timezone Europe/Berlin
timedatectl status

Die Zeit wird sofort angepasst, Logs und Schnittzeiten passen damit zur lokalen Umgebung.

Zum Schluss legen wir die Arbeitsordner an:

mkdir -p /srv/clipper/{watch,out,temp,logs}
  • watch Eingangsordner für neue Videos (egal ob von Twitch oder RTMP)
  • out fertige Clips und Metadaten
  • temp Zwischenspeicher für Analyse
  • logs Protokolle aller Abläufe

Damit ist das Fundament gelegt.


Abschnitt 2 ClipperLXC einrichten (Benutzer, Verzeichnisse, Pakete, Skripte)

In diesem Abschnitt richten wir den ClipperContainer so ein, dass SSHSchlüssel, Downloads und n8nAufrufe ohne Berechtigungsfehler funktionieren. Wir arbeiten jetzt im Terminal deines ClipperLXC als root.

Entscheidung & Begründung Benutzer mit Home & Bash
Der Benutzer clipper bekommt ein Homeverzeichnis (/home/clipper) und eine LoginShell. So können SSHSchlüssel sauber in ~clipper/.ssh landen und n8n später per SSH Befehle ausführen. Varianten ohne Home (SystemUser) führen bei ssh-copy-id zu Fehlern.

2.1 Benutzer und Verzeichnisse anlegen (Terminal, als root)

adduser --home /home/clipper --shell /bin/bash clipper

Vergib ein Passwort und bestätige die Abfragen. Danach legst du die Arbeitsordner an und überträgst den Besitz an clipper:

mkdir -p /srv/clipper/{inbox,watch,out,temp,logs,bin}
chown -R clipper:clipper /srv/clipper
chmod 750 /srv/clipper

(optional, aber hilfreich für ssh-copy-id später):

install -d -m 700 -o clipper -g clipper /home/clipper/.ssh

Falls du den Benutzer bereits ohne Home angelegt hast:
Richte ihn so nach:
mkdir -p /home/clipper/.ssh && chown -R clipper:clipper /home/clipper && chmod 700 /home/clipper/.ssh

2.2 Pakete installieren (Terminal, als root)

apt update && apt install -y yt-dlp jq python3 python3-venv curl unzip inotify-tools sudo
  • ffmpeg: Analyse & Schnitt
  • yt-dlp: TwitchVOD/ClipDownloads (HLS)
  • jq: JSONHandling
  • python3/venv: spätere AnalyseTools
  • inotify-tools: DateisystemEvents (optional)
  • sudo: für gezielte Rechteerhöhungen falls nötig

2.3 Zentrale Konfiguration (Terminal, als root)

Bevor wir die Umgebungsdatei anlegen, brauchen wir ein eigenes Konfigurationsverzeichnis. Das existiert standardmäßig nicht, daher legen wir es einmalig an:

mkdir -p /etc/clipper
chown root:clipper /etc/clipper
chmod 750 /etc/clipper

Entscheidung & Begründung eigenes /etc/clipper
Konfiguration gehört nach /etc. Mit einem eigenen Ordner /etc/clipper bleibt alles übersichtlich getrennt.
Besitzer ist root, die Gruppe clipper. So kann der Clipper-User die Datei lesen, aber nicht verändern genau die Balance zwischen Sicherheit und Funktion.

Entscheidung & Begründung eigenes /etc/clipper Konfiguration gehört nach /etc. Mit einem eigenen Ordner /etc/clipper bleibt alles übersichtlich getrennt. Besitzer ist root, die Gruppe clipper. So kann der Clipper-User die Datei lesen, aber nicht verändern genau die Balance zwischen Sicherheit und Funktion.

Lege eine Umgebungsdatei an, die beide Skripte laden:

nano /etc/clipper/clipper.env

Inhalt:

CLIPPER_INBOX=/srv/clipper/inbox
CLIPPER_IN=/srv/clipper/watch
CLIPPER_OUT=/srv/clipper/out
CLIPPER_TMP=/srv/clipper/temp
CLIPPER_LOG=/srv/clipper/logs/clipper.log

Dateirechte setzen, damit clipper sie lesen darf:

chown root:clipper /etc/clipper/clipper.env
chmod 640 /etc/clipper/clipper.env

2.4 PythonUmgebung vorbereiten (Wechsel zu Benutzer clipper)

Wechsle jetzt zum Benutzer clipper:

su - clipper

Erzeuge und fülle eine virtuelle Umgebung für die spätere Analyse:

python3 -m venv /srv/clipper/.venv
source /srv/clipper/.venv/bin/activate
pip install --upgrade pip
pip install numpy opencv-python-headless
deactivate

Wechsle für die nächsten Schritte im Benutzer clipper weiter.

2.5 Einstiegsskripte erstellen (im Benutzer clipper)

AnalyseStub prüft Eingaben, schreibt Logs, erzeugt leere Kandidatenliste:

nano /srv/clipper/bin/clipper-analyze

Inhalt:

#!/usr/bin/env bash
set -euo pipefail
ENV_FILE="/etc/clipper/clipper.env"; [ -r "$ENV_FILE" ] || { echo "ENV nicht lesbar: $ENV_FILE" >&2; exit 1; }; source "$ENV_FILE"
IN="$1"       # absolute Datei
JOBID="${2:-manual}"
mkdir -p "$CLIPPER_TMP/$JOBID"
echo "$(date '+%F %T') [ANALYZE] job=$JOBID file=$IN" | tee -a "$CLIPPER_LOG"
OUT_JSON="$CLIPPER_TMP/$JOBID/candidates.json"
echo '[]' > "$OUT_JSON"
echo "$OUT_JSON"

SchneidStub protokolliert Schnittaufrufe, echte Logik folgt in Abschnitt 5:

nano /srv/clipper/bin/clipper-cut

Inhalt:

#!/usr/bin/env bash
set -euo pipefail
ENV_FILE="/etc/clipper/clipper.env"; [ -r "$ENV_FILE" ] || { echo "ENV nicht lesbar: $ENV_FILE" >&2; exit 1; }; source "$ENV_FILE"
IN="$1"            # absolute Datei
RANGES_JSON="$2"   # Zeitbereiche (kommt später aus Abschnitt 4)
JOBID="${3:-manual}"
mkdir -p "$CLIPPER_OUT/$JOBID"
echo "$(date '+%F %T') [CUT] job=$JOBID file=$IN ranges=$RANGES_JSON" | tee -a "$CLIPPER_LOG"
exit 0

Rechte setzen und Eigentümer korrigieren:

chmod +x /srv/clipper/bin/clipper-*
chown -R clipper:clipper /srv/clipper/bin

2.6 Logrotation (zurück zu root)

Beende die Session (exit) und kehre zu root zurück. Richte Logrotation ein:

nano /etc/logrotate.d/clipper

Inhalt:

/srv/clipper/logs/*.log {
  rotate 14
  daily
  missingok
  notifempty
  compress
  delaycompress
  copytruncate
}

Schnelltest (optional):
Zurück im Benutzer clipper:
/srv/clipper/bin/clipper-analyze /srv/clipper/watch/demo.mp4 job-001
/srv/clipper/bin/clipper-cut /srv/clipper/watch/demo.mp4 /srv/clipper/temp/job-001/ranges.json job-001
tail -n 50 /srv/clipper/logs/clipper.log

Mit dieser Einrichtung sind SSHSchlüssel, Berechtigungen und Pfade konsistent. ssh-copy-id aus Abschnitt 3 funktioniert dadurch ohne Fehlermeldungen und n8n kann die Skripte stabil starten.


Abschnitt 3 n8n ↔ Twitch: VOD & Clips importieren, in Nextcloud ablegen, Clipper starten

In diesem Abschnitt verbinden wir n8n mit Twitch, Nextcloud und dem Clipper. Das Ziel: n8n erkennt automatisch neue VODs auf Twitch, lädt sie zusammen mit Clips herunter, legt sie in Nextcloud ab und startet dann die Analyse auf dem Clipper. Wir gehen Schritt für Schritt vor immer mit klaren Hinweisen, ob wir uns gerade in der n8nWeboberfläche, im Terminal oder in Nextcloud befinden.

Entscheidung & Begründung Rollenverteilung
n8n steuert (APIs, Logik, Benachrichtigungen). Clipper arbeitet (Download, Analyse, Schnitt). Nextcloud speichert (Archiv & Übergabe). So bleibt n8n schlank und ausfallsicher, während Clipper CPU/IO für Medienjobs bekommt.


Schritt 1: Zugriff zwischen den Containern vorbereiten (Terminal)

Optional: SSH Known-Hosts zurücksetzen (falls Clipper schon einmal erstellt wurde)

Wenn du den Clipper-LXC bereits früher erstellt und neu aufgesetzt hast, kann es zu einem SSH-Fehler kommen:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

Das bedeutet, dass sich der Server-Hostkey geändert hat. SSH blockiert dann aus Sicherheitsgründen.

Lösung Schritt für Schritt (im n8n-LXC als root)

  1. Fingerprint auf dem Clipper prüfen
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

(SHA256-Wert merken und vergleichen)

  1. Alten Eintrag löschen
ssh-keygen -R "<CLIPPER-IP>"

Entscheidung & Begründung Sicherheitsprinzip
SSH schützt vor Man-in-the-Middle-Angriffen, indem es Hostkeys prüft. Wenn ein Container neu erstellt wird, ist ein neuer Hostkey normal. Wir löschen den alten Eintrag bewusst, prüfen den neuen Fingerprint und akzeptieren ihn erst danach. So bleibt die Verbindung sicher und stabil.

Melde dich zuerst im Terminal deines n8nLXC an. Wir richten hier die Verbindung zum Clipper und zu Nextcloud ein.

SSHSchlüssel für Clipper erzeugen:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""
ssh-copy-id clipper@<CLIPPER-IP>
ssh clipper@<CLIPPER-IP> "echo OK"

Ersetze <CLIPPER-IP> durch die IP/den Hostnamen deines ClipperLXC (z.B. 10.0.0.42). Wenn OK erscheint, kann n8n ohne Passwort auf den Clipper zugreifen.

Zugangsdaten für NextcloudWebDAV erstellen (Weboberfläche)

Ort in Nextcloud: Avatar (oben rechts) → Persönliche EinstellungenSicherheitganz nach unten zum Bereich AppPasswörter.

Anleitung:

  1. Melde dich in der NextcloudWeboberfläche an.
  2. Gehe zu Persönliche EinstellungenSicherheit.
  3. Ganz nach unten scrollen bis zum Abschnitt AppPasswörter (unscheinbar platziert).
  4. Trage bei AppName z.B. n8n Clipper ein und klicke auf Neues AppPasswort erstellen.
  5. Kopiere das einmalig angezeigte AppPasswort sofort und notiere zusätzlich deinen Benutzernamen. (Das Passwort wird später nicht erneut angezeigt.)

WebDAVURL für n8n/Uploads:

https://<DEINE_NEXTCLOUD_DOMAIN>/remote.php/dav/files/<DEIN_NC_BENUTZER>/

(Alternativ, je nach Setup: https://<DEINE_NEXTCLOUD_DOMAIN>/remote.php/webdav/)

Schnelltest (optional, auf deinem n8nLXC)
curl -u "<BENUTZER>:<APP_PASSWORT>" \
  -X PROPFIND -H "Depth: 0" \
  -s -o /dev/null -w "%{http_code}\n" \
  "https://<DEINE_NEXTCLOUD_DOMAIN>/remote.php/dav/files/<DEIN_NC_BENUTZER>/"
# Erwartet: 207

Optional kannst du die ersten Zeilen der Antwort prüfen:

curl -u "<BENUTZER>:<APP_PASSWORT>" \
  -X PROPFIND -H "Depth: 0" -s \
  "https://<DEINE_NEXTCLOUD_DOMAIN>/remote.php/dav/files/<DEIN_NC_BENUTZER>/" \
  | head -n 5
# Erwartet: XML mit <d:multistatus ...>

Fehler & Lösung (kurz):

  • 401/403 → Benutzername oder AppPasswort falsch.
  • 404 → Pfad prüfen (richtiger Benutzerordner?).
  • AppPasswörter fehlen? Admin muss sie in den NextcloudEinstellungen aktivieren.

TwitchAPI Zugang:

Twitch Developer Console App anlegen
  1. Gehe auf Twitch Developer ConsoleApplicationsRegister Your Application.
  2. Felder ausfüllen:
  • Name: frei wählbar (muss einzigartig sein).
  • OAuth Redirect URL: z. B. https://localhost/ (Platzhalter; für Client-Credentials Flow nicht genutzt).
  • Category: passend wählen (z. B. Chatbot/Website Integration).
  1. App speichern → Manage öffnen.
  2. Client ID notieren, New Secret klicken und Client Secret sichern.

Twitch OAuth2 Credential in n8n (Client Credentials Flow)

Beim Anlegen in n8n → Credentials → + Add → OAuth2 API:

  • Name: Twitch API
  • Grant Type: Client Credentials
  • Authorization URL: https://id.twitch.tv/oauth2/authorize (Pflichtfeld, wird in diesem Flow nicht genutzt)
  • Access Token URL: https://id.twitch.tv/oauth2/token
  • Client ID: (aus Twitch Developer Console)
  • Client Secret: (aus Twitch Developer Console)
  • Scope: (leer lassen)
  • Authentication: Bodywichtig, sonst Fehler
  • OAuth Redirect URL: https://automation.bratonien.de/rest/oauth2-credential/callback (muss in Twitch-App eingetragen sein, auch wenn bei Client Credentials nicht genutzt)

Speichern.

Prüfen (kein „Test“-Button bei Client Credentials):

  1. Lege einen HTTP Request-Node an.
  2. Authentication: Predefined Credential Type → wähle dein Twitch API Credential.
  3. Headers: Client-Id: <DEINE_CLIENT_ID>
  4. URL: https://api.twitch.tv/helix/users?login=bratonien_tv
  5. Execute Node → kommt JSON mit data[0].id, ist OAuth korrekt.

Nutzung in HTTP Request Nodes

  • Authentication: Predefined Credential Type → wähle dein Twitch API Credential
  • Headers:
    • Client-Id: <DEINE_CLIENT_ID>

n8n setzt automatisch Authorization: Bearer <token>.


Schnelltest in n8n

HTTP Request Node:

  • Method: GET
  • URL: https://api.twitch.tv/helix/users?login=bratonien_tv
  • Header: Client-Id: <DEINE_CLIENT_ID>

Ergebnis: JSON mit data[0].id, login, usw. dann funktioniert OAuth2 korrekt.


Schritt 2: TwitchUserID herausfinden (n8nWeboberfläche)

Die TwitchAPI benötigt deine numerische UserID, nicht den LoginNamen. Wir holen diese ID einmalig in n8n.

  1. Gehe in der n8nWeboberfläche auf Workflows+ New Workflow.
  2. Ziehe einen HTTP Request Node auf die Arbeitsfläche.
  3. Konfiguriere ihn so:
    • Methode: GET
    • URL: https://api.twitch.tv/helix/users?login=<DEIN_LOGIN>
    • Authentifizierung: OAuth2 Credential (aus Schritt 1)
    • Header: Client-Id: <DEINE_CLIENT_ID>
  4. Klicke auf Execute Node.
  5. Im Ergebnis findest du im Feld data[0].id deine UserID (z.B. 123456789). Diese Zahl ist entscheidend und ersetzt ab jetzt <DEINE_TWITCH_USER_ID> in allen weiteren Schritten.

Referenz: Get Users

Entscheidung & Begründung Login vs. UserID
Der „Login“ ist nur ein Anzeigename. Die API filtert zuverlässig über die numerische ID deshalb holen wir sie einmalig und verwenden sie konsequent.


Schritt 3: Workflow bauen (n8nWeboberfläche)

Jetzt bauen wir den eigentlichen Workflow, der regelmäßig neue VODs prüft, herunterlädt und ablegt.

  1. Cron-Trigger anlegen:

    • Ziehe einen Cron Node auf die Arbeitsfläche.
    • Stelle ihn auf „Every 10 minutes“. Damit prüft n8n alle 10 Minuten auf neue VODs.
  2. VOD-Daten abrufen:

    • Ziehe einen weiteren HTTP Request Node an den Cron-Node.

    • URL:

      https://api.twitch.tv/helix/videos?user_id=<DEINE_TWITCH_USER_ID>&type=archive&first=1
      
    • Auth: OAuth2 Credential

    • Header: Client-Id: <DEINE_CLIENT_ID>

    • Ergebnis: In data[0] stehen id, title, url, created_at, published_at.

    Referenz: Get Videos

  3. IF „Neu?“ Node hinzufügen:

    • Bedingung (Expression):

      {{$json.data[0].id !== $workflow.staticData.global.last_vod_id}}
      
    • true → weiter; false → Ende

    Entscheidung & Begründung State merken Nur wenn die ID sich ändert, ist ein neues VOD da. So entstehen keine leeren Ordner und keine unnötigen API- oder SSH-Aufrufe.

  4. VOD herunterladen (SSH Execute Command im Clipper-LXC):

    • Node: SSH Execute Command (Credential: Clipper)

    • Command:

      JOBID="{{ $json.data[0].id }}"
      URL="{{ $json.data[0].url }}"
      DIR="/srv/clipper/inbox/$JOBID"
      
      mkdir -p "$DIR"
      
      yt-dlp \
        --download-archive "/srv/clipper/logs/yt-dlp.archive" \
        --no-part --restrict-filenames \
        --abort-on-unavailable-fragment \
        --retries 10 --fragment-retries 10 --retry-sleep 5 \
        -o "$DIR/%(title)s-%(id)s.%(ext)s" \
        "$URL"
      

    Entscheidung & Begründung yt-dlp Archive --download-archive verhindert doppelte Downloads. Retries sichern HLS-Streams ab. Alles passiert auf Clipper, aber gesteuert durch n8n.

  5. Clips abrufen (optional):

    • Node: HTTP Request

    • URL:

      https://api.twitch.tv/helix/clips?broadcaster_id=<DEINE_TWITCH_USER_ID>&started_at={{$json.data[0].created_at}}&ended_at={{$json.data[0].published_at}}
      
    • Danach: Split in Batches → je Clip-URL an SSH Execute Command

    Command (SSH):

    CID="{{ $json.id }}"
    CURL="{{ $json.url }}"
    DIR="/srv/clipper/inbox/$CID"
    
    mkdir -p "$DIR"
    
    yt-dlp \
      --download-archive "/srv/clipper/logs/yt-dlp.archive" \
      --no-part --restrict-filenames \
      --retries 10 --fragment-retries 10 --retry-sleep 5 \
      -o "$DIR/%(title)s-%(id)s.%(ext)s" \
      "$CURL"
    
  6. Upload nach Nextcloud (n8nWeboberfläche):

    • Node: HTTP Request

    • Methode: PUT

    • Auth: Basic Auth (Nextcloud App-Passwort)

    • URL:

      https://<DEINE_NEXTCLOUD_DOMAIN>/remote.php/dav/files/<DEIN_NC_BENUTZER>/Clips/{{ $json.data[0].id }}/<Dateiname>
      
    • Ergebnis: In Nextcloud liegt danach ein Ordner Clips/<VOD-ID>/….

    Entscheidung & Begründung Warum Nextcloud? Zentrales, versionierbares Speicherziel mit Freigaben/Quotas/Backups. Clipper und andere Systeme können darauf zugreifen, ohne erneut von Twitch laden zu müssen.

  7. Analyse starten (SSH Execute Command):

    • Command:

      VIDDIR="/srv/clipper/inbox/{{ $json.data[0].id }}"
      MAINFILE="$(find "$VIDDIR" -maxdepth 1 -type f -name '*.mp4' -o -name '*.mkv' | head -n1)"
      /srv/clipper/bin/clipper-analyze "$MAINFILE" "vod-{{ $json.data[0].id }}"
      

    Entscheidung & Begründung Arbeitsteilung n8n stößt nur an, Clipper rechnet. So bleibt n8n leicht und ausfallsicher.

  8. State aktualisieren (n8nWeboberfläche):

    • Node: Function oder Set

      $workflow.staticData.global.last_vod_id = $json.data[0].id;
      return items;
      

    Damit merkt sich der Workflow, welches VOD zuletzt verarbeitet wurde.

Alternative: TwitchCommunityNode (n8nWeboberfläche)

Wenn du statt HTTP Requests lieber einen fertigen TwitchNode nutzen willst, kannst du in selfhosted n8n einen CommunityNode installieren. Die Anleitung: n8n Community Nodes. Beachte: CommunityNodes sind DrittanbieterCode und können bei Updates Probleme machen. Für einen stabilen Dauerbetrieb empfehlen wir den APIWeg mit HTTP Request.


Kontrolle

Nach einem erfolgreichen Durchlauf prüfst du im Terminal des ClipperLXC:

su - clipper
ls -lh /srv/clipper/inbox/<VOD-ID>

tail -n 50 /srv/clipper/logs/clipper.log

Und in der NextcloudWeboberfläche solltest du den Ordner Clips/<VOD-ID> sehen. Damit ist die Pipeline geschlossen: Twitch liefert VODs, n8n steuert den Ablauf, Clipper verarbeitet, Nextcloud speichert. In Abschnitt 4 gehen wir in die AnalyseLogik und die KIAuswertung.