lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

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

Orquestrador de ponta a ponta: roteiro → MP4 final TikTok/Reels 9:16.

Pipeline possui 2 checkpoints de usuário:

1. Checkpoint MP3 (orquestrador) — após a Fase 1, o usuário revisa a narração.
2. Checkpoint do esboço das cenas (sub-agente da Fase 3) — o usuário revisa a estrutura das cenas e as variantes antes de gerar os conteúdos. Pode ser ignorado se o usuário passar auto_scenes=true.

Quando usar

• O usuário possui um roteiro em Vietnamita/Inglês com ≤ 5000 caracteres e deseja um vídeo TikTok completo
• Possui (opcional) imagens ou vídeos de apoio (b-roll) com propósito definido
• Deseja ir do roteiro até o preview no Studio em um único fluxo

Não use esta skill se:

• O usuário já possui um MP3 pronto → use diretamente heygen-mp3-to-mp4
• O usuário já possui um MP4 com avatar (talking-head) pronto → use diretamente mkt-hyperframe-talking-head-video
• O usuário precisa que o HeyGen leia o texto diretamente (sem ElevenLabs) → use heygen-script-to-mp4
• Roteiro > 5000 caracteres → divida semanticamente e chame o pipeline para cada segmento

Visão geral do pipeline

Script (texto + b-roll opcional + tts_provider)
    │
    ▼
Fase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    │                                         │
    │                                         ▼
    │                              CHECKPOINT #1 — usuário ouve + aprova MP3
    │                                         │
    │                                         ▼ (OK)
Fase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 lip-sync)
    │
    ▼
Fase 3 ── spawn agente mkt-full-video-phase3-packager (contexto isolado)
            │
            ├─ transcrever + limpar + agrupar legendas
            ├─ detectar limites de cenas + classificar variante de mockup
            ├─ CHECKPOINT #2 — usuário revisa esboço das cenas
            ├─ FAN-OUT N sub-agentes de propósito geral (1 por cena) em paralelo
            │   → cada sub-agente constrói JSON de conteúdo de acordo com o schema da variante
            ├─ mesclar → scenes.json
            ├─ paralelo: scaffold sub-comps + copiar SFX + injetar legendas
            ├─ gerar index.html raiz
            └─ lint + preview Studio
    │
    ▼
Usuário revisa preview → "render" → MP4 final

Regra de checkpoint: O orquestrador gerencia o checkpoint #1 (MP3). Fase 2 → 3 executam automaticamente. O checkpoint #2 (esboço das cenas) é gerenciado pelo sub-agente da Fase 3. A porta de renderização final está no Studio.

Entradas

Entrada	Obrigatório	Formato / exemplo
Texto do roteiro	Sim	Caminho de arquivo (.txt/.md) ou string inline. ≤ 5000 caracteres.
Slug do projeto	Não	Derivado automaticamente das 5 primeiras palavras do script. Minúsculo, ASCII, com traços.
Lista de b-roll	Não	Array [{path: "...", purpose: "Lição 1 — ilustração X"}, ...].
tts_provider	Não	elevenlabs (padrão — voz do Hoàng, expressiva) ou minimax (speech-2.8-hd, mais barato, leitura natural em Vietnamita). Usuário diz "dùng minimax" / "dùng eleven" → define de acordo.
Substituição de Voice ID	Não	Substitui o padrão do .env. ElevenLabs lê ELEVENLABS_VOICE_ID, MiniMax lê MINIMAX_VOICE_ID. Flag CLI --voice_id para ambos.
Substituição de configurações de voz	Não	ElevenLabs: {stability, similarity_boost, style}. MiniMax: {speed, vol, pitch}.
Aparência do avatar	Não	1 ID obtido de HEYGEN_AVATAR_LOOKS env (.env, separado por vírgulas). Aleatório se não for escolhido.
auto_scenes	Não	Padrão false. true para ignorar o checkpoint do esboço das cenas na Fase 3.

Estrutura do workspace

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Fase 0
├── voiceover.mp3           # Fase 1
├── source.mp4              # Fase 2
├── broll/                  # B-roll fornecido pelo usuário (cópia)
├── transcript.json         # Fase 3
├── caption-groups.json     # Fase 3
├── scenes-outline.json     # Fase 3 — esboço pré-checkpoint
├── scenes/                 # Fase 3 — fan-out de conteúdo por cena
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Fase 3 — final mesclado
├── compositions/           # Fase 3 — sub-comps do HF
├── sfx/                    # Fase 3 — 6 SFX
└── index.html              # Fase 3 — composição raiz

YYYY-MM-DD = data de hoje (UTC+7).

Fluxo de trabalho

Passo 0 — Configuração

1. Validar len(script_text) <= 5000. Se ultrapassar → parar, solicitar que o usuário divida semanticamente.
2. Derivar slug se ausente: 5 primeiras palavras → minúsculas → remover acentos → espaço→traço.
3. Resolver provedor TTS — ler tts_provider da entrada do usuário (padrão elevenlabs). Se o usuário disser "dùng minimax" / "đổi sang minimax" → minimax. Se o usuário disser "dùng eleven" / "elevenlabs" → elevenlabs. Validar se a chave de API correspondente existe em .env:
   • elevenlabs → precisa de ELEVENLABS_API_KEY (opcional ELEVENLABS_VOICE_ID para substituir o padrão K7ewtjKRNtwwt3lKQ6M0).
   • minimax → precisa de MINIMAX_API_KEY (opcional MINIMAX_VOICE_ID para substituir o padrão moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116). Se faltar chave → parar, informar o usuário para adicionar ao .env.
4. Criar workspace/content/YYYY-MM-DD/<slug>/. Salvar script.txt.
5. Se o usuário tiver b-roll: criar <folder>/broll/, copiar arquivos mantendo os nomes originais.
6. Informar o usuário: "Workspace criado em <folder>. Provedor TTS: <elevenlabs|minimax>. Iniciando Fase 1."

Passo 1 — Fase 1: Script → MP3 (TTS)

Executar exatamente 1 dos 2 ramos, dependendo de tts_provider:

Ramo A — ElevenLabs (padrão):

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

Voice ID: lê automaticamente ELEVENLABS_VOICE_ID do .env (fallback para a voz padrão da marca do Hoàng). Substituir via CLI: --voice_id <id>. Configurações de voz: adicionar --stability / --similarity_boost / --style se o usuário solicitar ajustes.

Ramo 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

Voice ID: lê automaticamente MINIMAX_VOICE_ID do .env (fallback para o padrão moss_audio_…). Substituir via CLI: --voice_id <id>. Configurações de voz: --speed (padrão 1.08), --vol, --pitch, --language_boost Vietnamese.

Nome do arquivo de saída invariável em ambos os ramos: voiceover.mp3 para que a Fase 2 (HeyGen) encontre o caminho correto.

Após a conclusão, verificar a duração (comum para ambos os provedores):

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

TOO_LONG → parar, informar que o MP3 > 5 minutos excede o limite do HeyGen, solicitar que o usuário reduza o roteiro.

Passo 2 — CHECKPOINT #1: usuário ouve o MP3

Único ponto de parada gerenciado pelo orquestrador. Informar o usuário no formato correto:

## Narração pronta — por favor, revise

**Arquivo:** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**Duração:** <X.X>s
**Tamanho:** <Y.Y> MB
**Provedor:** <`elevenlabs` | `minimax`>
**Voz:** <`ElevenLabs Brand Voice do Hoàng (K7ewtjKRNtwwt3lKQ6M0)`> ou <`MiniMax speech-2.8-hd (moss_audio_…)`> (obtido do voice ID no `.env` se o usuário substituiu)

Abra o arquivo e ouça. Responda com 1 das opções:
- **`OK`** / **`tiếp`** → vou executar a Fase 2 (avatar HeyGen com lip-sync)
- **`regen`** + (opcional) motivo → vou ajustar as configurações de voz e regenerar o MP3
- **`sửa script`** + novo conteúdo → vou salvar o novo script e executar novamente a Fase 1

Parar chamadas de ferramentas. Aguardar resposta clara do usuário.

Quando o usuário disser OK → Fase 2. Quando o usuário disser regen → executar novamente o script TTS do provedor atual com novas configurações, retornar ao checkpoint. Se o usuário disser "đổi sang minimax" / "thử eleven" → trocar tts_provider, executar novamente a Fase 1. Quando o usuário editar o script → sobrescrever script.txt, executar novamente a Fase 1 desde o início (mesmo provedor).

Passo 3 — Fase 2: MP3 → HeyGen MP4 (automática)

De acordo com a sub-skill heygen-mp3-to-mp4:

1. Selecionar ID do avatar — ler HEYGEN_AVATAR_LOOKS do .env (separado por vírgulas), selecionar aleatoriamente se o usuário não especificar:

   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]}'
   

   Se a variável de ambiente estiver ausente/vazia → parar e informar o usuário para adicionar HEYGEN_AVATAR_LOOKS=<id1>,<id2> ao .env. Informar o usuário para escolher um antes de chamar o MCP.

2. Fazer upload do MP3 para o HeyGen via MCP (upload_asset, asset type audio). NÃO usar curl https://upload.heygen.com/....

3. Criar vídeo do avatar via MCP (generate_avatar_video):

   character: { type: avatar, avatar_id: <selecionado>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <do upload> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<timestamp>"
   

4. Verificar status a cada ~10s → completed (limite de 10 min). failed → parar, exibir erro.

5. Baixar MP4 → workspace/content/YYYY-MM-DD/<slug>/source.mp4 (nome de arquivo invariável):

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

6. Informar o usuário com 1 linha: "Fase 2 concluída — <path> (avatar <id>, s, MB). Gerando sub-agente da Fase 3…"

Não parar aqui. Fluxo automático para a Fase 3.

Passo 4 — Fase 3: Gerar sub-agente packager

Usar a ferramenta Task com subagent_type: "mkt-full-video-phase3-packager". Passar um prompt auto-contido com as entradas que o agente precisa. Exemplo:

Workspace: workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug: hom-nay-minh-chia-se
Script: <texto completo do roteiro>
B-roll: [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "Lição 1"},
  ...
]
auto_scenes: false
header_label: "3 BÀI HỌC AI"
footer_handle: "@tranvanhoang.com"

Execute o pipeline completo de empacotamento da Fase 3 de acordo com a definição do seu agente. Retorne a URL do Studio quando o preview estiver aberto.

O sub-agente:

• Transcreve source.mp4, constrói o esboço das cenas
• Para e pergunta ao usuário para aprovar o esboço (CHECKPOINT #2) a menos que auto_scenes: true
• Distribui N escritores de conteúdo de cena em paralelo
• Mescla + scaffold + lint + abre preview
• Retorna a URL do Studio

Enquanto o sub-agente estiver em execução, a única tarefa do orquestrador é encaminhar as respostas do usuário para o sub-agente (a resposta do usuário no checkpoint de esboço das cenas chegará nesta conversa; encaminhe para o sub-agente se ele ainda estiver ativo, caso contrário, trate como uma instrução de acompanhamento).

Passo 5 — Entrega

Quando o sub-agente retornar a URL do Studio, formatar o relatório final:

## Pipeline de vídeo completo CONCLUÍDO — preview pronto

**Workspace:** `workspace/content/YYYY-MM-DD/<slug>/`

**Fase 1 (`<elevenlabs|minimax>`):** voiceover.mp3 — <D1>s, <S1>MB (voice ID `<id>`)
**Fase 2 (HeyGen):** source.mp4 — avatar `<avatar_id>`, <D2>s, <S2>MB
**Fase 3 (HyperFrames):** <N> cenas (<listar variantes>), <K> grupos de legendas, 6 SFX

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

Abra o navegador e percorra a linha do tempo. Diga **`render`** quando estiver OK → executarei `npx hyperframes render` para exportar MP4 1080×1920 30fps.

Parar aqui. Não renderizar automaticamente. O usuário confirma e só então chamar npx hyperframes render.

Regras críticas de orquestração

1. 2 checkpoints de usuário, 1 porta de orquestrador — O orquestrador só para no MP3 (Passo 2). O checkpoint do esboço das cenas é gerenciado pelo sub-agente da Fase 3. A porta de renderização está no Studio, sob controle do usuário.

2. Convenções de caminho invariáveis — a narração deve ser voiceover.mp3, o vídeo com avatar deve ser source.mp4. A sub-skill HF espera o nome source.mp4.

3. HeyGen MCP apenas — nunca usar curl para https://api.heygen.com/.... Restrição rígida de heygen-mp3-to-mp4.

4. Voice ID armazenado no .env, não codificado na skill. ElevenLabs lê ELEVENLABS_VOICE_ID (fallback K7ewtjKRNtwwt3lKQ6M0). MiniMax lê MINIMAX_VOICE_ID (fallback moss_audio_…). Substituir por chamada via --voice_id. O pipeline informa claramente o provedor + voice ID escolhidos no Passo 0 e checkpoint #1.

5. Limite rígido de 5000 caracteres para o roteiro — falha rápida no Passo 0.1.

6. Duração do MP3 ≤ 300s — limite de vídeo único do HeyGen. Verificar imediatamente após a Fase 1.

7. Preview primeiro — Fase 3 NÃO renderiza automaticamente. Memória feedback_hyperframes_workflow.md.

8. Isolamento da Fase 3 — Fase 3 é executada em um contexto de sub-agente separado. O corpo da skill HF + 4 documentos de referência (~40KB) são carregados no sub-agente em vez do orquestrador principal.

Modos de falha e fallback

Sintoma	Ação
Roteiro > 5000 caracteres	Parar, solicitar que o usuário divida semanticamente
Falha na API ElevenLabs	Informar erro, sugerir verificar ELEVENLABS_API_KEY no .env (opcional ELEVENLABS_VOICE_ID). Ou trocar para tts_provider=minimax e executar novamente a Fase 1
Falha na API MiniMax	Informar erro, sugerir verificar MINIMAX_API_KEY no .env (opcional MINIMAX_VOICE_ID). Ou trocar para tts_provider=elevenlabs e executar novamente a Fase 1
MP3 > 300s após a Fase 1	Parar pipeline, sugerir heygen-short-video (divisão em partes)
HeyGen MCP não conectado	Parar, informar claude mcp list para verificar
Falha na renderização do HeyGen	Exibir erro, sugerir verificar créditos via mcp__heygen__get_current_user
Falha no sub-agente da Fase 3	Ler trace de erro, sugerir que o usuário execute novamente a Fase 3 de forma independente usando a skill mkt-hyperframe-talking-head-video
Escritor de cena retorna JSON malformado	Sub-agente gera novamente para essa cena automaticamente (não é responsabilidade do orquestrador)
Usuário rejeita voz do MP3	Voltar para a Fase 1 com ajustes nas configurações de voz

Exemplo de ponta a ponta

Usuário:

Tenho um roteiro aqui, execute o pipeline completo para gerar um vídeo TikTok. Acompanhe com 2 imagens de b-roll para a lição 1 e lição 2. Roteiro: "Hôm nay mình chia sẻ 3 bài học từ Anthropic. Bài học đầu tiên là Alphabet ship beta. Bài học thứ 2 là 24h…" B-roll: alphabet.png (lição 1), clock.png (lição 2)

Pipeline:

1. Passo 0 — slug hom-nay-minh-chia-se. Pasta workspace/content/2026-05-03/hom-nay-minh-chia-se/. Salvar script.txt, copiar b-roll.
2. Passo 1 — text_to_mp3.py → voiceover.mp3 (45s, 0.7MB).
3. Passo 2 — CHECKPOINT #1 — informar caminho + duração. Aguardar resposta.
4. Usuário: OK.
5. Passo 3 — Selecionar avatar (aleatório de HEYGEN_AVATAR_LOOKS, ex. 66e75e22…). Fazer upload do MP3 → asset_id. Gerar vídeo → poll → baixar source.mp4 (45s, 7.5MB).
6. Passo 4 — Gerar sub-agente mkt-full-video-phase3-packager.
7. Sub-agente transcreve (35s), constrói esboço (3 lições + recapitulação + cta), exibe esboço → CHECKPOINT #2.
8. Usuário: OK.
9. Sub-agente distribui 5 escritores de cena em paralelo (~8s de tempo real vs ~40s em série).
10. Sub-agente mescla → scenes.json → scaffold + SFX + legendas em paralelo.
11. Sub-agente executa lint + abre preview do Studio → retorna URL.
12. Passo 5 — Relatório final com URLs. Aguardar render.