Communitygithub.com

baldiga/headless-studio

Transforme la marque et les captures d'écran d'un projet SaaS en une publicité verticale 9:16 de moins de 60 secondes dans le style UGC — un clip d'avatar HeyGen réaliste comme colonne vertébrale, composé dans Remotion avec captures d'écran, sous-titres à mots-clés et une musique de fond atténuée, le tout rendu localement en MP4 avec et sans sous-titres.

Qu'est-ce que headless-studio ?

Ce skill est un pipeline automatisé complet pour créer des publicités vidéo verticales de type UGC (contenu généré par l'utilisateur) pour des applications SaaS. Il utilise un clip d'avatar réaliste HeyGen comme colonne vertébrale, portant la voix et la narration, et le combine dans Remotion avec des captures d'écran, des sous-titres animés par mots-clés et une musique de fond. L'ensemble du processus, de la rédaction du script à la composition finale, est géré par des scripts CLI et des schémas de validation, avec une itération gratuite jusqu'à ce que le script soit approuvé. La seule étape payante est la génération de l'avatar HeyGen, qui est strictement protégée et nécessite une approbation explicite de l'utilisateur. Le skill supporte des systèmes visuels enrichis (V2) avec des incrustations d'images, des cartes-titres, des effets de papier et des animations de mots 3D, et il inclut des contrôles de qualité automatisés, comme l'interdiction des tirets longs et la vérification de la résolution.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/baldiga/headless-studio/tree/HEAD/skills/avatar-ad-director

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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)

  1. 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 non standard. 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. Voir references/cost-gate.md.
  2. 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. AvatarAdSchema les rejette à l'analyse et l'étape 6 les recherche dans le SRT pour confirmation. Humanisez également le script (appliquez les directives humanizer) 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

  1. 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.json existant si le projet en a déjà un, sinon créez-en un.

  2. Affichez le solde HeyGen et l'avis de barrière de coût : heygen auth status (gratuit, lecture seule) affiche remaining_balance.

  3. Écrivez jobs/<slug>/ad-project.json correspondant à AdProjectSchema (voir src/ad-schemas.ts). Le slug est en kebab-minuscule. Valeurs par défaut que vous conservez généralement : heygen.group VOTRE_ID_GROUPE_AVATAR (Jibran), heygen.voiceId VOTRE_ID_VOIX (voix par défaut de Jibran — préférez-la pour le look Jibran afin que la voix corresponde au visage), resolution 1080p, music.gain 0.2, music.duckRatio 16, viewport 1080×1920, fps 30. Définissez brandBgHex à partir du fond de la marque (couleur unie sur laquelle l'avatar est rendu).

  4. Réécriture des mots à risque (pronunciations). Les noms de marque et les orthographes inhabituelles sont souvent mal prononcés par la TTS. Ajoutez une map pronunciations (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, plus zooq.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 dans scripts/heygen.ts (applyPronunciations) et s'exécute automatiquement dans generate.

  5. Copiez brand/brand.json et 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 a usable: false est 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.

  1. Écrivez selon la méthodologie. En suivant le flux en six étapes de ad-script-playbook.md, écrivez jobs/<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).

  2. Exécutez la barrière de lint. Elle doit signaler 0 problème dur :

    npx tsx scripts/script-lint.ts jobs/<slug>/ad-script.md
    

    Les 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.

  3. 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.

  4. 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.

  5. 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.

  1. Relisez references/layout-library.md. Écrivez jobs/<slug>/ad-storyboard.json correspondant à AvatarAdSchema : segments de mise en page segments ordonnés sur la timeline de l'avatar plus le tableau captions.
  2. 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 ; le toMs du dernier segment doit arriver approximativement à la durée du clip.
  3. Écrivez des sous-titres à incrustations de mots-clés à partir des startMs des mots de clip.timing.json : des phrases de 1 à 4 mots, un mot d'accent chacun, pas de chevauchement, pas de tirets longs. N'inventez pas atMs — 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és
  • jobs/<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.

Skills associés