Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 13/Tutorial.md

🛠️ Kapitel 13 – Clipper (Tutorial)

---

Einleitung

Clips sind der beste Weg, lange Streams in kurze, teilbare Highlights zu verwandeln.
Das Ziel dieses Kapitels: Wir bauen ein System, das neue Videos automatisch erkennt, sinnvolle Stellen analysiert, passende Highlights schneidet und die Ergebnisse in Nextcloud ablegt – komplett mit Titeln und Hashtags für jede Plattform.
Der Clipper selbst übernimmt dabei nur die technische Verarbeitung. Alles rund um Steuerung, Analyse und Benachrichtigungen läuft über n8n – so bleibt das System 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, 512 MB RAM, 10 GB Speicher reichen aus
• Grundwissen: SSH-Verbindung, Nano-Editor, Basiskenntnisse in n8n

---

Vorbereitung

Bevor wir Clipper installieren, richten wir den Container sauber ein:

1. LXC erstellen

   • Debian 12, Name clipper
   • Ressourcen wie oben (1 vCPU, 512 MB RAM, 10 GB Speicher)

2. System aktualisieren und Basis-Tools installieren

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

3. Zeitsynchronisation prüfen

   timedatectl status
   

   Eine saubere Zeitbasis ist entscheidend, da Clips später anhand exakter Sekundenmarken geschnitten werden.

   Wenn der Container standardmäßig auf UTC läuft, kann man die Zeitzone so ändern:

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

Damit springt die Systemzeit sofort auf Europe/Berlin, und alle Logs sowie Schnittzeiten passen zur lokalen Zeit.

4. Ordnerstruktur vorbereiten

   mkdir -p /srv/clipper/{watch,out,temp,logs}
   

   • watch → Eingangsordner für neue Videos (über Nextcloud oder Twitch-Import)
   • out → fertige Clips + Metadaten
   • temp → Zwischenablagen für Analyse
   • logs → Protokolle aller Abläufe

Damit ist das Fundament gelegt: Der LXC ist vorbereitet, das System auf Stand, und die Ordnerstruktur für Clipper ist vorhanden.

---

Abschnitt 2 – Clipper-LXC einrichten (Basisdienste & Service-Skelett)

In diesem Abschnitt bereiten wir den Container so vor, dass der Benutzer clipper alle Arbeiten übernimmt. Root wird nur für die Installation und Systemaufgaben genutzt. Danach wechseln wir bewusst in die Session von clipper und arbeiten dort weiter. So bleibt das System sauber getrennt und sicher.

---

Schritt 1: Benutzer und Verzeichnisse anlegen

Zuerst legen wir den Benutzer clipper an und bereiten die Arbeitsverzeichnisse vor.

adduser clipper
# Passwort vergeben und die Standardfragen beantworten

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

Damit ist der Benutzer angelegt und besitzt alle notwendigen Verzeichnisse.

---

Schritt 2: Notwendige Pakete installieren

Als root installieren wir die benötigten Pakete.

apt update && apt install -y ffmpeg jq python3 python3-venv curl unzip inotify-tools sudo

• ffmpeg: Kernwerkzeug für Analyse und Schnitt
• jq: JSON-Handling
• python3/venv: Virtuelle Umgebung für spätere Analyse-Tools
• inotify-tools: optional für lokale Hooks
• sudo: erlaubt clipper bei Bedarf Systembefehle auszuführen

---

Schritt 3: Benutzer clipper für sudo freischalten

Damit clipper bei Bedarf Befehle mit Administratorrechten ausführen kann, geben wir ihm Zugang zur Gruppe sudo.

usermod -aG sudo clipper

---

Schritt 4: In die Session des Benutzers clipper wechseln

Ab hier arbeiten wir direkt als Benutzer clipper.

su - clipper

---

Schritt 5: Konfigurationsdatei anlegen

Wir erstellen die Umgebungsvariablen-Datei, die später von allen Skripten genutzt wird.

nano /srv/clipper/clipper.env

Inhalt:

CLIPPER_IN=/srv/clipper/watch
CLIPPER_OUT=/srv/clipper/out
CLIPPER_TMP=/srv/clipper/temp
CLIPPER_LOG=/srv/clipper/logs/clipper.log
EXPORT_VARIANTS="16x9,9x16"

Speichern mit Strg+O, bestätigen mit Enter, beenden mit Strg+X.

---

Schritt 6: Virtuelle Python-Umgebung vorbereiten

Noch immer als Benutzer clipper legen wir die virtuelle Umgebung an und installieren die ersten Pakete.

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

Damit ist die Grundlage für spätere Analysen geschaffen. KI und STT binden wir später in Abschnitt 4 ein.

---

Schritt 7: Einstiegsskripte erstellen

Jetzt erstellen wir die beiden Einstiegspunkte clipper-analyze und clipper-cut. Sie liegen im Verzeichnis /srv/clipper/bin/ und dienen n8n als Schnittstelle.

Analyse-Skript

nano /srv/clipper/bin/clipper-analyze

Inhalt:

#!/usr/bin/env bash
set -euo pipefail
ENV_FILE="/srv/clipper/clipper.env"; [ -r "$ENV_FILE" ] || { echo "ENV nicht lesbar: $ENV_FILE" >&2; exit 1; }; source "$ENV_FILE"
IN="$1"
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"

Schnitt-Skript

nano /srv/clipper/bin/clipper-cut

Inhalt:

#!/usr/bin/env bash
set -euo pipefail
ENV_FILE="/srv/clipper/clipper.env"; [ -r "$ENV_FILE" ] || { echo "ENV nicht lesbar: $ENV_FILE" >&2; exit 1; }; source "$ENV_FILE"
IN="$1"
RANGES_JSON="$2"
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

Speichern beide Male mit Strg+O, bestätigen mit Enter, beenden mit Strg+X.

Rechte setzen:

chmod +x /srv/clipper/bin/clipper-*

---

Schritt 8: Skripte testen

Wir testen die beiden Einstiegspunkte.

Analyse-Test:

/srv/clipper/bin/clipper-analyze /srv/clipper/watch/demo.mp4 job-001

Schnitt-Test:

/srv/clipper/bin/clipper-cut /srv/clipper/watch/demo.mp4 /srv/clipper/temp/job-001/ranges.json job-001

Logs prüfen:

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

---

Schritt 9: Logrotation einrichten

Zum Abschluss richten wir die automatische Log-Rotation ein. Dafür wechseln wir kurz zurück zu root.

exit   # zurück zu root
nano /etc/logrotate.d/clipper

Inhalt:

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

---

Ergebnis Abschnitt 2:

• Benutzer clipper ist vollständig eingerichtet und übernimmt die Arbeit.
• Skripte clipper-analyze und clipper-cut laufen fehlerfrei in seiner Session.
• n8n kann später direkt als Benutzer clipper per SSH einsteigen und die Skripte aufrufen.