Pipeline HyperFrames — Vidéos explicatives de marque multi-locataire
Pipeline de bout en bout qui prend une URL et produit une vidéo MP4 explicative/promotionnelle de marque terminée. Construit et validé sur ColdStart (coldstartb2b.com). Conçu pour s'adapter à n'importe quelle marque B2B avec une configuration minimale par locataire.
Quand invoquer
- L'utilisateur dit "Hyper Frames" / "hyperframes" + une URL ou un nom de marque
- L'utilisateur demande une vidéo explicative/promotionnelle pour une entreprise spécifique
- L'utilisateur dit "fais une vidéo pour " ou similaire
- L'utilisateur dit "essayons ceci sur "
Environnement requis (dans $PIPELINE_ROOT/.env — copier .env.example)
KIE_AI_API_KEY=... # Nano Banana 2 + Seedance 2 via KIE.AI
HEYGEN_API_KEY=... # Génération d'avatar HeyGen
ELEVENLABS_API_KEY=... # Voix + musique 11Labs
ELEVENLABS_VOICE_ID=... # Voix du narrateur par défaut
HEYGEN_TALKING_PHOTO_ID=... # Apparence d'avatar par défaut
Structure du projet
$PIPELINE_ROOT/ # Racine de ce dépôt
brands/
<marque>/ # Un répertoire par marque (créé par brand-book)
brand.json
colors.md
typography.md
voice-tone.md
reference.png
template-16x9/ # La composition active (un seul répertoire de travail ; échanger les assets par marque)
index.html
styles/
brand.css # Interface de marque — seul fichier avec du CSS spécifique à la marque
template.css # Mouvement non lié à la marque
layouts.css # Système de 10 mises en page
assets/
voice.mp3 # Sortie 11Labs (avec padding)
avatar.webm # Sortie HeyGen (incrustation chroma + padding)
music.mp3 # Musique de fond 11Labs
broll-*.png # Images B-roll Nano Banana
renders/
Pour la production multi-locataire, l'étape 0 future devrait copier template-16x9/ par marque. Pour l'instant, échanger les assets sur place par rendu.
Étapes du pipeline
Étape 1 — Extraction de la marque
Invoquer la compétence brand-book sur l'URL cible. Elle produit :
brands/<marque>/brand.json— palette, typographie, résumé de la voix/du tonbrands/<marque>/css-variables.json— TOUTES les variables CSS du site en directbrands/<marque>/reference.png— capture d'écran de la page d'accueil
Extraire les deux couleurs verrouillées qui pilotent chaque étape en aval :
bg: couleur d'arrière-plan de la marque (généralement presque noire, ex.#050508)accent: couleur de signal de la marque (généralement une teinte saturée, ex.#8b9cf7)
Elles deviennent des substitutions dans les invites B-roll et dans styles/brand.css.
Étape 2 — Lire le site, comprendre l'activité
Utiliser WebFetch pour lire la page d'accueil + les pages clés (services, équipe, tarifs, à propos). Synthétiser :
- Ce qu'ils vendent
- À qui ils vendent (ICP)
- Les 1 à 2 différenciateurs les plus marquants
- L'appel à l'action souhaité (réserver un appel, essai gratuit, etc.)
Cela devient la substance du script.
Étape 3 — Script
Rédiger un script pour la durée demandée. Règle de rythme : ~2,7 mots par seconde de voix (cadence multilingue_v2). Donc 22s ≈ 60 mots ; 45s ≈ 120 mots ; 60s ≈ 160 mots.
Structure (modèle 5 scènes à 22s ; adapter proportionnellement pour plus long) :
- Accroche (10–15% de la durée) — une ligne percutante de 3 à 6 mots
- Corps 1 — Problème (~30%) — ce qui est cassé / le goulot d'étranglement
- Corps 2 — Statistique ou preuve (~15%) — l'ampleur (utiliser un graphique du modèle 2 pour le B-roll)
- Corps 3 — Comment nous travaillons (~25%) — le différenciateur
- Fin / CTA (~15%) — invitation + logo de la marque
Pour les vidéos plus longues (45s+), ajouter des scènes Corps supplémentaires entre le Corps 1 et le Corps 2 (par ex. "Corps 1a — Point douloureux spécifique", "Corps 1b — Coût de l'inaction").
Prosodie pour 11Labs eleven_multilingual_v2 : la ponctuation pilote le rythme (virgules = micro-pauses, points = pauses complètes, tirets longs = battement). Ne pas s'encombrer avec des balises SSML ou d'émotion — multilingue_v2 ne les honore pas. Écrire simplement une prose conversationnelle avec une ponctuation naturelle.
Sauvegarder le script dans template-16x9/script.txt pour traçabilité.
Étape 4 — Voix (11Labs)
Appeler la TTS 11Labs avec eleven_multilingual_v2. Voix par défaut : $ELEVENLABS_VOICE_ID depuis .env (ou celle que l'utilisateur spécifie / que la marque préfère — demander en cas de doute).
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":"<script>","model_id":"eleven_multilingual_v2"}' \
--output assets/voice_raw.mp3
Post-traiter le volume à 92% via FFmpeg (le standard du pipeline) :
ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3
Étape 5 — Avatar (HeyGen)
Choisir un talking_photo_id (ID Look). La valeur par défaut vient de $HEYGEN_TALKING_PHOTO_ID dans .env (n'importe quel Look de photo parlante dans votre compte HeyGen).
Toujours définir use_avatar_v_model: true au niveau du personnage. HeyGen reviendra silencieusement à Avatar IV si le Look n'est pas inscrit au V (un Look non inscrit revient à IV ; le rendu n'est pas affecté).
Uploader la voix → soumettre le rendu talking_photo → sonder → télécharger → incrustation chroma :
# Uploader l'audio
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'])")
# Soumettre le rendu
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
)
# Sonder jusqu'à complétion (généralement 60–90s pour IV, 5–20min pour V lors du premier rendu avec un nouveau Look)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# Ensuite télécharger data.video_url vers assets/avatar_green.mp4
Étape 6 — Incrustation chroma + padding symétrique
Convertir la MP4 fond vert HeyGen → webm VP9 transparent avec 0,5 s d'image figée des deux côtés :
# Chromakey + despill → webm transparent brut
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
# Padder les deux extrémités avec 0,5 s d'images figées (préserve l'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
Padder symétriquement voice.mp3 avec 0,5 s de silence aux deux extrémités pour que les décalages audio correspondent au timing de l'avatar :
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
Cela atteint la règle de timing : l'avatar apparaît → la parole commence → la parole se termine → l'avatar disparaît. (La règle est 0,5 s d'avance + 0,5 s de queue, tous les repères de scène GSAP décalés de +0,5 s, la disparition finale commence 0,1 s après la fin de la parole).
Étape 7 — Calibrage object-position
La position du visage de l'avatar dans le cadre dépend de la photo source, donc recalibrer par ID Look :
ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png
Lire le cadre, mesurer la coordonnée y du centre du visage (dans la source de 1280 de haut). Calculer object-position par mise en page :
object_position_y_pct = ( (face_y_px / 1280) * scaled_height_for_layout - layout_slot_height/2 ) / (scaled_height_for_layout - layout_slot_height) * 100
En pratique : visage dans le tiers supérieur du cadre (face_y ~380) → utiliser '50% 30%' pour les emplacements étroits, '50% 50%' pour les emplacements plein cadre. Mettre à jour LAYOUT_AVATAR_SLOTS dans index.html. Ne jamais deviner — toujours calibrer à partir d'un cadre extrait.
Étape 8 — Images B-roll (Nano Banana 2 via KIE.AI)
Deux modèles verrouillés. Les couleurs de la marque changent par projet (substituer BG_HEX et ACCENT_HEX depuis brand.json).
Modèle 1 — Sculpture abstraite pure (atmosphère, ambiance, temps narratifs) :
Rendu sculptural 3D abstrait sur fond uni
[BG_HEX].[FORM_DESCRIPTION], évoquant[MOTION_INTENT]. La lumière[ACCENT_HEX]se réfracte à travers et autour de la forme avec diffusion sous-surface, projetant des caustiques douces sur un sol sombre subtilement réfléchissant. Éclairage studio directionnel doux. Rendu Hyperreal Octane. Esthétique premium de keynote technique. Mise au point nette sur la forme centrale, profondeur s'atténuant dans l'ombre sur les bords. Pas de texte, pas de logos.
Modèle 2 — Graphique en verre (toute ligne faisant référence à une statistique, comparaison, croissance, ratio, "X×", "Y%") :
Visualisation de données 3D abstraite sur fond uni
[BG_HEX].[CHART_TYPE]entièrement rendu comme des formes de verre translucides flottantes représentant[DATA_CONCEPT]. Éléments de base en verre gris mat sourd ; éléments focaux brillants de diffusion sous-surface[ACCENT_HEX]et réfraction, projetant des caustiques douces sur un sol sombre subtilement réfléchissant. Une fine ligne d'axe blanc cassé. Éclairage studio directionnel doux. Rendu Hyperreal Octane. Esthétique premium de keynote technique. Composition éditoriale minimale avec beaucoup d'espace négatif. Pas de texte, pas de chiffres, pas d'étiquettes, pas de logos.
Règle de décision par scène : si la ligne de script cite un nombre/statistique/comparaison → Modèle 2. Sinon → Modèle 1.
Modèle de soumission (format 1:1 par défaut ; tout format supporté). Toujours capturer le code HTTP + le corps pour que les échecs 4xx s'auto-diagnostiquent :
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":"<MODÈLE AVEC EMPLACEMENTS REMPLIS>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "Échec de soumission KIE — voir le corps ci-dessus"; exit 1; }
Sonder https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> toutes les 4s jusqu'à ce que data.state == "success", analyser data.resultJson (c'est une chaîne JSON — json.loads() la), télécharger l'URL vers assets/broll-N.png.
Exécuter plusieurs générations B-roll en parallèle — KIE.AI gère bien les tâches concurrentes.
Cause fréquente de 400 : filtre de sécurité des invites. Nano Banana 2 rejette les invites qui ressemblent à du contenu légal/violence/conflit (ex. "salle d'audience", "bataille juridique", "demandeurs vs défendeurs"). Rester strictement dans les deux modèles abstraits — encoder le sens dans la géométrie/couleur, jamais dans un sujet littéral. Validé le 28/04/2026 : une sonde abstraite minimale renvoie 200 avec la même auth/schéma, donc un 400 ici est pratiquement toujours un contenu d'invite.
Étape 9 — Musique de fond (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": "<INVITE MUSIQUE>",
"music_length_ms": 22000,
"force_instrumental": true,
"model_id": "music_v1"
}' --output assets/music_raw.mp3
Renvoie les octets audio de manière synchrone. music_length_ms correspond à la durée de la composition (plage 3000–600000ms).
Invite musicale par défaut pour la musique de fond publicitaire B2B (validée le 27/04/2026) :
Souligné instrumental optimiste et entraînant pour une publicité B2B. Piano moderne brillant jouant un motif rythmique vers l'avant avec des notes staccato nettes, associé à des nappes de synthé subtilement exaltantes. Pouls léger et doux — shakers discrets ou clics rythmiques feutrés fournissant une impulsion régulière vers l'avant. Pas de grosses batteries, pas de coups de pied, pas de crashs, pas de cymbales. Pas de voix. Sentiment confiant, vif, énergique, optimiste. Moderne, propre, axé technologie, professionnel, d'entreprise contemporain. Tempo autour de 115 BPM. Tonalité majeure lumineuse, ensoleillée mais pas sirupeuse. Dynamique constante tout au long — pas de gonflements, pas de chutes, pas d'apogées, pas de fondus — mais avec un élan rythmique régulier. Ressemble à une musique de fond pour une vidéo de lancement de produit SaaS moderne.
Anti-modèles à éviter dans l'invite :
- "Cinématique" / "ténébreux" / "ambiant" → produit un tiraillement sentimental, mauvais pour une publicité
- Tempo inférieur à 90 BPM → trop endormant
- Mentionner des gonflements, apogées, changements de dynamique → concurrence la voix
- Oublier "pas de voix" → ElevenLabs peut ajouter un bourdonnement
Mixer à -20dB avec de brefs fondus pour qu'elle se place invisiblement sous la voix :
ffmpeg -y -i music_raw.mp3 \
-af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<fin-0.6>:d=0.6" \
-c:a libmp3lame -b:a 192k music.mp3
Étape 10 — Assemblage de la composition
Le fichier template-16x9/index.html est la composition de travail. Pour chaque rendu :
- Mettre à jour
data-durationsur les éléments racine, voix, avatar et musique pour correspondre à la longueur cible - Mettre à jour les couleurs de la marque dans
styles/brand.css(variables--bg,--accent, etc.) - Mettre à jour les polices dans
brand.csssi la marque utilise des familles différentes - Ré-ajuster les transitions de scène dans la timeline GSAP pour correspondre aux battements du script
- S'assurer que les 4 éléments chronométrés (vidéo avatar, audio voix, audio musique, composition racine) ont des
data-startetdata-durationalignés
Indices des pistes audio : avatar=1, voice=2, music=3. Tous class="clip". Tous data-start="0".
Étape 11 — Rendu
cd "$PIPELINE_ROOT/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<marque>-v<n>.mp4
CRITIQUE : Exécuter le rendu au premier plan. Les rendus en arrière-plan se bloquent à 0% CPU après le début de la capture d'image. Utiliser un appel Bash au premier plan avec timeout: 300000. Le rendu prend ~1–2 min pour une composition de 22s, ~3–4 min pour 45s.
Après la fin du rendu, open -a "QuickTime Player" renders/<marque>-v<n>.mp4 pour la révision.
Boucle d'itération
La plupart des rendus nécessitent 1 à 3 passes :
- v1: faire fonctionner la chaîne de bout en bout avec des valeurs par défaut acceptables
- v2: corriger les problèmes évidents (recadrage du visage, musique trop forte, transitions décalées)