Communitygithub.com

ChuchoMonster/brand-video-pipeline

End-to-End Multi-Tenant-Marken-Erklär-/Promo-Video-Pipeline. Erzeugt ein komplettes Markenvideo aus einer URL – extrahiert Markenidentität, schreibt Skript, generiert Stimme + KI-Avatar + B-Roll-Bilder + Hintergrundmusik, montiert alles in HyperFrames und rendert es.

Was ist brand-video-pipeline?

Diese Pipeline automatisiert die Erstellung kompletter Marken-Erklär- oder Promo-Videos auf Basis einer einzelnen URL. Sie ist für den Multi-Tenant-Einsatz konzipiert, wobei die Konfiguration pro Marke minimal ist. Der Prozess beginnt mit der Extraktion der Markenidentität (Farben, Typografie, Stil) über das `brand-book`-Skill. Darauf folgt das Lesen der Website, um das Unternehmen und seine Zielgruppe zu verstehen, und das Schreiben eines maßgeschneiderten Skripts. Die Pipeline generiert dann Voiceovers via ElevenLabs TTS, KI-Avatare über HeyGen (mit Chroma-Key und symmetrischem Padding), B-Roll-Bilder mittels KI-gestützter Nano-Banana-2-Modelle (die Markenfarben einweben) und Hintergrundmusik über ElevenLabs Music. Alle Assets werden in einer HyperFrames-Composition zusammengeführt und als MP4 gerendert. Die Pipeline enthält dedizierte Phasen für Skripterstellung mit standardmäßiger Lautstärkeanpassung, Avatar-Kalibrierung, Prompt-Engineering für B-Roll-Bilder (mit zwei Vorlagen – abstrakt für Atmosphäre, glasartig für Statistiken) und Audiomischung, um ein konsistentes und professionelles Ergebnis zu gewährleisten. Sie wird durch eine Iterationsschleife ergänzt, die nach Bedarf schnelle Überarbeitungen ermöglicht.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChuchoMonster/brand-video-pipeline/tree/HEAD/skill

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

HyperFrames Pipeline — Multi-Tenant-Marken-Erklärvideos

End-to-End-Pipeline, die eine URL nimmt und ein fertiges, markiertes Erklär-/Promo-MP4 produziert. Erstellt und getestet mit ColdStart (coldstartb2b.com). Konzipiert für die Skalierung auf beliebige B2B-Marken mit minimaler Konfiguration pro Mandant.

Wann aufrufen

  • Benutzer sagt "Hyper Frames" / "hyperframes" + eine URL oder ein Markenname
  • Benutzer fragt nach einem Erklär-/Promo-Video für ein bestimmtes Unternehmen
  • Benutzer sagt "Erstelle ein Video für " oder ähnlich
  • Benutzer sagt "Lass es uns mit versuchen"

Erforderliche Umgebung (in $PIPELINE_ROOT/.env — kopiere .env.example)

KIE_AI_API_KEY=...        # Nano Banana 2 + Seedance 2 über KIE.AI
HEYGEN_API_KEY=...        # HeyGen Avatar-Generierung
ELEVENLABS_API_KEY=...    # 11Labs Stimme + Musik
ELEVENLABS_VOICE_ID=...   # Standard-Erzählerstimme
HEYGEN_TALKING_PHOTO_ID=...  # Standard-Avatar-Look

Projektstruktur

$PIPELINE_ROOT/            # Wurzelverzeichnis dieses Repositorys
  brands/
    <Marke>/              # Ein Verzeichnis pro Marke (erstellt von brand-book)
      brand.json
      colors.md
      typography.md
      voice-tone.md
      reference.png
  template-16x9/          # Die aktive Komposition (ein Arbeitsverzeichnis; Assets pro Marke tauschen)
    index.html
    styles/
      brand.css           # Marken-Schnittstelle — einzige Datei mit markenspezifischem CSS
      template.css        # Markenunabhängige Bewegung
      layouts.css         # 10-Layout-System
    assets/
      voice.mp3           # 11Labs-Ausgabe (aufgefüllt)
      avatar.webm         # HeyGen-Ausgabe (chromakeyed + aufgefüllt)
      music.mp3           # 11Labs Musik-Hintergrund
      broll-*.png         # Nano Banana B-Roll
    renders/

Für die Multi-Tenant-Produktion sollte zukünftige Stufe 0 template-16x9/ pro Marke kopieren. Derzeit werden Assets pro Render vor Ort getauscht.


Pipeline-Stufen

Stufe 1 — Markenextraktion

Rufe das brand-book-Skill mit der Ziel-URL auf. Es erzeugt:

  • brands/<Marke>/brand.json — Palette, Typografie, Stimme/Ton-Zusammenfassung
  • brands/<Marke>/css-variables.json — ALLE CSS-Variablen von der Live-Site
  • brands/<Marke>/reference.png — Screenshot der Startseite

Extrahiere die beiden festgelegten Farben, die alle nachgelagerten Stufen steuern:

  • bg: Hintergrundfarbe der Marke (typischerweise nahe Schwarz, z. B. #050508)
  • accent: Signalfarbe der Marke (typischerweise eine gesättigte Nuance, z. B. #8b9cf7)

Diese werden zu Substitutionen in B-Roll-Prompts und in styles/brand.css.

Stufe 2 — Website lesen, Unternehmen verstehen

Verwende WebFetch, um die Startseite + wichtige Seiten (Leistungen, Team, Preise, Über uns) zu lesen. Synthetisiere:

  • Was sie verkaufen
  • An wen sie verkaufen (ICP)
  • Die 1–2 schärfsten Unterscheidungsmerkmale
  • Den gewünschten CTA (Beratung buchen, Testversion starten usw.)

Dies wird die Substanz des Skripts.

Stufe 3 — Skript

Schreibe ein Skript für die gewünschte Dauer. Temporegeln: ~2,7 Wörter pro Sekunde Stimme (multilingual_v2 Kadenz). Also 22s ≈ 60 Wörter; 45s ≈ 120 Wörter; 60s ≈ 160 Wörter.

Struktur (5-Szenen-Vorlage bei 22s; proportional für längere skalieren):

  1. Aufhänger (10–15 % der Dauer) — knackige 3–6-Wort-Zeile
  2. Körper 1 — Problem (~30 %) — was ist kaputt / der Engpass
  3. Körper 2 — Statistik oder Beweis (~15 %) — die Größenordnung (B-Roll mit Vorlage 2 Diagramm)
  4. Körper 3 — Wie wir arbeiten (~25 %) — das Unterscheidungsmerkmal
  5. Ende / CTA (~15 %) — Einladung + Marken-Logo

Für längere Videos (45s+) füge zwischen Körper 1 und Körper 2 zusätzliche Körperszenen hinzu (z. B. "Körper 1a — Spezifischer Schmerzpunkt", "Körper 1b — Kosten der Untätigkeit").

Prosodie für 11Labs eleven_multilingual_v2: Zeichensetzung steuert das Tempo (Kommas = Mikropausen, Punkte = vollständige Pausen, Gedankenstriche = Puls). Mache dir keine Gedanken über SSML oder Emotions-Tags – multilingual_v2 beachtet sie nicht. Schreibe einfach einen konversationellen Prosastil mit natürlicher Zeichensetzung.

Speichere das Skript zur Nachverfolgbarkeit in template-16x9/script.txt.

Stufe 4 — Stimme (11Labs)

Rufe 11Labs TTS mit eleven_multilingual_v2 auf. Standardstimme: $ELEVENLABS_VOICE_ID aus .env (oder was der Benutzer angibt / die Marke bevorzugt — frage bei Unklarheiten nach).

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_ID" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"<Skript>","model_id":"eleven_multilingual_v2"}' \
  --output assets/voice_raw.mp3

Nachbearbeitung der Lautstärke auf 92 % mittels FFmpeg (Pipeline-Standard):

ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3

Stufe 5 — Avatar (HeyGen)

Wähle eine talking_photo_id (Look-ID). Die Standardeinstellung stammt aus $HEYGEN_TALKING_PHOTO_ID in .env (jeder Talking-Photo-Look in deinem HeyGen-Konto).

Setze immer use_avatar_v_model: true auf Charakterebene. HeyGen fällt stillschweigend auf Avatar IV zurück, wenn der Look nicht für V aktiviert ist (ein nicht aktivierter Look fällt auf IV zurück; das Rendern ist nicht betroffen).

Audio hochladen → Talking-Photo-Render einreichen → Abfragen → Herunterladen → Chroma-Key:

# Audio hochladen
AUDIO_ID=$(curl -s -X POST "https://upload.heygen.com/v1/asset" \
  -H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: audio/mpeg" \
  --data-binary @assets/voice.mp3 | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['id'])")

# Render einreichen
VID=$(curl -s -X POST "https://api.heygen.com/v2/video/generate" \
  -H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<EOF | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['video_id'])"
{
  "video_inputs": [{
    "character": {
      "type": "talking_photo",
      "talking_photo_id": "$HEYGEN_TALKING_PHOTO_ID",
      "use_avatar_v_model": true
    },
    "voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
    "background": { "type": "color", "value": "#00FF00" }
  }],
  "dimension": { "width": 720, "height": 1280 }
}
EOF
)

# Abfragen, bis abgeschlossen (normalerweise 60–90s für IV, 5–20min für V beim ersten Render mit neuem Look)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# Dann data.video_url nach assets/avatar_green.mp4 herunterladen

Stufe 6 — Chroma-Key + symmetrisches Padding

Konvertiere HeyGen-Greenscreen-MP4 in transparentes VP9-Webm mit 0,5s Standbild-Pad an beiden Enden:

# Chromakey + Despill → rohes transparentes webm
ffmpeg -y -i avatar_green.mp4 \
  -vf "chromakey=0x00FF00:0.10:0.05,despill=type=green:mix=0.6:expand=0" \
  -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
  avatar.raw.webm

# Beide Enden mit 0,5s Standbildern auffüllen (bewahrt Alpha)
ffmpeg -y -c:v libvpx-vp9 -i avatar.raw.webm \
  -vf "tpad=start_duration=0.5:start_mode=clone:stop_duration=0.5:stop_mode=clone" \
  -c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
  avatar.webm

Padde voice.mp3 symmetrisch mit 0,5s Stille an beiden Enden, damit Audio-Offsets mit dem Avatar-Timing übereinstimmen:

ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 0.5 -c:a libmp3lame -b:a 192k silence.mp3
ffmpeg -y -f concat -safe 0 -i <(printf "file '%s/silence.mp3'\nfile '%s/voice_raw.mp3'\nfile '%s/silence.mp3'\n" "$PWD" "$PWD" "$PWD") \
  -c:a libmp3lame -b:a 192k voice.mp3

Damit wird die Timing-Regel erreicht: Avatar erscheint → Sprache beginnt → Sprache endet → Avatar blendet aus. (Die Regel lautet 0,5s Vorlauf + 0,5s Nachlauf, alle GSAP-Szenen-Hinweise um +0,5s verschoben, endgültiges Ausblenden beginnt 0,1s nach Sprachende).

Stufe 7 — Objekt-Positionskalibrierung

Die Gesichtsposition des Avatars im Frame hängt vom Quellfoto ab, daher pro Look-ID neu kalibrieren:

ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png

Lies den Frame, messe die y-Koordinate der Gesichtsmitte (im 1280 hohen Quellmaterial). Berechne object-position pro Layout:

object_position_y_pct = ( (gesicht_y_px / 1280) * skalierte_hoehe_fuer_layout - layout_slot_hoehe/2 ) / (skalierte_hoehe_fuer_layout - layout_slot_hoehe) * 100

In der Praxis: Gesicht im oberen Drittel des Frames (face_y ~380) → verwende '50% 30%' für schmale Slots, '50% 50%' für Vollbild-Slots. Aktualisiere LAYOUT_AVATAR_SLOTS in index.html. Nie raten — immer aus einem extrahierten Frame kalibrieren.

Stufe 8 — B-Roll-Bilder (Nano Banana 2 über KIE.AI)

Zwei festgelegte Vorlagen. Markenfarben werden pro Projekt getauscht (ersetze BG_HEX und ACCENT_HEX aus brand.json).

Vorlage 1 — Reine abstrakte Skulptur (Atmosphäre, Stimmung, narrative Beats):

Abstrakter 3D-skulpturaler Render auf einem einfarbigen [BG_HEX]-Hintergrund. [FORM_BESCHREIBUNG], suggeriert [BEWEGUNGSABSICHT]. [ACCENT_HEX] Licht bricht sich durch und um die Form mit subkutaner Streuung, wirft weiche Kaustiken auf einen subtil reflektierenden dunklen Boden. Sanfte gerichtete Studiolichtsetzung. Hyperrealer Octane-Render. Ästhetik einer Premium-Tech-Keynote. Scharfer Fokus auf die zentrale Form, Tiefenabfall in den Schatten an den Rändern. Kein Text, keine Logos.

Vorlage 2 — Glasdiagramm (für jede Zeile, die auf eine Statistik, einen Vergleich, Wachstum, ein Verhältnis, "X×", "Y%" verweist):

Abstrakte 3D-Datenvisualisierung auf einem einfarbigen [BG_HEX]-Hintergrund. [DIAGRAMM_TYP] vollständig als schwebende durchscheinende Glasformen gerendert, die [DATEN_KONZEPT] darstellen. Basiselemente in mattem Grauglas; Fokuselemente leuchten mit [ACCENT_HEX] subkutaner Streuung und Brechung, werfen weiche Kaustiken auf einen subtil reflektierenden dunklen Boden. Eine dünne, gebrochen-weiße Achsenlinie. Sanfte gerichtete Studiolichtsetzung. Hyperrealer Octane-Render. Ästhetik einer Premium-Tech-Keynote. Minimale redaktionelle Komposition mit großzügigem Negativraum. Kein Text, keine Zahlen, keine Beschriftungen, keine Logos.

Entscheidungsregel pro Szene: Wenn die Skriptzeile eine Zahl/Statistik/einen Vergleich zitiert → Vorlage 2. Sonst → Vorlage 1.

Einreichungsmuster (1:1-Seitenverhältnis Standard; jedes Seitenverhältnis unterstützt). Erfasse immer HTTP-Code + Body, damit 4xx-Fehler sich selbst diagnostizieren:

source .env && RESPONSE=$(curl -sS -w "\nHTTP_CODE:%{http_code}" -X POST "https://api.kie.ai/api/v1/playground/createTask" \
  -H "Authorization: Bearer $KIE_AI_API_KEY" -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{"model":"nano-banana-2","input":{"prompt":"<VORLAGE MIT GEFÜLLTEN SLOTS>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "KIE-Einreichung fehlgeschlagen — siehe Body oben"; exit 1; }

Frage alle 4s https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> ab, bis data.state == "success", parst data.resultJson (es ist ein JSON-String — json.loads() darauf), lade die URL nach assets/broll-N.png herunter.

Führe mehrere B-Roll-Generierungen parallel aus – KIE.AI verarbeitet gleichzeitige Aufgaben gut.

Häufige 400-Ursache: Prompt-Sicherheitsfilter. Nano Banana 2 lehnt Prompts ab, die als rechtlich/gewalt/konfliktbezogen gelesen werden (z. B. "Gerichtssaal", "Rechtsstreit", "Kläger vs. Beklagte"). Bleibe streng innerhalb der beiden abstrakten Vorlagen — kodiere Bedeutung in Geometrie/Farbe, niemals im wörtlichen Motiv. Getestet am 28.04.2026: Minimaler abstrakter Test gibt 200 mit derselben Auth/Schema zurück, also ist eine 400 hier praktisch immer Prompt-Inhalt.

Stufe 9 — Musik-Hintergrund (11Labs Music)

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "prompt": "<MUSIK_PROMPT>",
    "music_length_ms": 22000,
    "force_instrumental": true,
    "model_id": "music_v1"
  }' --output assets/music_raw.mp3

Gibt Audio-Bytes synchron zurück. music_length_ms entspricht der Kompositionsdauer (3000–600000 ms Bereich).

Standard-Musik-Prompt für B2B-Werbe-Unterlegung (getestet am 27.04.2026):

Fröhlich optimistische instrumentale Unterlegung für einen B2B-Geschäfts-Werbespot. Helles modernes Klavier spielt ein vorwärtsbewegtes rhythmisches Muster mit knackigen Staccato-Noten, gepaart mit subtilen erhebenden Synth-Pads. Leichter sanfter Puls – sanfte Shaker oder gedämpfte rhythmische Klicks, die stetigen Vorwärtsimpuls geben. Keine großen Drums, keine Kicks, keine Crash-Becken, keine Becken. Kein Gesang. Selbstbewusstes, peppiges, energiegeladenes, optimistisches Gefühl. Modern, sauber, technikaffin, professionell, zeitgenössisch unternehmerisch. Tempo um 115 BPM. Helle Dur-Tonart, sonnig, aber nicht kitschig. Gleichmäßige Dynamik durchgehend – keine Wellen, keine Abfälle, keine Höhepunkte, keine Ausblendungen – aber mit stetigem rhythmischem Schwung. Klingt wie die Unterlegung eines modernen SaaS-Produkteinführungsvideos.

Anti-Patterns, die im Prompt vermieden werden sollten:

  • "Cinematic" / "moody" / "ambient" → erzeugt sentimentale Schwere, falsch für Werbespot
  • Tempo unter 90 BPM → zu schläfrig
  • Erwähnung von Wellen, Höhepunkten, Dynamikänderungen → konkurriert mit der Stimme
  • "kein Gesang" vergessen → ElevenLabs könnte Summen hinzufügen

Mische auf -20 dB mit kurzen Ein-/Ausblendungen, damit es unsichtbar unter der Stimme liegt:

ffmpeg -y -i music_raw.mp3 \
  -af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<Ende-0.6>:d=0.6" \
  -c:a libmp3lame -b:a 192k music.mp3

Stufe 10 — Kompositionszusammenstellung

Die Datei template-16x9/index.html ist die Arbeitskomposition. Für jeden Render:

  1. Aktualisiere data-duration auf Wurzel-, Sprach-, Avatar- und Musik-Elementen, um der Ziellänge zu entsprechen
  2. Aktualisiere Markenfarben in styles/brand.css (Vars --bg, --accent usw.)
  3. Aktualisiere Schriftarten in brand.css, wenn die Marke andere Familien verwendet
  4. Passe das Timing der Szenenübergänge in der GSAP-Timeline an die Skript-Beats an
  5. Stelle sicher, dass alle 4 zeitgesteuerten Elemente (Avatar-Video, Sprach-Audio, Musik-Audio, Wurzelkomposition) ausgerichtete data-start- und data-duration-Werte haben

Audio-Track-Indizes: avatar=1, voice=2, music=3. Alle class="clip". Alle data-start="0".

Stufe 11 — Rendern

cd "$PIPELINE_ROOT/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<Marke>-v<n>.mp4

KRITISCH: Führe den Render im Vordergrund aus. Hintergrundmodus-Render hängen bei 0 % CPU, nachdem die Frame-Erfassung beginnt. Verwende einen Vordergrund-Bash-Aufruf mit timeout: 300000. Der Render dauert ~1–2 Minuten für eine 22s-Komposition, ~3–4 Minuten für 45s.

Nach Abschluss des Renders: open -a "QuickTime Player" renders/<Marke>-v<n>.mp4 zur Überprüfung.


Iterationsschleife

Die meisten Render benötigen 1–3 Durchläufe:

  • v1: Die Kette mit sinnvollen Standardeinstellungen von Ende zu Ende zum Laufen bringen
  • v2: Offensichtliche Probleme beheben (Gesichtszuschnitt, zu laute Musik, falsche Übergänge)
  • v3+: Feinschliff von Beats, Prompt-Exploration, Musik-Stilwechsel – aber immer zuerst die mechanische Korrektheit sicherstellen

Verwende bei Problemen mit einem bestimmten Schritt echo-Anweisungen und überprüfe die Ausgabe jedes Schritts, bevor du fortfährst. Die Pipeline ist deterministisch und debugbar.


Fehlerbehebungshinweise

| Symptom | Wahrscheinlichste Ursache | |---|---|---| | HeyGen-Video ist grün | Chroma-Key-Schritt übersprungen oder fehlgeschlagen; überprüfe avatar_green.mp4 | | Avatar erscheint zu früh oder zu spät | data-start-Offset oder Padding inkompatibel; überprüfe voice.mp3-Länge vs. avatar.webm-Länge | | B-Roll-Bild ist schwarzer Bildschirm | Nano Banana Sicherheitsfilter (Prompt zu wörtlich); verwende abstrakte Formulierung neu | | Musik überlagert Stimme | Musik-Lautstärke nicht auf -20 dB reduziert; überprüfe music.mp3-Pegel | | HyperFrames Render hängt bei 0 % | Render im Hintergrund gestartet; verwende Vordergrund mit Timeout |

API-Kontingentverwaltung

  • KIE.AI (Nano Banana): ~1–2 Credits pro Bild. ~5 Bilder pro Video. Überwache unter https://console.kie.ai.
  • ElevenLabs (Stimme + Musik): Stimme ~0,3 Zeichen/Sekunde; Musik 1 Credit/Sekunde.
  • HeyGen (Avatar): ~1–2 Credits pro Render, abhängig von der Dauer.

Für die Entwicklung empfehlen wir, mit 22s-Videos zu beginnen, um Kosten zu minimieren. Ein komplettes Video kostet etwa 50–100 Credits, abhängig von der Plattform.


Nächste Schritte für die Produktion

  1. Stufe 0-Aufgabe: Kopiere template-16x9/ in brands/<Marke>/composition/ für echten Multi-Tenant-Betrieb (aktuell werden Assets pro Render vor Ort getauscht)
  2. Automatische Bilderkennung: Ersetze die manuelle Position-Extraktion durch ein Modell (z. B. MediaPipe Face Mesh), um object-position programmatisch zu setzen
  3. Skript-Vorlagen: Erstelle eine Bibliothek mit Szenenvorlagen für gängige B2B-Narrative (Pain-Point, Vergleich, Vision-ähnlich)
  4. A/B-Test-Unterstützung: Variiere Avatar-Look, Musik-Stil oder B-Roll-Stil pro Video und verfolge Engagement-Metriken

Verwandte Skills