Pipeline HyperFrames — Vidéos Explicatives Multi-Tenants
Pipeline de bout en bout qui prend une URL et produit une vidéo explicative/promotionnelle de marque au format MP4. Construit et validé sur ColdStart (coldstartb2b.com). Conçu pour passer à l'échelle sur n'importe quelle marque B2B avec une configuration minimale par tenant.
Quand l'utiliser
- 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 ça sur "
Environnement requis (dans <votre-dossier-projet>/.env)
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
Structure du projet
<votre-dossier-projet>/
marques/
<marque>/ # un dossier par marque (créé par brand-book)
brand.json
couleurs.md
typographie.md
voix-ton.md
reference.png
template-16x9/ # la composition active (un seul dossier de travail ; on échange les assets par rendu)
index.html
styles/
brand.css # interface de marque — seul fichier avec CSS spécifique à la marque
template.css # mouvement générique
layouts.css # système de 10 dispositions
assets/
voice.mp3 # sortie 11Labs (avec padding)
avatar.webm # sortie HeyGen (incrusté et avec padding)
music.mp3 # musique de fond 11Labs
broll-*.png # images B-roll Nano Banana
rendus/
Pour la production multi-tenants, l'étape 0 à venir devrait copier template-16x9/ par marque. Pour l'instant, on échange les assets sur place par rendu.
Étapes du pipeline
Étape 1 — Extraction de la marque
Invoquez la compétence brand-book sur l'URL cible. Elle produit :
marques/<marque>/brand.json— palette, typographie, résumé voix/tonmarques/<marque>/css-variables.json— TOUTES les variables CSS du site en lignemarques/<marque>/reference.png— capture d'écran de la page d'accueil
Récupérez les deux couleurs verrouillées qui pilotent chaque étape suivante :
bg: couleur de fond de la marque (généralement quasi-noir, ex.#050508)accent: couleur de signal de la marque (généralement une teinte saturée, ex.#8b9cf7)
Elles deviennent des substitutions dans les prompts B-roll et dans styles/brand.css.
Étape 2 — Lire le site, comprendre l'activité
Utilisez WebFetch pour lire la page d'accueil + les pages clés (services, équipe, tarifs, à propos). Synthétisez :
- Ce qu'ils vendent
- À qui ils vendent (ICP)
- Les 1-2 différenciateurs les plus forts
- Le CTA souhaité (réserver un appel, essai gratuit, etc.)
Cela devient la substance du script.
Étape 3 — Script
Écrivez un script pour la durée demandée. Règle de débit : ~2,7 mots par seconde de voix (cadence multilingual_v2). Donc 22s ≈ 60 mots ; 45s ≈ 120 mots ; 60s ≈ 160 mots.
Structure (modèle en 5 scènes pour 22s ; adaptez proportionnellement pour les durées plus longues) :
- Accroche (10–15% de la durée) — ligne percutante de 3 à 6 mots
- Corps 1 — Problème (~30%) — ce qui ne va pas / le goulot d'étranglement
- Corps 2 — Statistique ou preuve (~15%) — l'ampleur (utilisez le Template 2 de graphique 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+), ajoutez des scènes Corps supplémentaires entre Corps 1 et Corps 2 (ex. "Corps 1a — Point de douleur 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 cadratins = temps). Ne vous embêtez pas avec SSML ou des balises d'émotion — multilingual_v2 ne les honore pas. Écrivez simplement une prose conversationnelle avec une ponctuation naturelle.
Enregistrez le script dans template-16x9/script.txt pour la traçabilité.
Étape 4 — Voix (11Labs)
Appelez la TTS de 11Labs avec eleven_multilingual_v2. Voix par défaut : <votre-voice-id-elevenlabs> (définissez-la sur une voix de votre bibliothèque 11Labs, ou selon ce que l'utilisateur spécifie / la marque préfère — demandez si ce n'est pas clair).
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/<votre-voice-id-elevenlabs>" \
-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-traitez le volume à 92% via FFmpeg (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)
Choisissez un talking_photo_id (ID Look). Définissez votre valeur par défaut sur un Look de votre propre compte HeyGen : <votre-talking-photo-id-heygen>.
Définissez toujours use_avatar_v_model: true au niveau du personnage. HeyGen basculera silencieusement vers Avatar IV si le Look n'est pas inscrit au modèle V (le rendu Avatar IV fonctionne très bien).
Téléchargez la voix → soumettez le rendu talking_photo → interrogez → téléchargez → incrustation chromakey :
# Télécharger 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": "<votre-talking-photo-id-heygen>",
"use_avatar_v_model": true
},
"voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
"background": { "type": "color", "value": "#00FF00" }
}],
"dimension": { "width": 720, "height": 1280 }
}
EOF
)
# Interroger jusqu'à complétion (généralement 60-90s pour IV, 5-20min pour V au premier rendu avec un nouveau Look)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# Puis télécharger data.video_url vers assets/avatar_green.mp4
Étape 6 — Incrustation chromakey + padding symétrique
Convertissez le MP4 fond vert HeyGen → webm transparent en VP9 avec 0,5s d'image fixe aux deux extrémités :
# Incrustation + 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
# Ajouter 0.5s d'images fixes aux deux extrémités (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
Ajoutez symétriquement 0,5s de silence à voice.mp3 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 respecte la règle de timing : l'avatar apparaît → la parole commence → la parole s'arrête → l'avatar disparaît. Voir project_audio_video_timing.md (créé à l'Étape 9 si manquant — la règle est 0,5s d'avance + 0,5s de retard, tous les repères de scène GSAP décalés de +0,5s, le fondu de sortie final commence 0,1s après la fin de la parole).
Étape 7 — Calibrage de la position objet
La position du visage de l'avatar dans le cadre dépend de la photo source, donc recalibrez par ID Look :
ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png
Lisez l'image, mesurez la coordonnée y du centre du visage (dans la source de 1280px de haut). Calculez object-position par disposition :
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 de l'image (face_y ~380) → utilisez '50% 30%' pour les emplacements étroits, '50% 50%' pour les emplacements plein écran. Mettez à jour LAYOUT_AVATAR_SLOTS dans index.html. Ne devinez jamais — calibrez toujours à partir d'une image extraite.
Étape 8 — Images B-roll (Nano Banana 2 via KIE.AI)
Deux modèles verrouillés — voir project_image_direction_templates.md pour les versions complètes. Les couleurs de la marque changent par projet (remplacez BG_HEX et ACCENT_HEX depuis brand.json).
Modèle 1 — Sculpture abstraite pure (ambiance, mood, rythme narratif) :
Rendu sculptural 3D abstrait sur fond uni
[BG_HEX].[FORM_DESCRIPTION], suggérant[MOTION_INTENT]. La lumière[ACCENT_HEX]se réfracte à travers et autour de la forme avec diffusion sous-cutanée, projetant de douces caustiques sur un sol sombre subtilement réfléchissant. Éclairage studio directionnel doux. Rendu Octane hyperréaliste. Esthétique keynote tech premium. Mise au point nette sur la forme centrale, perte de profondeur dans l'ombre sur les bords. Pas de texte, pas de logos.
Modèle 2 — Diagramme en verre (toute ligne mentionnant 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 mat gris atténué ; éléments focaux brillants avec diffusion sous-cutanée et réfraction de couleur[ACCENT_HEX], projetant de douces caustiques sur un sol sombre subtilement réfléchissant. Une fine ligne d'axe blanc cassé. Éclairage studio directionnel doux. Rendu Octane hyperréaliste. Esthétique keynote tech premium. Composition éditoriale minimaliste 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 (ratio 1:1 par défaut ; tout ratio supporté). Capturez toujours 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":"<TEMPLATE AVEC EMPLACEMENTS REMPLIS>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "La soumission KIE a échoué — voir le corps ci-dessus"; exit 1; }
Interrogez https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> toutes les 4s jusqu'à ce que data.state == "success", parsez data.resultJson (c'est une chaîne JSON — json.loads()), téléchargez l'URL vers assets/broll-N.png.
Lancez 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é du prompt. Nano Banana 2 rejette les prompts perçus comme liés au droit/à la violence/au conflit (ex. "salle d'audience", "bataille juridique", "demandeurs contre défendeurs"). Restez strictement dans les deux modèles abstraits — encodez le sens dans la géométrie/la couleur, jamais dans le sujet littéral. Validé le 28-04-2026 : une sonde abstraite minimale renvoie 200 avec la même authentification/schéma, donc un 400 ici est presque toujours dû au contenu du prompt.
É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": "<PROMPT MUSIQUE>",
"music_length_ms": 22000,
"force_instrumental": true,
"model_id": "music_v1"
}' --output assets/music_raw.mp3
Retourne les octets audio de manière synchrone. music_length_ms correspond à la durée de la composition (plage 3000–600000ms).
Prompt musical par défaut pour la bande-son de publireportage B2B (validé le 27-04-2026) :
Musique instrumentale optimiste et entraînante pour un publireportage B2B. Piano moderne lumineux jouant un motif rythmique vers l'avant avec des notes staccato nettes, associé à des nappes synthétiques subtiles et édulcorées. Pouls léger et doux — shakers discrets ou clics rythmiques étouffés donnant une impulsion constante vers l'avant. Pas de grosses batteries, pas de kicks, pas de crashs, pas de cymbales. Pas de voix. Sensation confiante, enjouée, énergique, optimiste. Moderne, propre, tourné vers la technologie, professionnel, corporate contemporain. Tempo autour de 115 BPM. Tonalité majeure lumineuse, ensoleillée mais pas sirupeuse. Dynamique uniforme tout au long — pas de montées, pas de descentes, pas de climax, pas de fondus — mais avec un élan rythmique régulier. Sonne comme la musique de fond d'une vidéo de lancement de produit SaaS moderne.
Anti-patrons à éviter dans le prompt :
- "Cinématique" / "mélancolique" / "ambiant" → produit une traînée sentimentale, inadapté pour un publireportage
- Tempo inférieur à 90 BPM → trop endormant
- Mentionner des montées, climax, changements de dynamique → concurrence la voix
- Oublier "pas de voix" → ElevenLabs peut ajouter des fredonnements
Mixez à -20dB avec de brefs fondus pour qu'elle s'intègre 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 :
- Mettez à jour
data-durationsur les éléments racine, voix, avatar et musique pour correspondre à la durée cible - Mettez à jour les couleurs de la marque dans
styles/brand.css(vars--bg,--accent, etc.) - Mettez à jour les polices dans
brand.csssi la marque utilise des familles différentes - Réajustez les transitions de scènes dans la timeline GSAP pour correspondre au rythme du script
- Assurez-vous que les 4 éléments minutés (vidéo avatar, audio voix, audio musique, composition racine) ont des
data-startetdata-durationalignés
Indices des pistes audio : avatar=1, voix=2, musique=3. Tous avec class="clip". Tous avec data-start="0".
Étape 11 — Rendu
cd "$HOME/<votre-dossier-projet>/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output rendus/<marque>-v<n>.mp4
CRITIQUE : Exécutez le rendu en premier plan. Les rendus en arrière-plan se bloquent à 0% CPU après le début de la capture d'images. Utilisez un appel Bash en premier plan avec timeout: 300000. Le rendu prend ~1–2 min pour une composition de 22s, ~3–4 min pour 45s.
Une fois le rendu terminé, open -a "QuickTime Player" rendus/<marque>-v<n>.mp4 pour la révision.
Boucle d'itération
La plupart des rendus nécessitent 1 à 3 passages :
- v1 : faire fonctionner la chaîne de bout en bout avec des valeurs par défaut sensées
- v2 : corriger les problèmes évidents (recadrage du visage, musique trop forte, problèmes de transitions, etc.)
- v3 : peaufiner le script, remplacer des images B-roll spécifiques, ajuster le volume de la musique
Il n'est pas attendu qu'une passe unique produise un résultat parfait — optimisez pour un cycle d'itération rapide.
Considérations multi-tenants
À l'avenir, l'Étape 0 créera des copies de template-16x9/ par marque. Pour l'instant, le pipeline modifie les assets du répertoire template-16x9/ en place. Cela signifie que les rendus pour différentes marques ne peuvent pas être exécutés simultanément sans conflit.
La structure marques/<marque>/ sert de source de vérité pérenne. Une fois qu'une marque est extraite, les rendus futurs peuvent être régénérés sans réexécuter l'Étape 1.
Notes techniques
- 11Labs
eleven_multilingual_v2: ne prend pas en charge SSML ou les balises d'émotion. Utilisez uniquement la ponctuation naturelle pour le rythme. - Nano Banana 2 : filtre les prompts à connotation violente/juridique. Restez dans les deux modèles abstraits.
- Avatars HeyGen : les nouveaux Looks peuvent nécessiter 5 à 20 minutes pour le premier rendu V-Model. Les rendus ultérieurs prennent ~60-90s.
- Timelines GSAP : tous les indices temporels sont en secondes. La propriété
data-durationsur l'élément racine contrôle la durée totale. - Pistes audio : la composition attend exactement 3 pistes audio (avatar, voix, musique) avec des indices spécifiques (1, 2, 3).
Débogage
- Erreur 400 de KIE : presque toujours déclenchée par le filtre de contenu du prompt. Utilisez un langage abstrait.
- Avatar non affiché : vérifiez que
object-positionest calibré pour le visage de l'avatar. - Décalage audio : vérifiez que le fichier
voice.mp3a un padding de 0,5s aux deux extrémités. - Le rendu se bloque à 0% CPU : assurez-vous que la commande de rendu est exécutée en premier plan, pas en arrière-plan.
Documentation du pipeline HyperFrames — Dernière mise à jour : 2026-04-28