mkt-hyperframe-talking-head-video-16-9
Editor 16:9 (1920×1080) paisagem dedicado — a entrada é uma pasta de workspace existente com voiceover.mp3 + source.mp4 + script.txt, a saída é a mesma pasta totalmente estruturada como um projeto HyperFrames pronto para npx hyperframes preview.
Esta é uma camada operacional abaixo da orquestradora mkt-full-video-with-11-hyperframe-heygen-16-9. A orquestradora lida com a Fase 1 (TTS) + Fase 2 (avatar HeyGen) → entrega a pasta para esta skill cuidar da Fase 3 (transcrição + estruturação + lint + pré-visualização).
O que esta skill produz
<pasta_de_trabalho>/
├── voiceover.mp3 # entrada (inalterada)
├── source.mp4 # entrada (avatar HeyGen sincronizado, inalterado)
├── script.txt # entrada (inalterado)
├── transcript.json # gerado — saída do Whisper a nível de palavra
├── transcript-cleaned.json # gerado — correção de erros de digitação em vietnamita
├── scenes-outline.json # gerado — esboço pré-ponto-de-verificação (5 cenas)
├── scenes.json # gerado — metadados finais por cena
├── index.html # gerado — composição raiz 1920×1080
├── compositions/
│ ├── scene-1.html # 1 arquivo por cena, independentemente de N
│ ├── scene-2.html # criado por subagentes LLM paralelos (Fase 3d)
│ ├── scene-3.html # NÃO gerado por templates Python (obsoleto)
│ ├── ...
│ └── scene-N.html
├── sfx/ # 6 SFX link/cópia dos ativos da skill
│ ├── camera-flash.mp3
│ ├── Whoosh sound effect (1).mp3
│ ├── búng tay.mp3
│ ├── Laser.mp3
│ ├── ting.mp3
│ └── Discord Notification - Sound Effect.mp3
└── (opcional) infographics/
├── 1.png 2.png 3.png # se --with-infographics
└── prompts.md # prompts editoriais para cada cena
Canvas:
- Raiz:
data-width="1920" data-height="1080". - Moldura do avatar padrão SPLIT:
top:100, left:1290, width:540, height:880, borderRadius:32. - Moldura do avatar PIP canto:
top:600, left:1540, width:320, height:420, borderRadius:20. - Suporte de slide:
1200×1080SPLIT, animável para1920×1080durante PIP. - Tamanho intrínseco de cada composição:
data-width="1200" data-height="1080"(preenche 100% do suporte, expande quando o suporte aumenta).
Entradas necessárias (convenção de pasta de workspace)
| Arquivo | Obrigatório | Observação |
|---|---|---|
voiceover.mp3 | Sim | Saída do ElevenLabs TTS (voz do Hoàng). |
source.mp4 | Sim | Avatar HeyGen sincronizado. Atualmente 9:16 retrato — o quadro paisagem usa object-fit: cover; object-position: center 25% para cortar adequadamente. Veja references/source-mp4-cropping.md. |
script.txt | Sim | Roteiro em vietnamita que produziu voiceover.mp3. Usado para correção de erros de digitação e derivação de títulos de cena. |
scenes-outline.json | Não | Se o usuário pré-definiu 5 cenas, pula a detecção automática. Esquema: veja a Etapa 3. |
Slug = nome base da pasta de workspace (nenhuma derivação necessária). Todos os scripts leem/escrevem dentro dessa pasta. Os scripts aceitam a flag --workspace <caminho> e usam o diretório atual como padrão.
O pipeline (invocação sequencial de scripts)
voiceover.mp3 + source.mp4 + script.txt
│
▼
1. transcribe_audio.py ── Whisper VN → transcript.json (nível de palavra)
│
▼
2. clean_transcript.py ── remove artefatos do Whisper, aplica dicionário VN
│
▼
3. detect_scenes.py ── transcript + script.txt → scenes-outline.json (5 cenas)
│
▼
4. [PONTO DE VERIFICAÇÃO opcional] ── usuário revisa outline / edita kicker, título
│
▼
5. scaffold_project.py ── escreve scenes.json (esquema completo), cria sfx/ + logos/ + avatar.jpg + yt-lower-third.html
│
▼
6. 🔥 FAN-OUT DE SUBAGENTES LLM 🔥 ── orquestrador cria N agentes de propósito geral paralelos
(1 por cena) em uma única mensagem, cada um
criando compositions/scene-{num}.html a partir de
visual-plan.json + references/composition-patterns.md.
NÃO generate_compositions.py (gerador Jinja2
OBSOLETO — colapsa em 5 arquétipos, não consegue adaptar
metáforas específicas de cena, quebra para listicles 6+ cenas).
│
▼
7. generate_root_index.py ── escreve index.html com suporte de slide (monta scene-{num}.html
para TODAS as cenas, sem mapeamento kind→fs-lesson) +
moldura de avatar (borda da marca claude-orange #d97757) +
timeline GSAP (SPLIT↔PIP, respiração, punch-in,
PIP_EVENTS, zoom de gancho híbrido) + 6 SFX conectados +
camada de imagem b-roll estilo papel-couro na raiz (1920×1080 completo)
│
▼
8. [opcional] scaffold_infographic_slots.py
── adiciona placeholders <img onerror> + escreve prompts.md
(editorial estilo papel-couro por metáfora de cena)
│
▼
9. lint_and_preview.py ── npx hyperframes lint → 0 erros, depois preview
│
▼
ENTREGA — URL do Studio impressa; usuário revisa; orquestradora decide renderização.
Regra de pré-visualização primeiro (innegociável): a skill termina na Etapa 9 com a URL do Studio. A renderização do MP4 só é executada após confirmação explícita do usuário — essa etapa pertence à orquestradora ou ao usuário manualmente.
Etapa 1: transcribe_audio.py
python3 scripts/transcribe_audio.py --workspace <pasta>
Envolve a skill existente mkt-ai-video-extract-srt-segment se disponível localmente; caso contrário, usa o CLI whisper diretamente:
whisper voiceover.mp3 --model medium --language vi --word_timestamps True \
--output_format json --output_dir .
NUNCA use --model medium.en para áudio vietnamita — .en traduz em vez de transcrever. Sempre --language vi.
Saída: transcript.json — array de entradas a nível de palavra {text, start, end}.
Etapa 2: clean_transcript.py
Reutiliza lógica do editor 9:16 (mkt-hyperframe-talking-head-video/scripts/clean_transcript.py). Remove U+FFFD, aplica dicionário a nível de palavra e frase VN (alphabit→Alphabet, Cod→Code, etc.), agrupa em frases de 3-5 palavras. Saída: transcript-cleaned.json. (Sem caption-groups.json — legendas estão DESLIGADAS em 16:9.)
Etapa 3: detect_scenes.py
Lê transcript-cleaned.json + script.txt → infere 5 fronteiras de cena usando o esqueleto padrão de vídeo de conhecimento:
| # | Tipo | Dica de kicker padrão | Variante |
|---|---|---|---|
| 1 | gancho | Primeira frase do roteiro | tier-row (sensação de pilha pós via kind=hook) |
| 2 | problema | Onde o roteiro transita para "ChatGPT/AI antigo", "difícil", "quebra", "problema"… | chats-stack |
| 3 | solução | Onde o roteiro apresenta a ferramenta/método | hero-orb |
| 4 | recapitulação | Onde o roteiro mostra resultado numérico ("X horas", "Y clientes") | counter-row |
| 5 | cta | Última frase com comentário/salvar/seguir gatilho | terminal-row |
Se o roteiro não tiver 5 partes claras, gera menos (mín. 3) e avisa o usuário. Heurística: dividir a transcrição por fronteiras de frase em ~5 blocos com peso 1.5x para a cena 3 (solução geralmente é a mais longa).
Saída scenes-outline.json:
[
{ "num": 1, "kind": "hook", "start": 0.07, "end": 13.73, "kicker": "...", "heading": "...", "variant": "tier-row" },
{ "num": 2, "kind": "problem", "start": 13.73, "end": 27.37, "kicker": "...", "heading": "...", "variant": "chats-stack" },
{ "num": 3, "kind": "solution", "start": 27.37, "end": 47.75, "kicker": "...", "heading": "...", "variant": "hero-orb" },
{ "num": 4, "kind": "recap", "start": 47.75, "end": 53.80, "kicker": "...", "heading": "...", "variant": "counter-row" },
{ "num": 5, "kind": "cta", "start": 53.80, "end": 60.68, "kicker": "...", "heading": "...", "variant": "terminal-row" }
]
PONTO DE VERIFICAÇÃO — imprime o outline para o usuário revisar. O usuário pode editar kicker/título/variante inline e continuar. Pula o ponto de verificação se a skill for chamada com --auto (modo orquestradora).
Etapa 4: scaffold_project.py
Lê scenes-outline.json → enriquece cada cena com:
accent_words— derivado do título (extrair números + últimos 2-3 substantivos)content— esquema específico do padrão (vejaassets/templates/)badges— 1-3 badges flutuantes por cenabrollEnd,hasBreath— para agendamento SPLIT↔PIPpip_events— derivado do tempo deaccent_wordsdentro da cena
Escreve scenes.json. Também copia automaticamente estes ativos auto-contidos do assets/ da skill para o workspace:
| Ativo | Origem | Destino | Propósito |
|---|---|---|---|
| 6 arquivos SFX | assets/sfx/ | <workspace>/sfx/ | Sons de batida (camera-flash, whoosh, búng-tay, Laser, ting, Discord-notification) |
| Logos da marca | assets/logos/{chatgpt,gemini,claude,claude-code}.{png,jpg} | <workspace>/assets/logos/ | Anexados automaticamente às composições (avatares chats-stack, hero-orb, badge de ferramenta tier-row) |
| Avatar | assets/avatar.jpg | <workspace>/assets/avatar.jpg | Miniatura do canal para banner de inscrição yt-lower-third |
| YT lower-third | assets/compositions/yt-lower-third.html | <workspace>/compositions/yt-lower-third.html | Suporte de banner de inscrição, últimos 3s do vídeo |
Se um ativo de origem estiver faltando no pacote da skill, faz fallback silencioso para o caminho legado do workspace (workspace/assets/...). Se nenhum for encontrado, esse ativo é pulado (as composições degradam graciosamente — avatares de texto em vez de logotipos, sem lower-third).
Etapa 5: 🔥 FAN-OUT DE SUBAGENTES LLM (criação de composição) 🔥
generate_compositions.py está OBSOLETO. Não o chame. O gerador Python Jinja2 colapsa cada cena em 1 dos 5 arquétipos fixos (hook → tier-row, problem → chats-stack, solution → hero-orb, recap → counter-row, cta → terminal-row), não consegue se adaptar a metáforas específicas de cena (por exemplo, "scroll-tape-wasted", "two-clock-comparison", "right-tool-vehicles") e quebra em listicles com 6+ cenas (vários tip-N colapsam para o mesmo nome de arquivo → sobrescrevem).
Método canônico: a orquestradora (ou usuário) cria N agentes de propósito geral paralelos (1 por cena) em uma única mensagem para que executem simultaneamente. Cada subagente:
- Lê seu bloco de cena de
visual-plan.json(caminho:<workspace>/visual-plan.json, índice da cenanum-1) - Lê referências da skill orquestradora:
references/composition-patterns.md(8 padrões testados em produção),references/slide-design-tokens.md(paleta + tipografia) - Escolhe o padrão certo para a metáfora de sua cena — adapta livremente (hero-orb pode se tornar vault+spokes, stats-3card pode se tornar two-clock-comparison)
- Cria
compositions/scene-{num}.htmldo zero com: viewport 1200×1080, CSS com escopo via[data-composition-id="scene-{num}"], timeline GSAP registrada emwindow.__timelines["scene-{num}"], sem!important, semimage-slotembutido (imagem estilo papel-couro vive apenas na camada raiz)
O resultado: cada cena recebe um arquivo de composição único e adequado à metáfora. Sem colisões, sem bloqueio dos 5 arquétipos chatos.
Veja o mkt-full-video-with-11-hyperframe-heygen-16-9/SKILL.md da orquestradora, Etapa 4d, para o modelo completo de prompt do subagente.
Logos da marca em composições (subagentes referenciam estes)
Subagentes incorporam logotipos da marca quando seu padrão precisa deles. Os logotipos estão em <workspace>/assets/logos/:
| Uso do padrão | Elemento da marca |
|---|---|
| "After" do gancho tier-row | Pílula tool-badge (canto superior direito) — logotipo + nome do Claude. |
| Linhas de falha chats-stack do problema | Logotipos ChatGPT/Gemini anexados automaticamente quando name corresponde à palavra-chave (chatgpt/gpt → chatgpt.png; gemini/google → gemini.jpg). |
| Orbe hero-orb / vault da solução | Logotipo da marca dentro do brilho do orbe (padrão Claude). |
| Terminal-row do CTA | Nenhum logotipo por padrão. |
Subagentes fazem fallback para avatar de texto se assets/logos/ não existir (sem flicker).
Referência de padrões (8 arquétipos, subagentes escolhem + adaptam)
O references/composition-patterns.md da orquestradora fornece 8 padrões testados em produção:
| Padrão | Melhor para | Motivo interno |
|---|---|---|
tier-row before-after | Contraste de gancho | 2 linhas de nível (antes rosa/vermelho + depois lima/verde) com letra + itens |
chats-stack | Problema / falha / demonstração Edit-Regen | Linha do usuário + 2-3 linhas de falha da IA + carimbo de link quebrado |
hero-orb + spec-trio | Solução / mecanismo / vault central | Orbe brilhante + ícones de tarefa + 3 linhas de nível de especificação |
counter-row | Recapitulação / prova numérica | Contador grande (DE → PARA) + clientes + tag delta |
comment-terminal | CTA / "comentário X" | Letra de nível + terminal macOS simulado + 2 cartões-presente |
stats-3card | Introdução de conhecimento / revelação de 3 fatos | 3 colunas estilo landing page com // LBL + número gradiente |
comparison-2col | "Quando usar qual" | Chips Sim/Sim de 2 colunas |
image-slot | (OBSOLETO — imagem na camada raiz) | — |
Subagentes adaptam livremente: por exemplo, hero-orb → "vault + 5 raios de chat", stats-3card → "two-clock-comparison", comparison-2col → "3 cartões de veículo em nível". O documento de padrões fornece o esqueleto (HTML + CSS + GSAP), o LLM faz a adaptação criativa.
Etapa 6: generate_root_index.py
Lê scenes.json + total_duration da transcrição → renderiza assets/templates/index.html.j2:
- Raiz 1920×1080 com
#slide-bg,#heygen-bg,#avatar-frame > .avatar-breathing > .avatar-punch > #v-source <audio id="a-source">rastreia o áudio original do source.mp4 (faixa 1)- 6
<audio>SFX conectados comdata-startabsoluto (fronteiras das cenas) - Marca da marca no canto superior esquerdo
- Bloco GSAP:
- Entrada inicial (fade-in do avatar, fade-in da marca)
- Constantes SPLIT/PIP + helpers
goPIP(t)/goSplit(t) - Array
PIP_EVENTSorientado porpip_eventspor cena de scenes.json - Estratégia de zoom visual "Gancho Híbrido" em
.avatar-breathing:- Cena HOOK: rampa lenta 1.0 → 1.10 ao longo da duração da cena (construção de drama,
power2.in) - Transição HOOK→BODY: reset brusco 1.10 → 1.0 (liberação de tensão, 0.5s
power3.in) - Cenas BODY (2..N-1) em eventos PIP-IN: batidas de punch de 1.06 (ritmo,
power2.out→power3.out) - Cena CTA: push suave 1.0 → 1.04 (fechamento,
sine.inOut)
- Cena HOOK: rampa lenta 1.0 → 1.10 ao longo da duração da cena (construção de drama,
- Pequeno punch por início de cena (1.06) em
.avatar-punchpara batida de transição
Uso (chamado pela orquestradora)
# Orquestradora chama esta skill após Fase 1 + 2
# A pasta <workspace> já contém voiceover.mp3, source.mp4, script.txt
python3 scripts/transcribe_audio.py --workspace <pasta>
python3 scripts/clean_transcript.py --workspace <pasta>
python3 scripts/detect_scenes.py --workspace <pasta> [--auto]
python3 scripts/scaffold_project.py --workspace <pasta>
# Etapa 6: orquestradora cria subagentes LLM paralelos (1 por cena)
python3 scripts/generate_root_index.py --workspace <pasta>
python3 scripts/scaffold_infographic_slots.py --workspace <pasta> # opcional
python3 scripts/lint_and_preview.py --workspace <pasta>
Observações
- Sem legendas: Esta skill não gera legendas. A entrega de conteúdo depende da voz do avatar + metáforas visuais.
- Ponto de verificação do esboço: A Etapa 3 fornece um ponto de verificação para revisão do usuário, a menos que
--autoseja passado. - Fallback de padrões: Se um ativo de logotipo estiver faltando, as composições usam texto em vez de imagens.
- Integração com orquestradora: Esta skill espera ser chamada por uma orquestradora que prepara os arquivos de entrada (
voiceover.mp3,source.mp4,script.txt). - 8 padrões flexíveis: Os subagentes não estão limitados a 5 arquétipos — eles podem adaptar qualquer um dos 8 padrões para se adequar à metáfora da cena.