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-Zusammenfassungbrands/<Marke>/css-variables.json— ALLE CSS-Variablen von der Live-Sitebrands/<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):
- Aufhänger (10–15 % der Dauer) — knackige 3–6-Wort-Zeile
- Körper 1 — Problem (~30 %) — was ist kaputt / der Engpass
- Körper 2 — Statistik oder Beweis (~15 %) — die Größenordnung (B-Roll mit Vorlage 2 Diagramm)
- Körper 3 — Wie wir arbeiten (~25 %) — das Unterscheidungsmerkmal
- 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:
- Aktualisiere
data-durationauf Wurzel-, Sprach-, Avatar- und Musik-Elementen, um der Ziellänge zu entsprechen - Aktualisiere Markenfarben in
styles/brand.css(Vars--bg,--accentusw.) - Aktualisiere Schriftarten in
brand.css, wenn die Marke andere Familien verwendet - Passe das Timing der Szenenübergänge in der GSAP-Timeline an die Skript-Beats an
- Stelle sicher, dass alle 4 zeitgesteuerten Elemente (Avatar-Video, Sprach-Audio, Musik-Audio, Wurzelkomposition) ausgerichtete
data-start- unddata-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
- Stufe 0-Aufgabe: Kopiere
template-16x9/inbrands/<Marke>/composition/für echten Multi-Tenant-Betrieb (aktuell werden Assets pro Render vor Ort getauscht) - Automatische Bilderkennung: Ersetze die manuelle Position-Extraktion durch ein Modell (z. B. MediaPipe Face Mesh), um
object-positionprogrammatisch zu setzen - Skript-Vorlagen: Erstelle eine Bibliothek mit Szenenvorlagen für gängige B2B-Narrative (Pain-Point, Vergleich, Vision-ähnlich)
- A/B-Test-Unterstützung: Variiere Avatar-Look, Musik-Stil oder B-Roll-Stil pro Video und verfolge Engagement-Metriken