diff --git a/Kapitel 13/Tutorial.md b/Kapitel 13/Tutorial.md new file mode 100644 index 0000000..12102de --- /dev/null +++ b/Kapitel 13/Tutorial.md @@ -0,0 +1,192 @@ +# 🛠️ 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, 1–2 GB RAM, 10 GB Speicher reichen aus +- **Grundwissen**: SSH-Verbindung, Nano-Editor, Basiskenntnisse in n8n + +--- + +## Vorbereitung + +Wir beginnen mit einem frischen Debian‑12‑LXC in Proxmox, benennen ihn `clipper` und vergeben die im Abschnitt oben genannten Ressourcen. Danach bringen wir das System auf Stand und installieren die Grundwerkzeuge: +```bash +apt update && apt upgrade -y +apt install -y curl nano unzip ffmpeg inotify-tools +``` + +Eine korrekte Systemzeit ist entscheidend, da Schnittmarken später auf exakten Sekunden basieren. Prüfe die Zeit mit: +```bash +timedatectl status +``` +Wenn hier UTC steht und du lieber „Europe/Berlin“ nutzen willst: +```bash +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: +```bash +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 – Clipper-LXC einrichten (Basisdienste & Einstiegsskripte) + +Jetzt richten wir Clipper so ein, dass er klare Einstiegspunkte zum **Analysieren** und **Schneiden** hat. Die eigentliche Logik füllen wir in Abschnitt 4 und 5, hier bauen wir das Gerüst. + +### Benutzer und Verzeichnisse + +Zuerst legen wir den Service-Benutzer an und weisen ihm die Arbeitsordner zu: +```bash +adduser clipper +mkdir -p /etc/clipper +chown root:clipper /etc/clipper +chmod 750 /etc/clipper +``` + +### Pakete installieren + +```bash +apt install -y ffmpeg jq python3 python3-venv curl unzip inotify-tools sudo +``` +- **ffmpeg** für Analyse und Schnitt +- **jq** für JSON-Verarbeitung +- **python3/venv** für optionale Analyse-Tools (z. B. Szenenerkennung, Face-Detection) +- **inotify-tools** für Dateisystem-Events +- **sudo** damit der Benutzer clipper bei Bedarf Rechte anheben kann + +Anschließend geben wir dem Benutzer clipper Sudo-Rechte: +```bash +usermod -aG sudo clipper +``` + +### Konfiguration anlegen + +Wir legen eine Konfigurationsdatei an, die von allen Skripten geladen wird: +```bash +nano /etc/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 +``` +Datei speichern und mit `chown root:clipper /etc/clipper/clipper.env && chmod 640 /etc/clipper/clipper.env` die Rechte setzen. + +### Python-Umgebung vorbereiten + +Die eigentliche Analyse binden wir erst in Abschnitt 4 ein. Damit die Basis steht, richten wir jetzt schon eine virtuelle Umgebung ein: +```bash +su - clipper +python3 -m venv /srv/clipper/.venv +source /srv/clipper/.venv/bin/activate +pip install --upgrade pip +pip install numpy opencv-python-headless +``` + +So haben wir erste Bibliotheken, mit denen Szenen- und Gesichtserkennung später möglich wird. + +### Einstiegsskripte (Stubs) + +Wir erstellen zwei Einstiegspunkte, die n8n direkt aufruft. Sie tun noch nichts außer Logging und Validierung. + +**Analyse-Stub** +```bash +nano /srv/clipper/bin/clipper-analyze +``` +Inhalt: +```bash +#!/usr/bin/env bash +set -euo pipefail +source /etc/clipper/clipper.env +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" +``` + +**Schneid-Stub** +```bash +nano /srv/clipper/bin/clipper-cut +``` +Inhalt: +```bash +#!/usr/bin/env bash +set -euo pipefail +source /etc/clipper/clipper.env +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 +``` + +Rechte setzen: +```bash +chmod +x /srv/clipper/bin/clipper-* +chown -R clipper:clipper /srv/clipper/bin +``` + +### Direktaufruf und Tests + +Wir verzichten bewusst auf systemd-Templates und rufen die Skripte direkt über n8n oder manuell auf. Beispiel: +```bash +su - 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 +``` +Wenn alles passt, siehst du Einträge `[ANALYZE]` und `[CUT]` mit deiner Job-ID. + +### Logrotation + +Zum Schluss sorgen wir dafür, dass Logs nicht unendlich wachsen: +```bash +nano /etc/logrotate.d/clipper +``` +Inhalt: +``` +/srv/clipper/logs/*.log { + rotate 14 + daily + missingok + notifempty + compress + delaycompress + copytruncate +} +``` + +--- + +Damit ist der Clipper-LXC vorbereitet: Benutzer, Verzeichnisse, Pakete, Konfiguration und Einstiegsskripte sind eingerichtet. In den nächsten Abschnitten bauen wir die Anbindung an Twitch/n8n, implementieren die Analyse-Logik (inklusive Facecam, Hochformat und Untertitel) und fügen den eigentlichen Schnitt hinzu, bevor alles sauber in Nextcloud abgelegt wird.