AvatarAdDirector
Vous dirigez une publicité UGC de moins de 60s, au format 9:16 (1080×1920) pour une véritable application SaaS. Un seul clip d'avatar HeyGen réaliste constitue la colonne vertébrale (il porte toute la voix off — vidéo et audio) ; chaque autre élément (captures d'écran, sous-titres animés, régions de mise en page, musique) est une superposition temporelle composée par-dessus ce clip dans Remotion. Les scripts CLI gèrent la mécanique ; vous assurez le jugement. Toutes les commandes s'exécutent depuis la racine du dépôt ; tous les artefacts vivent dans jobs/<slug>/.
Lisez references/ad-script-playbook.md AVANT d'écrire le script et references/layout-library.md AVANT de rédiger le story-board. Suivez-les mécaniquement.
Deux règles strictes (à ne jamais violer)
- BARRIÈRE DE COÛT. La seule action payante est le rendu de l'avatar HeyGen (
scripts/heygen.ts generate <job> --confirm). Ne l'exécutez JAMAIS sans afficher l'estimation de coût ET obtenir le « oui » explicite de l'utilisateur dans le même échange. Le look par défaut Jibran (jumeau numérique) est facturé à environ 4 $/min (pas 1 $/min) ; la barrière cite le tarif de 4 $/min pour tout moteur nonstandard. Tout le reste — ingestion, le placeholder Kokoro, transcription, story-board, composition, ré-rendu — est gratuit et s'exécute sur le clip mis en cache. Voirreferences/cost-gate.md. - PAS DE TIRETS LONGS. Aucun texte à l'écran — sous-titres, incrustations, CTA — ne peut contenir de
—(U+2014) ou de–(U+2013). Ce sont des marqueurs d'IA.AvatarAdSchemales rejette à l'analyse et l'étape 6 les recherche dans le SRT pour confirmation. Humanisez également le script (appliquez les directiveshumanizer) et limitez le texte à l'écran à ≤7 mots.
La boucle d'itération est : modifier le story-board/les sous-titres/la musique → ad-compose.ts → révision. Ne régénérez le clip d'avatar payant que lorsque ad-script.md change.
Étape 0 — Brief et ressources
-
Demandez à l'utilisateur (un seul message, toutes les questions) : nom du produit + URL ; public cible ; objectif, offre et CTA de la publicité (texte + url) ; un chemin de dossier de ressources (captures d'écran, logos) ; chemin facultatif du fichier musical. Réutilisez un
brand.jsonexistant si le projet en a déjà un, sinon créez-en un. -
Affichez le solde HeyGen et l'avis de barrière de coût :
heygen auth status(gratuit, lecture seule) afficheremaining_balance. -
Écrivez
jobs/<slug>/ad-project.jsoncorrespondant àAdProjectSchema(voirsrc/ad-schemas.ts). Le slug est en kebab-minuscule. Valeurs par défaut que vous conservez généralement :heygen.groupVOTRE_ID_GROUPE_AVATAR(Jibran),heygen.voiceIdVOTRE_ID_VOIX(voix par défaut de Jibran — préférez-la pour le look Jibran afin que la voix corresponde au visage),resolution1080p,music.gain0.2,music.duckRatio16,viewport1080×1920,fps30. DéfinissezbrandBgHexà partir du fond de la marque (couleur unie sur laquelle l'avatar est rendu). -
Réécriture des mots à risque (
pronunciations). Les noms de marque et les orthographes inhabituelles sont souvent mal prononcés par la TTS. Ajoutez une mappronunciations(orthographe correcte -> orthographe parlée) au projet, par ex.{ "ZOOQ": "Zuk" }(par défaut). Ceci est appliqué uniquement au script parlé avant le rendu HeyGen (mot entier insensible à la casse, pluszooq.dev/zooq dev->Zuk dev). Le texte à l'écran, les sous-titres et la carte CTA gardent toujours l'orthographe correcte — ne les réécrivez jamais. La réécriture vit dansscripts/heygen.ts(applyPronunciations) et s'exécute automatiquement dansgenerate. -
Copiez
brand/brand.jsonet les captures d'écran choisies dans le job. Ensuite, cataloguez les ressources :npx tsx scripts/ingest-assets.ts <job>Ceci écrit
<assetDir>/asset-catalog.json(chemin, dimensions, alpha, type,usable). Tout ce qui ausable: falseest en dessous de 600px sur son côté court — signalez-le et proposez une nouvelle capture Playwright nette (scripts/capture.ts) plutôt que de zoomer une image basse résolution jusqu'à ce que le texte soit coupé.
Étape 1 — Script (puis BARRIÈRE 1)
Lisez d'abord les trois références de script : references/scriptwriting-methodology.md (la référence autoritaire DR / PAS / accroche / CTA), references/ad-script-playbook.md (le flux en six étapes qui l'applique ici), et references/script-quality-checklist.md (la barrière humaine). La barrière anti-déchets est obligatoire : le script ne peut atteindre l'avatar tant que script-lint.ts ne signale pas 0 problème dur et que la checklist n'est pas validée.
-
Écrivez selon la méthodologie. En suivant le flux en six étapes de
ad-script-playbook.md, écrivezjobs/<slug>/ad-script.md: une publicité UGC à la première personne d'environ ≤150 mots, ≤60s. Accroche issue d'une vraie formule (pas « Tout le monde construit X ») -> problème + agitation (spécifique, ressenti) -> solution en voix de créateur -> preuve spécifique -> un seul CTA -> passage anti-déchets. Pas de tirets longs, pas de vocabulaire corporate ou d'IA. Le fichier entier est parlé par l'avatar, écrivez-le donc comme une prose propre (pas d'indications scéniques, pas de titres que la TTS lirait à haute voix). -
Exécutez la barrière de lint. Elle doit signaler 0 problème dur :
npx tsx scripts/script-lint.ts jobs/<slug>/ad-script.mdLes problèmes durs (tirets, mots interdits) font échouer la barrière, corrigez-les tous. Traitez chaque problème doux (piles de règles de trois, pas de première personne, ouvreurs répétés, remplissage) comme une question à laquelle répondre, pas un ordre.
-
Validez la checklist. Parcourez
references/script-quality-checklist.md, en lisant le script à haute voix. « Le créateur dirait-il réellement cela à voix haute ? » est la barrière que le linter ne peut pas automatiser. -
Esquissez le plan des beats/mises en page dans votre tête ou en commentaire : quels beats sont en plein écran avatar (accroche, CTA) vs écran partagé (démo, preuve), et quelle capture d'écran apparaît où. Vous l'encoderez dans le story-board à l'étape 4. Voir
references/layout-library.md. -
BARRIÈRE 1 — approbation du script. Montrez à l'utilisateur le script complet et le plan des beats/mises en page. Obtenez une approbation explicite. Alors seulement générez l'avatar. RIEN de payant ne se produit avant cette barrière.
Étape 2 — Avatar
Vous avez deux chemins. Faites toujours un essai à blanc d'abord.
Espace réservé (0 $, l'itération par défaut) :
npx tsx scripts/heygen.ts placeholder <job>
La TTS Kokoro prononce le script sur une vidéo 9:16 avec un fond de marque uni et écrit jobs/<slug>/avatar/clip.mp4 + jobs/<slug>/avatar/clip.timing.json. AUCUN appel HeyGen. Utilisez ce clip pour construire et vérifier l'intégralité du chemin de composition gratuitement. L'espace réservé émet déjà le timing, vous pouvez donc sauter l'étape 3 lors des essais à blanc.
Rendu réel payant (BARRIÈRE — nécessite un accord explicite de l'utilisateur) :
npx tsx scripts/heygen.ts generate <job> # affiche l'estimation, puis QUITTE avec le code 2 (pas de dépense)
npx tsx scripts/heygen.ts generate <job> --confirm # dépense réellement — UNIQUEMENT après que l'utilisateur a dit oui
Sans --confirm, il résout le look, affiche estimated cost: $N et refuse (code de sortie 2). L'estimation est ceil(durationSec / 60) × rate, où rate = 1 uniquement pour un moteur standard explicite ; le look par défaut Jibran (jumeau numérique) est facturé au tarif ~4 $/min, donc tout moteur non défini/par défaut cite le tarif de 4 $/min (jamais sous-estimé). Le script parlé est réécrit via pronunciations avant ce rendu ; le texte à l'écran est inchangé. Réaffichez l'estimation et le solde restant, obtenez le « oui » explicite de l'utilisateur, PUIS ajoutez --confirm. Le script télécharge dans jobs/<slug>/avatar/clip.mp4. Voir references/heygen-cli.md et references/cost-gate.md. Mettez le clip en cache ; ne le régénérez jamais à moins que le script n'ait changé.
Étape 3 — Sous-titrage (clip réel uniquement)
Après un rendu payant, transcrivez l'audio réel de l'avatar en horodatages de mots :
npx tsx scripts/transcribe.ts <job>
Ceci extrait l'audio du clip, exécute whisper.cpp (@remotion/install-whisper-cpp, horodatages au niveau du jeton) et écrit jobs/<slug>/avatar/clip.timing.json (TimingSchema, sceneId: "avatar"). L'espace réservé Kokoro a déjà écrit ce fichier, sautez donc la transcription lors des essais à blanc.
Étape 4 — Assemblez le story-board (gratuit)
Pour le système visuel V2 plus riche — incrustations d'images clés, grandes cartes-titres, effets de papier et animations de mots 3D audacieuses — lisez references/v2-assets-layer.md et construisez avec scripts/build-v2-storyboard.ts (il fait correspondre les beats aux types V2 et récupère les incrustations via scripts/media.ts). V2 est additif : les story-boards utilisant uniquement des types V1 sont rendus inchangés.
- Relisez
references/layout-library.md. Écrivezjobs/<slug>/ad-storyboard.jsoncorrespondant àAvatarAdSchema: segments de mise en pagesegmentsordonnés sur la timeline de l'avatar plus le tableaucaptions. - Arc typique :
avatarFull(accroche) →split(démo : capture d'écran + incrustation) →split(preuve) →outro(carte CTA propre). Les segments doivent être ascendants et non chevauchants ; letoMsdu dernier segment doit arriver approximativement à la durée du clip. - Écrivez des sous-titres à incrustations de mots-clés à partir des
startMsdes mots declip.timing.json: des phrases de 1 à 4 mots, un mot d'accent chacun, pas de chevauchement, pas de tirets longs. N'inventez pasatMs— lisez-le dans le fichier de timing. Les sous-titres chevauchent tous les segments.
Étape 5 — Composition (aperçu, puis final)
npx tsx scripts/ad-compose.ts <job> # aperçu rapide en demi-taille, sans mixage musique
npx tsx scripts/ad-compose.ts <job> --final # rendu complet + musique atténuée + variante propre + SRT
--final rend en 1080×1920, mixe la musique de fond (music.gain ≈ 0.2, ducking sidechain à music.duckRatio, loudnorm I=-14:TP=-1) et émet :
jobs/<slug>/render/ad-captioned.mp4— sous-titres incrustésjobs/<slug>/render/ad-clean.mp4— sans sous-titres (fichier SRT séparé), musique à égalitéjobs/<slug>/render/ad-captions.srt
Itérez librement ici : modifier le story-board, les sous-titres ou la musique et relancer la composition ne coûte rien.
Étape 6 — Livraison et vérification
Exécutez les contrôles d'acceptation avant de faire votre rapport :
ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of csv=p=0 jobs/<job>/render/ad-captioned.mp4 # 1080,1920
ffmpeg -i jobs/<job>/render/ad-captioned.mp4 -af volumedetect -f null - 2>&1 | grep mean_volume # pas silencieux
grep -P "[\x{2013}\x{2014}]" jobs/<job>/render/ad-captions.srt && echo "TIRET LONG TROUVÉ (ÉCHEC)" || echo "pas de tiret long OK"
Extrayez quelques images et visualisez-les : écran partagé présent, captures d'écran ne coupant pas le texte des sous-titres, sous-titres alignés sur la parole, outro propre. Rapportez les deux MP4, le SRT, le clip d'avatar mis en cache (pour réutilisation) et la dépense totale.
Fichiers de référence
references/scriptwriting-methodology.md— la référence autoritaire DR / PAS / AIDA / accroche / CTA.references/ad-script-playbook.md— le flux anti-déchets en six étapes + règles strictes + l'interdiction des tirets longs.references/script-quality-checklist.md— la barrière humaine (« le créateur dirait-il cela à voix haute ? »).references/layout-library.md— la grammaire de segments à mix dynamique + les zones de sécurité portrait.references/v2-assets-layer.md— les types d'enrichissement V2 (incrustations, cartes-titres, effets papier, animations de mots 3D), les règles d'édition apprises, la direction de l'accentuation graphique animée (pills/timbres/outro) et le vocabulaire des effets GSAP.references/zooq-video-runbook.md— pour les vidéos ZOOQ, commencez ici. Le flux de bout en bout renforcé avec chaque décision verrouillée : échafaudage (npx tsx scripts/new-zooq-job.ts <slug>) → script + BARRIÈRE 1 → rendu Terry payant → base Remotion avec incrustations de scènes de marque (assets/zooq/manifest.json) → superposition HyperFrames + effets GSAP → révision + livraison.references/heygen-cli.md— commandes exactes de création/interrogation/téléchargement + lecture seule HeyGen.references/cost-gate.md— la règle de coût stricte, la formule d'estimation, la vérification du solde.