Communitygithub.com

ChuchoMonster/brand-video-pipeline

Pipeline completo de ponta a ponta para criar vídeos explicativos/promocionais de marca multi-inquilino. Gera um vídeo de marca completo a partir de uma URL — extrai identidade da marca, escreve roteiro, gera voz + avatar com IA + imagens B-roll + música de fundo, monta no HyperFrames e renderiza.

O que é brand-video-pipeline?

Este skill implementa um pipeline automatizado e multi-inquilino para produção de vídeos explicativos e promocionais de marca. O processo começa com a extração da identidade visual de uma marca a partir de uma URL (paleta de cores, tipografia, tom de voz), seguido pela síntese de um roteiro personalizado com base no conteúdo do site. Em seguida, gera voz sintética via ElevenLabs, um avatar animado via HeyGen (com chromakey e padding simétrico), imagens B-roll abstratas usando o modelo Nano Banana 2 da KIE.AI, e uma trilha musical de fundo instrumental. Todos os ativos são montados em uma composição HyperFrames (baseada em HTML/GSAP) e renderizados em MP4. O pipeline foi projetado para escalar para qualquer marca B2B com configuração mínima por inquilino, suportando frases de gatilho como "Hyper Frames para <url>" ou "vídeo explicativo para <marca>". As plataformas envolvidas incluem ElevenLabs, HeyGen, KIE.AI e HyperFrames, todas controladas por variáveis de ambiente para chaves de API.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ChuchoMonster/brand-video-pipeline/tree/HEAD/skill

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Pipeline HyperFrames — Vídeos Explicativos de Marca Multi-Inquilino

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 "crie um vídeo para " ou similar
  • O usuário diz "vamos testar isso em "

Ambiente necessário (em $PIPELINE_ROOT/.env — copie .env.example)

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
ELEVENLABS_VOICE_ID=...   # Voz do narrador padrão
HEYGEN_TALKING_PHOTO_ID=...  # Aparência do avatar padrão

Estrutura do projeto

$PIPELINE_ROOT/            # raiz deste repositório
  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 (único diretório de trabalho; troca assets por marca)
    index.html
    styles/
      brand.css           # interface da marca — único arquivo com CSS específico da marca
      template.css        # movimento agnóstico de marca
      layouts.css         # sistema de 10 layouts
    assets/
      voice.mp3           # saída do 11Labs (com padding)
      avatar.webm         # saída do HeyGen (chromakey + padding)
      music.mp3           # música de fundo 11Labs
      broll-*.png         # B-roll do Nano Banana
    renders/

Para produção multi-inquilino, o Estágio 0 futuro deve copiar template-16x9/ por marca. Por enquanto, troque os assets no local para cada renderização.


Estágios do Pipeline

Estágio 1 — Extração da Marca

Invoque o skill brand-book na URL alvo. Ele produz:

  • brands/<marca>/brand.json — paleta, tipografia, resumo de voz/tom
  • brands/<marca>/css-variables.json — TODAS as variáveis CSS do site ao vivo
  • brands/<marca>/reference.png — captura de tela da página inicial

Extraia as duas cores fixas que orientam todos os estágios posteriores:

  • bg: cor de fundo da marca (tipicamente quase preta, ex. #050508)
  • accent: cor de destaque da marca (tipicamente um tom saturado, ex. #8b9cf7)

Estas se tornam substituições nos prompts de B-roll e em styles/brand.css.

Estágio 2 — Leia o site, entenda o negócio

Use WebFetch para ler a página inicial + páginas principais (serviços, equipe, preços, sobre). Sintetize:

  • O que eles vendem
  • Para quem vendem (PIC)
  • Os 1-2 diferenciais mais nítidos
  • O CTA desejado (agendar chamada, iniciar teste, 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). Portanto, 22s ≈ 60 palavras; 45s ≈ 120 palavras; 60s ≈ 160 palavras.

Estrutura (modelo de 5 cenas em 22s; escalar proporcionalmente para mais tempo):

  1. Gancho (10–15% da duração) — linha impactante de 3–6 palavras
  2. Corpo 1 — Problema (~30%) — o que está quebrado / o gargalo
  3. Corpo 2 — Estatística ou prova (~15%) — a magnitude (use gráfico do Template 2 para B-roll)
  4. Corpo 3 — Como trabalhamos (~25%) — o diferencial
  5. Final / 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 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 respeita. 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: $ELEVENLABS_VOICE_ID de .env (ou a que o usuário especificar / marca preferir — pergunte se não estiver claro).

source .env && curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/$ELEVENLABS_VOICE_ID" \
  -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 (ID de Aparência). O padrão vem de $HEYGEN_TALKING_PHOTO_ID em .env (qualquer Aparência de foto falante na sua conta HeyGen).

Sempre defina use_avatar_v_model: true no nível do personagem. O HeyGen fará fallback silencioso para Avatar IV se a Aparência não estiver inscrita no V (uma Aparência não inscrita cai para IV; a renderização não é afetada).

Carregue a voz → envie a renderização de foto falante → 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": "$HEYGEN_TALKING_PHOTO_ID",
      "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é completar (tipicamente 60–90s para IV, 5–20min para V na primeira renderização com nova Aparência)
# 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 VP9 transparente com padding de 0,5s de quadro congelado 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

# Adicionar padding de 0,5s em ambas as extremidades (preserva alpha)
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. (A regra é 0,5s de liderança + 0,5s de cauda, todas as deixa de cena do GSAP deslocadas +0,5s, desaparecimento 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 ID de Aparência:

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 (na fonte 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 completo. 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 templates fixos. As cores da marca trocam por projeto (substitua BG_HEX e ACCENT_HEX de brand.json).

Template 1 — Escultura abstrata pura (atmosfera, humor, batidas narrativas):

Renderização escultórica abstrata 3D em um fundo sólido [BG_HEX]. [FORM_DESCRIPTION], sugerindo [MOTION_INTENT]. Luz [ACCENT_HEX] refrata através e ao redor da forma com dispersão subsuperficial, projetando cáusticas suaves em um chão escuro sutilmente reflexivo. Iluminação suave de estúdio direcional. Render Octane hiper-real. Estética de keynote tech premium. Foco nítido na forma central, profundidade de campo caindo em sombra nas bordas. Sem texto, sem logotipos.

Template 2 — Gráfico de vidro (qualquer linha que cite uma estatística, comparação, crescimento, proporção, "X×", "Y%"):

Visualização de dados 3D abstrata em um fundo sólido [BG_HEX]. [CHART_TYPE] renderizado inteiramente como formas de vidro translúcido flutuantes representando [DATA_CONCEPT]. Elementos de base em vidro fosco cinza acetinado; elementos focais brilhando com dispersão subsuperficial e refração [ACCENT_HEX], projetando cáusticas suaves em um chão escuro sutilmente reflexivo. Uma linha fina de eixo off-white. Iluminação suave de estúdio direcional. Render Octane hiper-real. Estética de keynote tech premium. Composição editorial mínima com espaço negativo generoso. 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 → Template 2. Caso contrário → Template 1.

Padrão de envio (1:1 aspecto padrão; 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":"<TEMPLATE 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 — json.loads()), baixe a URL para assets/broll-N.png.

Execute várias gerações de B-roll em paralelo — KIE.AI lida bem com tarefas concorrentes.

Causa comum de 400: filtro de segurança de prompt. O Nano Banana 2 rejeita prompts que parecem legais/violência/adjacentes a conflitos (ex. "tribunal", "batalha legal", "reclamantes vs réus"). Mantenha-se estritamente dentro dos dois templates abstratos — codifique significado em geometria/cor, nunca em assunto literal. Validado em 2026-04-28: sonda abstrata mínima retorna 200 com a mesma auth/schema, então um 400 aqui é virtualmente 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 3000–600000ms).

Prompt de música padrão para fundo de anunciário B2B (validado em 2026-04-27):

Trilha instrumental otimista para um anunciário B2B. Piano moderno e brilhante tocando um padrão rítmico progressivo com notas staccato nítidas, combinado com pads de synth sutis e edificantes. Pulso leve e suave — shakers suaves ou cliques rítmicos abafados fornecendo impulso constante. Sem baterias grandes, sem bumbos, sem crashes, sem pratos. Sem vocais. Sensação confiante, animada, enérgica, otimista. Corporativo moderno, limpo, tecnológico, profissional, contemporâneo. Andamento em torno de 115 BPM. Tom maior brilhante, ensolarado mas não açucarado. Dinâmica uniforme durante toda a música — sem crescendos, sem quedas, sem clímax, sem desvanecimentos — mas com impulso rítmico constante. Soa como a trilha de fundo de um vídeo de lançamento de produto SaaS moderno.

Antipadrões a evitar no prompt:

  • "Cinematográfico" / "sombrio" / "ambiente" → produz arrasto sentimental, errado para anunciário
  • Andamento 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 breves 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:

  1. Atualize data-duration no elemento raiz, voz, avatar e música para corresponder à duração alvo
  2. Atualize as cores da marca em styles/brand.css (variáveis --bg, --accent, etc.)
  3. Atualize as fontes em brand.css se a marca usar famílias diferentes
  4. Reajuste o tempo das transições de cena na timeline GSAP para corresponder às batidas do roteiro
  5. Certifique-se de que todos os 4 elementos temporizados (vídeo do avatar, áudio da voz, áudio da música, composição raiz) tenham data-start e data-duration alinhados

Índices das trilhas de áudio: avatar=1, voice=2, music=3. Todos class="clip". Todos data-start="0".

Estágio 11 — Renderização

cd "$PIPELINE_ROOT/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 modo de fundo travam com 0% de CPU após o início da captura de quadros. 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, open -a "QuickTime Player" renders/<marca>-v<n>.mp4 para revisão.


Ciclo de iteração

A maioria das renderizações precisa de 1–3 passos:

  • v1: fazer a cadeia funcionar de ponta a ponta com padrões sensatos
  • v2: corrigir problemas óbvios (corte de rosto, música muito alta, transições...)

Habilidades Relacionadas