lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

mkt-full-video-with-11-hyperframe-heygen

Orchestrateur de bout en bout : script → final TikTok/Reels MP4 9:16.

Pipeline avec 2 points de contrôle utilisateur :

1. Point de contrôle MP3 (orchestrateur) — après la Phase 1, l'utilisateur valide la voix off.
2. Point de contrôle du plan de scènes (sous-agent Phase 3) — l'utilisateur valide la structure des scènes + la variante avant le déploiement des rédacteurs de contenu. Peut être ignoré si l'utilisateur passe auto_scenes=true.

Quand l'utiliser

• L'utilisateur a un script en vietnamien ou en anglais de ≤ 5000 caractères et souhaite obtenir une vidéo TikTok complète.
• L'utilisateur a des images ou vidéos b-roll (optionnelles) avec un objectif d'utilisation précis.
• L'utilisateur souhaite parcourir tout le pipeline du script jusqu'à l'aperçu dans Studio.

Ne pas utiliser ce skill si :

• L'utilisateur a déjà un fichier MP3 → utiliser directement heygen-mp3-to-mp4.
• L'utilisateur a déjà une vidéo talking-head au format MP4 → utiliser directement mkt-hyperframe-talking-head-video.
• L'utilisateur a besoin que HeyGen lise le texte directement (sans passer par ElevenLabs) → utiliser heygen-script-to-mp4.
• Le script fait plus de 5000 caractères → diviser sémantiquement puis appeler le pipeline pour chaque segment.

Aperçu du pipeline

Script (texte + b-roll optionnel + tts_provider)
    │
    ▼
Phase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    │                                         │
    │                                         ▼
    │                              POINT DE CONTRÔLE #1 — l'utilisateur écoute et valide le MP3
    │                                         │
    │                                         ▼ (OK)
Phase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 lip-sync)
    │
    ▼
Phase 3 ── lancement de l'agent mkt-full-video-phase3-packager (contexte isolé)
            │
            ├─ transcrire + nettoyer + regrouper les sous-titres
            ├─ détecter les limites des scènes + classer la variante mockup
            ├─ POINT DE CONTRÔLE #2 — l'utilisateur valide le plan des scènes
            ├─ DÉPLOIEMENT PARALLÈLE de N sous-agents génériques (1 par scène)
            │   → chaque sous-agent construit un JSON de contenu selon le schéma de variante
            ├─ fusionner → scenes.json
            ├─ parallèle : générer les sous-composants + copier les SFX + injecter les sous-titres
            ├─ générer le fichier index.html racine
            └─ lint + aperçu dans Studio
    │
    ▼
L'utilisateur valide l'aperçu → "render" → MP4 final

Règle des points de contrôle : L'orchestrateur gère le point de contrôle #1 (MP3). Les phases 2 → 3 s'exécutent automatiquement. Le point de contrôle #2 (plan des scènes) est géré par le sous-agent de la Phase 3. La validation finale du rendu se fait dans Studio.

Entrées

Entrée	Requise	Format / exemple
Texte du script	Oui	Chemin de fichier (.txt/.md) ou chaîne inline. ≤ 5000 caractères.
Slug du projet	Non	Dérivé automatiquement des 5 premiers mots du script. Minuscules, ASCII, tirets.
Liste b-roll	Non	Tableau [{path: "...", purpose: "Leçon 1 — illustration X"}, ...].
tts_provider	Non	elevenlabs (par défaut — voix de Hoàng, expressive) ou minimax (speech-2.8-hd, moins cher, lecture vietnamienne naturelle). L'utilisateur dit "utiliser minimax" / "utiliser eleven" → défini en conséquence.
Remplacement de l'ID vocal	Non	Remplace la valeur par défaut du fichier .env. ElevenLabs lit ELEVENLABS_VOICE_ID, MiniMax lit MINIMAX_VOICE_ID. Indicateur CLI --voice_id pour les deux.
Remplacement des réglages vocaux	Non	ElevenLabs : {stability, similarity_boost, style}. MiniMax : {speed, vol, pitch}.
Apparence de l'avatar	Non	1 ID issu de la variable d'environnement HEYGEN_AVATAR_LOOKS (.env, séparés par des virgules). Aléatoire si non spécifié.
auto_scenes	Non	Par défaut false. true pour ignorer le point de contrôle du plan de scènes dans la Phase 3.

Structure de l'espace de travail

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Phase 0
├── voiceover.mp3           # Phase 1
├── source.mp4              # Phase 2
├── broll/                  # B-roll fourni par l'utilisateur (copie)
├── transcript.json         # Phase 3
├── caption-groups.json     # Phase 3
├── scenes-outline.json     # Phase 3 — plan avant point de contrôle
├── scenes/                 # Phase 3 — écriture du contenu par scène ici
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Phase 3 — fusion finale
├── compositions/           # Phase 3 — sous-composants HF
├── sfx/                    # Phase 3 — 6 SFX
└── index.html              # Phase 3 — composition racine

YYYY-MM-DD = date du jour (UTC+7).

Flux de travail

Étape 0 — Configuration

1. Valider len(script_text) <= 5000. Si dépassé → stop, demander à l'utilisateur de diviser sémantiquement.
2. Dériver le slug si manquant : 5 premiers mots → minuscules → supprimer les accents → espace→tiret.
3. Résoudre le fournisseur TTS — lire tts_provider à partir de l'entrée utilisateur (par défaut elevenlabs). Si l'utilisateur dit "utiliser minimax" / "passer à minimax" → minimax. Si l'utilisateur dit "utiliser eleven" / "elevenlabs" → elevenlabs. Valider que la clé API correspondante est présente dans .env :
   • elevenlabs → nécessite ELEVENLABS_API_KEY (optionnel ELEVENLABS_VOICE_ID pour remplacer la valeur par défaut K7ewtjKRNtwwt3lKQ6M0).
   • minimax → nécessite MINIMAX_API_KEY (optionnel MINIMAX_VOICE_ID pour remplacer la valeur par défaut moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116). Si la clé manque → stop, informer l'utilisateur de l'ajouter à .env.
4. Créer le dossier workspace/content/YYYY-MM-DD/<slug>/. Sauvegarder script.txt.
5. Si l'utilisateur a des b-roll : créer le dossier <folder>/broll/, copier les fichiers en conservant le nom d'origine.
6. Informer l'utilisateur : "Espace de travail créé dans <folder>. Fournisseur TTS : <elevenlabs|minimax>. Début de la Phase 1."

Étape 1 — Phase 1 : Script → MP3 (TTS)

Exécuter exactement 1 des 2 branches selon tts_provider :

Branche A — ElevenLabs (par défaut) :

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

ID vocal : lecture automatique de ELEVENLABS_VOICE_ID depuis .env (valeur par défaut : la voix de marque de Hoàng). Remplacement CLI : --voice_id <id>. Réglages vocaux : ajouter --stability / --similarity_boost / --style si l'utilisateur demande des ajustements.

Branche B — MiniMax :

uv run .claude/skills/mkt-video-script-to-mp3/scripts/text_to_mp3.py \
  --file workspace/content/YYYY-MM-DD/<slug>/script.txt \
  -o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

ID vocal : lecture automatique de MINIMAX_VOICE_ID depuis .env (valeur par défaut moss_audio_…). Remplacement CLI : --voice_id <id>. Réglages vocaux : --speed (par défaut 1.08), --vol, --pitch, --language_boost Vietnamese.

Nom de fichier de sortie inviolable pour les deux branches : voiceover.mp3 afin que la Phase 2 (HeyGen) trouve le bon chemin.

Une fois terminé, vérifier la durée (commun aux deux fournisseurs) :

uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py \
  workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3

TOO_LONG → stop, informer l'utilisateur que le MP3 dure plus de 5 minutes (limite HeyGen), demander de réduire le script.

Étape 2 — POINT DE CONTRÔLE #1 : l'utilisateur écoute le MP3

Seul point d'arrêt géré par l'orchestrateur. Informer l'utilisateur avec le format suivant :

## Voix off prête — merci de valider

**Fichier :** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**Durée :** <X.X>s
**Taille :** <Y.Y> Mo
**Fournisseur :** <`elevenlabs` | `minimax`>
**Voix :** <`Voix de marque ElevenLabs de Hoàng (K7ewtjKRNtwwt3lKQ6M0)`> ou <`MiniMax speech-2.8-hd (moss_audio_…)`> (à partir de l'ID vocal du fichier `.env` si l'utilisateur a remplacé)

Ouvrez le fichier pour écouter. Répondez par l'une des options suivantes :
- **`OK`** / **`continuer`** → je lance la Phase 2 (avatar HeyGen lip-sync)
- **`regen`** + (optionnel) raison → j'ajuste les réglages vocaux et je regénère le MP3
- **`modifier le script`** + nouveau contenu → je sauvegarde le nouveau script et je relance la Phase 1

Arrêter les appels d'outils. Attendre une réponse claire de l'utilisateur.

Quand l'utilisateur répond OK → Phase 2. Quand l'utilisateur répond regen → relancer le script TTS du fournisseur actuel avec de nouveaux réglages, revenir au point de contrôle. Si l'utilisateur dit "passer à minimax" / "essayer eleven" → changer tts_provider, relancer la Phase 1. Quand l'utilisateur modifie le script → écraser script.txt, relancer la Phase 1 depuis le début (même fournisseur).

Étape 3 — Phase 2 : MP3 → MP4 HeyGen (automatique)

Selon le sous-skill heygen-mp3-to-mp4 :

1. Choisir un ID d'avatar — lire HEYGEN_AVATAR_LOOKS depuis .env (séparé par des virgules), choisir aléatoirement si l'utilisateur n'a pas spécifié :

   HEYGEN_AVATAR_LOOKS=$(grep '^HEYGEN_AVATAR_LOOKS=' .env | cut -d'=' -f2- | tr -d '"' | tr -d "'")
   echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'
   

   Si la variable d'environnement est manquante/vide → stop et informer l'utilisateur d'ajouter HEYGEN_AVATAR_LOOKS=<id1>,<id2> dans .env. Demander à l'utilisateur de choisir avant d'appeler MCP.

2. Télécharger le MP3 vers HeyGen via MCP (upload_asset, type d'actif audio). NE PAS utiliser curl https://upload.heygen.com/....

3. Créer la vidéo avatar via MCP (generate_avatar_video) :

   character: { type: avatar, avatar_id: <choisi>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <id du téléchargement> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<timestamp>"
   

4. Interroger le statut toutes les ~10s → completed (limite de 10 min). failed → stop, afficher l'erreur.

5. Télécharger le MP4 → workspace/content/YYYY-MM-DD/<slug>/source.mp4 (nom de fichier inviolable) :

   uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py \
     "<video_url>" "workspace/content/YYYY-MM-DD/<slug>/source.mp4"
   

6. Informer l'utilisateur en une ligne : "Phase 2 terminée — <path> (avatar <id>, <durée>s, Mo). Lancement du packager Phase 3…"

Ne pas s'arrêter ici. Passer automatiquement à la Phase 3.

Étape 4 — Phase 3 : Lancer le sous-agent packager

Utiliser l'outil Task avec subagent_type: "mkt-full-video-phase3-packager". Passer une invite autonome contenant les entrées nécessaires à l'agent. Exemple :

Espace de travail : workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug : hom-nay-minh-chia-se
Script : <texte complet du script>
B-roll : [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "Leçon 1"},
  ...
]
auto_scenes : false
header_label : "3 LEÇONS IA"
footer_handle : "@tranvanhoang.com"

Exécutez le pipeline complet de packaging Phase 3 selon votre définition d'agent. Retournez l'URL Studio une fois l'aperçu ouvert.

Le sous-agent :

• Transcrit source.mp4, construit le plan des scènes
• S'arrête pour demander à l'utilisateur d'approuver le plan (POINT DE CONTRÔLE #2) sauf si auto_scenes: true
• Déploie N rédacteurs de contenu de scènes en parallèle
• Fusionne + génère la structure + lint + ouvre l'aperçu
• Retourne l'URL Studio

Pendant que le sous-agent s'exécute, le seul travail de l'orchestrateur est de transmettre les réponses de l'utilisateur au sous-agent (la réponse de l'utilisateur au point de contrôle du plan de scènes arrivera dans cette conversation ; la rediriger vers le sous-agent s'il est toujours actif, sinon la traiter comme une instruction de suivi).

Étape 5 — Passation

Lorsque le sous-agent retourne l'URL Studio, formater le rapport final :

## Pipeline vidéo complet TERMINÉ — aperçu prêt

**Espace de travail :** `workspace/content/YYYY-MM-DD/<slug>/`

**Phase 1 (`<elevenlabs|minimax>`) :** voiceover.mp3 — <D1>s, <S1>Mo (ID vocal `<id>`)
**Phase 2 (HeyGen) :** source.mp4 — avatar `<avatar_id>`, <D2>s, <S2>Mo
**Phase 3 (HyperFrames) :** <N> scènes (<liste des variantes>), <K> groupes de sous-titres, 6 SFX

**URL Studio :** http://localhost:3002

Ouvrez le navigateur et parcourez la timeline. Dites **`render`** quand c'est OK → je lance `npx hyperframes render` pour exporter le MP4 1080×1920 30fps.

S'arrêter ici. Ne pas lancer automatiquement le rendu. Attendre la confirmation de l'utilisateur avant d'appeler npx hyperframes render.

Règles critiques d'orchestration

1. 2 points de contrôle utilisateur, 1 porte d'orchestrateur — L'orchestrateur s'arrête uniquement au MP3 (Étape 2). Le point de contrôle du plan de scènes est géré par le sous-agent Phase 3. La porte de rendu est dans Studio, gérée par l'utilisateur.

2. Conventions de chemin inviolables — la voix off doit être voiceover.mp3, la talking-head doit être source.mp4. Le sous-skill HF attend le nom source.mp4.

3. HeyGen MCP uniquement — ne jamais utiliser curl https://api.heygen.com/.... Contrainte forte de heygen-mp3-to-mp4.

4. ID vocal stocké dans .env, non codé en dur dans le skill. ElevenLabs lit ELEVENLABS_VOICE_ID (valeur par défaut K7ewtjKRNtwwt3lKQ6M0). MiniMax lit MINIMAX_VOICE_ID (valeur par défaut moss_audio_…). Remplacement par appel via --voice_id. Le pipeline indique clairement le fournisseur + l'ID vocal choisis à l'Étape 0 et au point de contrôle #1.

5. Limite stricte du script : 5000 caractères — échec rapide à l'Étape 0.1.

6. Durée du MP3 ≤ 300s — limite d'une seule vidéo HeyGen. Vérifier immédiatement après la Phase 1.

7. Aperçu d'abord — La Phase 3 NE fait PAS de rendu automatique. Mémoire feedback_hyperframes_workflow.md.

8. Isolation de la Phase 3 — La Phase 3 s'exécute dans un contexte de sous-agent dédié. Le corps du skill HF + 4 documents de référence (~40 Ko) sont chargés dans le sous-agent plutôt que dans l'orchestrateur principal.

Modes d'échec et solutions de repli

Symptôme	Action
Script > 5000 caractères	Stop, demander à l'utilisateur de diviser sémantiquement
Échec de l'API ElevenLabs	Signaler l'erreur, suggérer de vérifier ELEVENLABS_API_KEY dans .env (optionnel ELEVENLABS_VOICE_ID). Ou passer à tts_provider=minimax et relancer la Phase 1
Échec de l'API MiniMax	Signaler l'erreur, suggérer de vérifier MINIMAX_API_KEY dans .env (optionnel MINIMAX_VOICE_ID). Ou passer à tts_provider=elevenlabs et relancer la Phase 1
MP3 > 300s après Phase 1	Arrêter le pipeline, suggérer heygen-short-video (fractionnement)
HeyGen MCP non connecté	Stop, informer de vérifier avec claude mcp list
Échec du rendu HeyGen	Afficher l'erreur, suggérer de vérifier les crédits via mcp__heygen__get_current_user
Échec du sous-agent Phase 3	Lire la trace d'erreur, suggérer à l'utilisateur de relancer la Phase 3 de manière autonome avec le skill mkt-hyperframe-talking-head-video
Le rédacteur de scène renvoie un JSON mal formé	Le sous-agent relance automatiquement pour cette scène (ne relève pas de l'orchestrateur)
L'utilisateur rejette la voix MP3	Revenir à la Phase 1 avec des réglages vocaux ajustés

Exemple de bout en bout

Utilisateur :

J'ai un script, lance le pipeline complet pour une vidéo TikTok. Avec 2 images b-roll pour les leçons 1 et 2. Script : "Aujourd'hui je partage 3 leçons d'Anthropic. La première leçon est Alphabet ship beta. La deuxième leçon est 24h…" B-roll : alphabet.png (leçon 1), clock.png (leçon 2)

Pipeline :

1. Étape 0 — slug hom-nay-minh-chia-se. Dossier workspace/content/2026-05-03/hom-nay-minh-chia-se/. Sauvegarder script.txt, copier le b-roll.
2. Étape 1 — text_to_mp3.py → voiceover.mp3 (45s, 0.7 Mo).
3. Étape 2 — POINT DE CONTRÔLE #1 — informer l'utilisateur du chemin + durée. Attendre la réponse.
4. Utilisateur : OK.
5. Étape 3 — Choisir un avatar (aléatoirement depuis HEYGEN_AVATAR_LOOKS, par exemple 66e75e22…). Télécharger le MP3 → asset_id. Générer la vidéo → interroger → télécharger source.mp4 (45s, 7.5 Mo).
6. Étape 4 — Lancer le sous-agent mkt-full-video-phase3-packager.
7. Le sous-agent transcrit (35s), construit le plan (3 leçons + récapitulatif + CTA), affiche le plan → POINT DE CONTRÔLE #2.
8. Utilisateur : OK.
9. Le sous-agent déploie 5 rédacteurs de scènes en parallèle (~8s temps réel vs ~40s séquentiel).
10. Le sous-agent fusionne → scenes.json → génération de la structure + SFX + sous-titres parallèles…

…

[skillMarkdown tronqué pour la traduction]