Videokompetenz (georg-malahov/claude-skills)

Videokompetenz

Verarbeite und teile Videos mit ffmpeg, Deepgram Nova 3 und S3/Tunnel-Freigabe.

Standard: leichteres Video, gleiche Auflösung

Standardmäßig immer in eine kleinere Datei mit der ursprünglichen Auflösung umkodieren. Eine komprimierte Kopie in derselben Auflösung ist fast immer das, was der Benutzer möchte – schnellere Uploads, leichtere Freigaben, identisches Seherlebnis. Mach dies zum Standard in jedem Ablauf (still, interaktiv und der Gemini dev-video Wiedergabekodierung); weiche nur ab, wenn der Benutzer explizit etwas anderes sagt. Konkret:

• Standardoptimierung = --resolution keep – Kodiere mit libx264 + CRF und keinem Scale-Filter neu, sodass die Auflösung unverändert bleibt und die Datei einfach kleiner wird. Dies ist die empfohlene Q1-Wahl und der Standard im Stillmodus.
• Verkleinere nur (z. B. auf 1080p), wenn die Quelle wesentlich größer als 1080p ist (≥1440p / 4K) oder der Benutzer darum bittet. Vergrößere niemals.
• Überspringe die Neukodierung nur (verwende das unberührte Original / Stream-Copy), wenn der Benutzer explizit nach dem Original verlangt – z. B. „Behalte das Original“, „Kodiere nicht neu.“
• Sicherheitscheck: Vergleiche nach der Kodierung die Ausgabegröße mit der Quelle. Wenn sie nicht wesentlich kleiner ist (selten – z. B. bei bereits niedriger Bitrate), erhöhe CRF (26–28) oder falle auf das Original zurück. Bildschirmaufnahmen komprimieren besonders gut: CRF 24–26 mit preset slow reduziert routinemäßig 70–80 % und hält gleichzeitig Bildschirmtext scharf.
• Download-Schaltflächen: Die Seite zeigt standardmäßig eine einzelne „Video herunterladen“-Schaltfläche (sie verweist auf das Wiedergabevideo). Füge nur eine „Original herunterladen“-Schaltfläche hinzu – d. h. übergib render_page.py --original-filename <name> –, wenn du tatsächlich das unberührte Original unter genau diesem Namen in den Ausgabeordner hochlädst; andernfalls verlinkt die Schaltfläche auf eine fehlende Datei und führt zu einem 404-Fehler. Der standardmäßige Komprimieren-Behalten-Ablauf behält kein separates Original, daher übergib --original-filename nicht.

Voraussetzungen

• ffmpeg und ffprobe müssen installiert sein
• Python 3 muss verfügbar sein
• Die aws CLI muss verfügbar sein (für S3-Uploads)
• Deepgram API-Schlüssel – für Audiotranskription/Untertitel (Standard-Engine)
• OpenRouter API-Schlüssel – für die Gemini-Analyse-Engine (dev-video / transcript-cheap Modi). Optional; wird nur benötigt, wenn diese Modi ausgewählt werden.

Verzeichnisse

• Skripte: <skill_dir>/scripts/ – alle Python-Skripte und die player.html-Vorlage
• Anmeldeinformationen: ~/.config/video-skill/ – dauerhaft über Plugin-Updates hinweg
  • deepgram_token – einzeiliger Deepgram API-Schlüssel
  • openrouter_token – einzeiliger OpenRouter API-Schlüssel (Gemini-Analyse-Engine)
  • s3_credentials – key=value-Format (endpoint, bucket, access_key, secret_key)
• Einstellungen: ~/.config/video-skill/preferences.json – über Sitzungen hinweg gespeicherte Benutzerentscheidungen

Einrichtung der Anmeldeinformationen

Wenn Anmeldeinformationen fehlen, frage den Benutzer über AskUserQuestion:

Deepgram: Prüfe die Umgebungsvariable DEEPGRAM_API_KEY, dann die Datei ~/.config/video-skill/deepgram_token. Wenn keines existiert, frage den Benutzer und speichere es in der Datei.

OpenRouter: Prüfe die Umgebungsvariable OPENROUTER_TOKEN, dann die Datei ~/.config/video-skill/openrouter_token. Wird nur für die Analyse-Modi dev-video / transcript-cheap benötigt. Wenn ein Gemini-Modus ausgewählt ist und das Token fehlt, frage den Benutzer und speichere es in der Datei.

S3: Prüfe die Umgebungsvariablen (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_ENDPOINT, S3_BUCKET), dann ~/.config/video-skill/s3_credentials. Wenn sie fehlen, frage den Benutzer nach Endpunkt, Bucket, Zugriffsschlüssel, geheimem Schlüssel und speichere sie.

Wichtig: Übergib Anmeldeinformationen niemals als CLI-Argumente. Skripte lesen sie intern aus Dateien über --credential-dir ~/.config/video-skill.

Einstellungen

{
  "language": "de",
  "last_folder": "/Users/beispiel/bildschirmaufnahmen",
  "share_folder": "/Users/beispiel/bildschirmaufnahmen",
  "sharing_method": "s3",
  "optimization": "compress-keep",
  "crf": 23,
  "preset": "medium",
  "audio": "aac-128k",
  "subtitles": "track",
  "subtitle_style": "modern",
  "subtitle_font": "Helvetica Neue",
  "target_language": "de",
  "download_button": true,
  "passcode": true,
  "mode": "subtitles"
}

optimization: Wie das Wiedergabevideo kodiert wird. Standard compress-keep = Neu kodieren, leichter in der Quellauflösung (--resolution keep). Andere Werte: web-1080p (Herunterskalieren auf 1080p – für ≥1440p/4K-Quellen), custom, keep-original (keine Neukodierung – nur auf expliziten Benutzerwunsch). Siehe „Standard: leichteres Video, gleiche Auflösung“ oben.

mode: Ein einzelnes Feld, das die Transkriptions-/Analyse-Engine bestimmt. Einer von vier Werten (das alte Paar analysis_mode + developer_analysis wurde hier zusammengefasst):

mode	Engine	Untertitel	Entwickleranalyse	Verwende, wenn
subtitles (Standard)	Deepgram	präzise	nein	Normale Freigabe, nur Untertitel gewünscht
dev-audio	Deepgram	präzise	ja (aus Transkriptionstext)	Tool-/Bug-Feedback, auch saubere Untertitel gewünscht
dev-video	Gemini Video	grob	ja + Screenshots	Reichhaltigstes Tool-/UX-Feedback (liest den Bildschirm)
transcript-cheap	Gemini Audio	grob	nein	Günstige grobe Transkription, Zeitangaben nicht kritisch

Intern: subtitles/dev-audio führen process_and_share.py aus (letzteres mit --developer-analysis); dev-video/transcript-cheap führen die Gemini-Engine aus (gemini_analyze.py). „Entwickleranalyse“ = der Analyseblock auf der Seite plus das Analyse-Markdown-Artefakt (siehe diesen Abschnitt). Engine-Anleitung (Stand 2026-06): Verwende Deepgram für präzise Untertitel; verwende Gemini-Video für die Analyse, Gemini-Audio für günstige, grobe Transkriptionen. Für dev-video, wo auch präzise Untertitel wichtig sind, führe zusätzlich einen Deepgram-Durchlauf für den Track durch.

Speichern: Aktualisiere nach jeder interaktiven Wahl preferences.json. Speichere immer last_folder nach jedem Durchlauf. Laden: Lies zu Beginn. Verwende gespeicherte Werte als „(Empfohlen)“-Standards. Im Stillmodus direkt verwenden.

Skriptreferenz

Alle Skripte befinden sich in <skill_dir>/scripts/. Sie akzeptieren --credential-dir für Anmeldeinformationen und geben [PROGRESS]-Zeilen zur Statusverfolgung aus.

Skript	Zweck	Wichtige Argumente
process_and_share.py	Hauptworkflow: optimieren + transkribieren + rendern + hochladen	<video> --output-dir --share-folder --share s3|tunnel
share_existing.py	Einen bereits verarbeiteten Ordner teilen	<folder> --share-folder --share s3|tunnel
upload_s3.py	Ordner auf S3 hochladen	<folder> --key <key> --credential-dir
render_page.py	index.html aus Vorlage generieren	--output-dir --template --metadata
manage_registry.py	Registry-CRUD (hinzufügen/entfernen/auflisten/abrufen/migrieren)	<subcommand> --share-folder
partial_update.py	Einen freigegebenen Ordner neu rendern + neu hochladen (löst Schlüssel aus Registry auf, leitet Passcode weiter)	<output_folder> [--key]
font_name.py	Den internen Familiennamen einer TTF-Datei ausgeben (für ASS Fontname)	<font.ttf>
transcribe.py	Deepgram-Transkription → SRT + VTT	<video> --credential-dir [--language]
gemini_analyze.py	Gemini-Engine: Audiotranskription ODER Videoanalyse + Screenshots	<video> --mode audio|video --output-dir --credential-dir [--key]
burn_subtitles.py	Untertitel in Video einbrennen	<video> <srt> [--font --fontsize ...]
share_server.py	Lokaler HTTP-Server für Tunnel-Freigabe	<share_root> [--port]

Workflow

Schritt 0: Argumente parsen & Modus erkennen

Befehle:

• /video → Interaktiver Modus (Schritte 1-5)
• /video process <pfad> → Interaktiver Modus für bestimmte Datei
• /video share → Stillmodus: neuestes verarbeiten + teilen
• /video share <pfad> → Stillmodus: bestimmte Datei verarbeiten + teilen
• /video share <pfad> "kontext" → Stillmodus mit zusätzlichem Kontext für Metadaten
• /video start → Teilen-Server + Tunnel starten
• /video stop → Teilen beenden
• /video status → Geteilte Videos auflisten
• /video copy <schlüssel_oder_name> → Link + Passcode in die Zwischenablage kopieren
• /video remove <schlüssel_oder_name> → Aus Registry entfernen

---

Teilen-Befehle (direkt verarbeitet, keine Verarbeitung)

Teilen-Registry: <share_folder>/.share_registry.json – verwaltet von manage_registry.py.

start-Befehl:

1. Einstellungen lesen → share_folder. Wenn nicht gesetzt, fragen.
2. Prüfen pgrep -f share_server.py. Wenn ausgeführt, Status anzeigen.
3. Server starten: python3 "<scripts>/share_server.py" "<share_folder>" --port 8080 &
4. Tunnel starten: ssh -p 443 -R0:localhost:<port> -o StrictHostKeyChecking=no a.pinggy.io 2>&1 &
5. Tunnel-URL parsen. Anzeigen: „Server läuft unter <base_url>“
6. Vorhandene Videos mit vollständigen URLs auflisten (<base_url>/v/<key>).

stop-Befehl: pkill -f share_server.py; pkill -f "ssh.*pinggy"; pkill -f "ngrok http"

status-Befehl:

1. Ausführen: python3 "<scripts>/manage_registry.py" list --share-folder "<share_folder>"
2. Prüfen pgrep -f share_server.py auf Tunnelstatus.
3. Tabelle anzeigen: Schlüssel, Titel, S3-URL, Tunnel-URL, Passcode, erstellt.

copy-Befehl:

1. Ausführen: python3 "<scripts>/manage_registry.py" get --share-folder "<share_folder>" --key "<abfrage>"
2. Formatieren: <titel>\n<url>\nPasscode: <code> → pbcopy

remove-Befehl: Ausführen: python3 "<scripts>/manage_registry.py" remove --share-folder "<share_folder>" --key "<abfrage>"

---

Stillmodus (/video share)

Eine Bestätigung, eine Skriptausführung, minimale Interaktion.

Ablauf:

1. Video identifizieren (Argumentpfad oder neuestes in last_folder / aktuellem Arbeitsverzeichnis)

2. Ausgabeordner erstellen <share_folder>/<video_name>/

3. Passcode generieren (zufällig 6-stellig oder gespeicherte Einstellung)

4. Bestätigung anzeigen:

   Schnellfreigabe: demo.mov
   → gleiche Auflösung · komprimiert (CRF 23) · AAC 128k
   → Transkribieren + Untertitel (Track)
   → Teilen via S3 (permanenter Link)
   → Passcode: 482910
   Fortfahren?
   

   Optionen: Fortfahren (Empfohlen) / In interaktiven Modus wechseln

   Wenn mode dev-video oder transcript-cheap ist, führe nicht process_and_share.py aus – folge stattdessen dem Abschnitt „Gemini-Analyse-Engine“ (still, mit gespeicherten Einstellungen), lade dann trotzdem hoch und registriere die Freigabe.

5. Haupt-Workflow-Skript ausführen. Übergib --developer-analysis, wenn mode dev-audio ist:

   python3 "<scripts>/process_and_share.py" "<video_pfad>" \
       --output-dir "<ausgabe_ordner>" \
       --share-folder "<teilungs_ordner>" \
       --credential-dir ~/.config/video-skill \
       --resolution keep --crf 23 --preset medium --audio aac-128k \
       --subtitles track \
       --share s3 \
       --passcode "<passcode>" \
       [--developer-analysis] \
       [--context "<benutzer_kontext>"]
   

   Standard --resolution keep (komprimieren, gleiche Auflösung). Verwende --resolution 1080p nur, wenn die Quelle ≥1440p/4K ist, oder keep-original-Handhabung, wenn der Benutzer explizit die unberührte Datei möchte.

6. Überwache stdout auf METADATA_READY: – wenn das Skript diese Markierung ausgibt: a. Lese die TRANSCRIPT_PREVIEW: und METADATA_INFO:, die ihm vorausgingen. b. Generiere Titel, Beschreibung und 4-8 Kapitel aus der Transkriptionsvorschau. c. Wenn mode dev-audio ist (Entwickleranalyse aktiviert): Erstelle den Analyseblock und das Analyse-Markdown aus dem vollständigen Transkript (lies die SRT/VTT im Ausgabeordner, nicht die gekürzte Vorschau). Siehe die „metadata.json-Referenz“ und „Analyse-Markdown“-Abschnitte für die genaue Form und den Vertrag. Passe die Seitensprache an (RU / DE / EN). d. Schreibe metadata.json in das Ausgabeverzeichnis gemäß der metadata.json-Referenz. e. Das Skript erkennt metadata.json und fährt automatisch fort.

7. Skript wird beendet. Ergebnis anzeigen, auf …