Pipeline HyperFrames — Vídeos Explicativos Multi-Inquilino para Marcas
Pipeline de ponta a ponta que recebe uma URL e produz um MP4 explicativo/promocional de marca finalizado. Construído e validado na ColdStart (coldstartb2b.com). Projetado para escalar para qualquer marca B2B com configuração mínima por inquilino.
Quando invocar
- O usuário diz "Hyper Frames" / "hyperframes" + uma URL ou nome de marca
- O usuário pede um vídeo explicativo/promocional para um negócio específico
- O usuário diz "faça um vídeo para " ou algo similar
- O usuário diz "vamos tentar isso em "
Ambiente necessário (em <seu-diretório-do-projeto>/.env)
KIE_AI_API_KEY=... # Nano Banana 2 + Seedance 2 via KIE.AI
HEYGEN_API_KEY=... # Geração de avatar HeyGen
ELEVENLABS_API_KEY=... # Voz + música 11Labs
Estrutura do projeto
<seu-diretório-do-projeto>/
brands/
<marca>/ # um diretório por marca (criado pelo brand-book)
brand.json
colors.md
typography.md
voice-tone.md
reference.png
template-16x9/ # a composição ativa (diretório de trabalho único; troca assets por marca)
index.html
styles/
brand.css # interface da marca — único arquivo com CSS específico da marca
template.css # movimento independente da marca
layouts.css # sistema de 10 layouts
assets/
voice.mp3 # saída do 11Labs (com padding)
avatar.webm # saída do HeyGen (com chromakey e padding)
music.mp3 # música de fundo do 11Labs
broll-*.png # B-roll do Nano Banana
renders/
Para produção multi-inquilino, o futuro Estágio 0 deve copiar template-16x9/ por marca. Por enquanto, troque os assets no local por renderização.
Estágios do pipeline
Estágio 1 — Extração da marca
Invoque a skill brand-book na URL alvo. Ela produz:
brands/<marca>/brand.json— paleta, tipografia, resumo de voz/tombrands/<marca>/css-variables.json— TODAS as variáveis CSS do site ativobrands/<marca>/reference.png— captura de tela da página inicial
Extraia as duas cores fixas que direcionam todos os estágios subsequentes:
bg: cor de fundo da marca (geralmente perto do preto, ex.#050508)accent: cor de destaque da marca (geralmente um matiz saturado, ex.#8b9cf7)
Elas se tornam substituições nos prompts de B-roll e em styles/brand.css.
Estágio 2 — Ler o site, entender o negócio
Use WebFetch para ler a página inicial + páginas-chave (serviços, equipe, preços, sobre). Sintetize:
- O que eles vendem
- Para quem eles vendem (ICP)
- Os 1-2 diferenciadores mais marcantes
- A CTA desejada (agendar uma chamada, iniciar trial, etc.)
Isso se torna a substância do roteiro.
Estágio 3 — Roteiro
Escreva um roteiro para a duração solicitada. Regra de ritmo: ~2,7 palavras por segundo de voz (cadência multilingual_v2). Então 22s ≈ 60 palavras; 45s ≈ 120 palavras; 60s ≈ 160 palavras.
Estrutura (modelo de 5 cenas para 22s; escale proporcionalmente para maior duração):
- Gancho (10–15% da duração) — linha de 3–6 palavras impactante
- Corpo 1 — Problema (~30%) — o que está quebrado / o gargalo
- Corpo 2 — Estatística ou prova (~15%) — a magnitude (use gráfico do Template 2 para B-roll)
- Corpo 3 — Como trabalhamos (~25%) — o diferenciador
- Fim / CTA (~15%) — convite + logotipo da marca
Para vídeos mais longos (45s+), adicione cenas de Corpo adicionais entre Corpo 1 e Corpo 2 (ex. "Corpo 1a — Ponto de dor específico", "Corpo 1b — Custo da inação").
Prosódia para o 11Labs eleven_multilingual_v2: pontuação dita o ritmo (vírgulas = micropausas, pontos = pausas completas, travessões = batida). Não se preocupe com SSML ou tags de emoção — multilingual_v2 não as honra. Apenas escreva prosa conversacional com pontuação natural.
Salve o roteiro em template-16x9/script.txt para rastreabilidade.
Estágio 4 — Voz (11Labs)
Chame o TTS do 11Labs com eleven_multilingual_v2. Voz padrão: <seu-id-de-voz-do-elevenlabs> (defina isso para uma voz da sua biblioteca do 11Labs, ou o que o usuário especificar / a marca preferir — pergunte se não estiver claro).
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/<seu-id-de-voz-do-elevenlabs>" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"<roteiro>","model_id":"eleven_multilingual_v2"}' \
--output assets/voice_raw.mp3
Pós-processe o volume para 92% via FFmpeg (padrão do pipeline):
ffmpeg -y -i voice_raw.mp3 -af "volume=0.92" -c:a libmp3lame -b:a 192k voice.mp3
Estágio 5 — Avatar (HeyGen)
Escolha um talking_photo_id (Look ID). Defina seu padrão para um Look da sua própria conta HeyGen: <seu-id-de-foto-falante-do-heygen>.
Sempre defina use_avatar_v_model: true no nível do personagem. O HeyGen retrocede silenciosamente para Avatar IV se o Look não estiver inscrito no V (a saída do Avatar IV renderiza bem).
Carregue a voz → envie renderização talking_photo → consulte → baixe → chromakey:
# Carregar áudio
AUDIO_ID=$(curl -s -X POST "https://upload.heygen.com/v1/asset" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: audio/mpeg" \
--data-binary @assets/voice.mp3 | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['id'])")
# Enviar renderização
VID=$(curl -s -X POST "https://api.heygen.com/v2/video/generate" \
-H "X-Api-Key: $HEYGEN_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF | python3 -c "import json,sys;print(json.load(sys.stdin)['data']['video_id'])"
{
"video_inputs": [{
"character": {
"type": "talking_photo",
"talking_photo_id": "<seu-id-de-foto-falante-do-heygen>",
"use_avatar_v_model": true
},
"voice": { "type": "audio", "audio_asset_id": "$AUDIO_ID" },
"background": { "type": "color", "value": "#00FF00" }
}],
"dimension": { "width": 720, "height": 1280 }
}
EOF
)
# Consultar até ser concluído (normalmente 60–90s para IV, 5–20min para V na primeira renderização com novo Look)
# GET https://api.heygen.com/v1/video_status.get?video_id=$VID → data.status == "completed"
# Então baixe data.video_url para assets/avatar_green.mp4
Estágio 6 — Chromakey + padding simétrico
Converta MP4 com tela verde do HeyGen → webm transparente VP9 com quadro congelado de 0,5s em ambas as extremidades:
# Chromakey + despill → webm transparente bruto
ffmpeg -y -i avatar_green.mp4 \
-vf "chromakey=0x00FF00:0.10:0.05,despill=type=green:mix=0.6:expand=0" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.raw.webm
# Adicione quadros congelados de 0,5s em ambas as extremidades (preserva alfa)
ffmpeg -y -c:v libvpx-vp9 -i avatar.raw.webm \
-vf "tpad=start_duration=0.5:start_mode=clone:stop_duration=0.5:stop_mode=clone" \
-c:v libvpx-vp9 -pix_fmt yuva420p -auto-alt-ref 0 -b:v 0 -crf 30 -an \
avatar.webm
Adicione padding simétrico de 0,5s de silêncio em ambas as extremidades do voice.mp3 para que os offsets de áudio correspondam ao tempo do avatar:
ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t 0.5 -c:a libmp3lame -b:a 192k silence.mp3
ffmpeg -y -f concat -safe 0 -i <(printf "file '%s/silence.mp3'\nfile '%s/voice_raw.mp3'\nfile '%s/silence.mp3'\n" "$PWD" "$PWD" "$PWD") \
-c:a libmp3lame -b:a 192k voice.mp3
Isso alcança a regra de tempo: avatar aparece → fala começa → fala termina → avatar desaparece. Veja project_audio_video_timing.md (criado na Fase 9 se ausente — a regra é 0,5s de lead + 0,5s de tail, todas as dicas de cena GSAP deslocadas +0,5s, fade-out final começa 0,1s após o fim da fala).
Estágio 7 — Calibração de object-position
A posição do rosto do avatar no quadro depende da foto de origem, então recalibre por Look ID:
ffmpeg -y -ss 0.7 -i avatar.webm -vframes 1 avatar-frame-check.png
Leia o quadro, meça a coordenada y do centro do rosto (no quadro de 1280 de altura). Calcule object-position por layout:
object_position_y_pct = ( (face_y_px / 1280) * scaled_height_for_layout - layout_slot_height/2 ) / (scaled_height_for_layout - layout_slot_height) * 100
Na prática: rosto no terço superior do quadro (face_y ~380) → use '50% 30%' para slots estreitos, '50% 50%' para slots de quadro inteiro. Atualize LAYOUT_AVATAR_SLOTS em index.html. Nunca adivinhe — sempre calibre a partir de um quadro extraído.
Estágio 8 — Imagens B-roll (Nano Banana 2 via KIE.AI)
Dois modelos fixos — veja project_image_direction_templates.md para as versões completas. As cores da marca trocam por projeto (substitua BG_HEX e ACCENT_HEX do brand.json).
Modelo 1 — Escultura abstrata pura (atmosfera, clima, batidas narrativas):
Render 3D escultórico abstrato em fundo sólido
[BG_HEX].[FORM_DESCRIPTION], sugerindo[MOTION_INTENT]. Luz[ACCENT_HEX]refrata através e ao redor da forma com dispersão de subsuperfície, projetando cáusticas suaves em um piso escuro sutilmente reflexivo. Iluminação de estúdio direcional suave. Render Octane hiper-real. Estética de keynote tecnológico premium. Foco nítido na forma central, profundidade de campo suave nas bordas. Sem texto, sem logotipos.
Modelo 2 — Gráfico de vidro (qualquer linha que mencione uma estatística, comparação, crescimento, proporção, "X×", "Y%"):
Visualização de dados 3D abstrata em fundo sólido
[BG_HEX].[CHART_TYPE]renderizado inteiramente como formas de vidro translúcido flutuantes representando[DATA_CONCEPT]. Elementos de base em vidro cinza fosco e suave; elementos focais brilhando com dispersão de subsuperfície[ACCENT_HEX]e refração, projetando cáusticas suaves em um piso escuro sutilmente reflexivo. Uma fina linha de eixo off-white. Iluminação de estúdio direcional suave. Render Octane hiper-real. Estética de keynote tecnológico premium. Composição editorial minimalista com amplo espaço negativo. Sem texto, sem números, sem rótulos, sem logotipos.
Regra de decisão por cena: se a linha do roteiro cita um número/estatística/comparação → Modelo 2. Caso contrário → Modelo 1.
Padrão de envio (padrão 1:1 de aspecto; qualquer aspecto suportado). Sempre capture código HTTP + corpo para que falhas 4xx se autodiagnostiquem:
source .env && RESPONSE=$(curl -sS -w "\nHTTP_CODE:%{http_code}" -X POST "https://api.kie.ai/api/v1/playground/createTask" \
-H "Authorization: Bearer $KIE_AI_API_KEY" -H "Content-Type: application/json" \
--data-binary @- <<EOF
{"model":"nano-banana-2","input":{"prompt":"<MODELO COM SLOTS PREENCHIDOS>","output_format":"png","image_size":"1:1"}}
EOF
)
echo "$RESPONSE"
[[ "$RESPONSE" == *"HTTP_CODE:200"* ]] || { echo "Falha no envio KIE — veja corpo acima"; exit 1; }
Consulte https://api.kie.ai/api/v1/playground/recordInfo?taskId=<id> a cada 4s até data.state == "success", analise data.resultJson (é uma string JSON — use json.loads()), baixe a URL para assets/broll-N.png.
Execute várias gerações de B-roll em paralelo — o KIE.AI lida bem com tarefas concorrentes.
Causa comum de 400: filtro de segurança de prompt. O Nano Banana 2 rejeita prompts que soam como adjacentes a lei/violência/conflito (ex. "tribunal", "batalha legal", "reclamantes vs réus". Fique estritamente dentro dos dois modelos abstratos — codifique o significado em geometria/cor, nunca em assunto literal. Validado em 2026-04-28: sonda abstrata mínima retorna 200 com a mesma autenticação/esquema, então um 400 aqui é quase sempre conteúdo do prompt.
Estágio 9 — Música de fundo (11Labs Music)
source .env && curl -s -X POST "https://api.elevenlabs.io/v1/music?output_format=mp3_44100_128" \
-H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
-d '{
"prompt": "<PROMPT DE MÚSICA>",
"music_length_ms": 22000,
"force_instrumental": true,
"model_id": "music_v1"
}' --output assets/music_raw.mp3
Retorna bytes de áudio de forma síncrona. music_length_ms corresponde à duração da composição (faixa de 3000–600000ms).
Prompt de música padrão para fundo de anúncio B2B (validado em 2026-04-27):
Base instrumental otimista para um anúncio B2B. Piano moderno brilhante tocando um padrão rítmico progressivo com notas staccato nítidas, combinado com pads de sintetizador sutis e edificantes. Pulso leve e suave — shakers suaves ou cliques rítmicos suaves fornecendo impulso constante. Sem baterias grandes, sem bumbos, sem crashes, sem pratos. Sem vocais. Sensação confiante, animada, energética, otimista. Moderno, limpo, tecnológico, profissional, corporativo contemporâneo. Ritmo em torno de 115 BPM. Tom maior brilhante, ensolarado, mas não açucarado. Dinâmica uniforme em toda a extensão — sem crescendos, sem quedas, sem clímax, sem fades — mas com impulso rítmico constante. Soa como a base de um vídeo de lançamento de produto SaaS moderno.
Anti-padrões a evitar no prompt:
- "Cinematográfico" / "sombrio" / "ambiente" → produz arrasto sentimental, errado para anúncio
- Ritmo abaixo de 90 BPM → muito sonolento
- Mencionar crescendos, clímax, mudanças de dinâmica → compete com a voz
- Esquecer "sem vocais" → ElevenLabs pode adicionar humming
Misture para -20dB com fades curtos para que fique invisível sob a voz:
ffmpeg -y -i music_raw.mp3 \
-af "volume=-20dB,afade=t=in:st=0:d=0.4,afade=t=out:st=<fim-0.6>:d=0.6" \
-c:a libmp3lame -b:a 192k music.mp3
Estágio 10 — Montagem da composição
O template-16x9/index.html é a composição de trabalho. Para cada renderização:
- Atualize
data-durationno elemento raiz, voz, avatar e música para corresponder à duração alvo - Atualize as cores da marca em
styles/brand.css(variáveis--bg,--accent, etc.) - Atualize as fontes em
brand.cssse a marca usar famílias diferentes - Re-ajuste os tempos de transição de cena na timeline GSAP para corresponder às batidas do roteiro
- Certifique-se de que todos os 4 elementos cronometrados (vídeo do avatar, áudio da voz, áudio da música, composição raiz) tenham
data-startedata-durationalinhados
Índices das faixas de áudio: avatar=1, voice=2, music=3. Todos com class="clip". Todos com data-start="0".
Estágio 11 — Renderização
cd "$HOME/<seu-diretório-do-projeto>/template-16x9" && \
npx hyperframes lint && \
npx hyperframes render --output renders/<marca>-v<n>.mp4
CRÍTICO: Execute a renderização em primeiro plano. Renderizações em segundo plano travam em 0% de CPU após a captura de quadros começar. Use uma chamada Bash em primeiro plano com timeout: 300000. A renderização leva ~1–2 min para uma composição de 22s, ~3–4 min para 45s.
Após a renderização ser concluída, open -a "QuickTime Player" renders/<marca>-v<n>.mp4 para revisão.
Loop de iteração
A maioria das renderizações precisa de 1–3 passagens:
- v1: faça a cadeia funcionar de ponta a ponta com padrões sensatos
- v2: corrija problemas óbvios (corte de rosto, música muito alta, transições de cena mal posicionadas)
- v3: ajuste o design para qualidade de produção