HTML Motion Pipeline (explicador 9:16, VO + SFX → MP4)
Algoritmo testado e aprovado. Cada etapa possui comandos prontos para uso em assets/pipeline/.
Consulte a implementação completa de referência: assets/pipeline/index.fc-reference.html (projeto Function Calling — copie e substitua o conteúdo, não escreva do zero).
Por que este pipeline
- Determinístico: timeline GSAP pausada, busca por frame → MP4 = prévia exata.
- VO do próprio usuário (arquivo ElevenLabs/microfone), não TTS; controle de velocidade.
- Auditoria de layout automática detecta texto saindo do canvas e colisões — obrigatório passar antes da renderização completa (economiza 1338 frames).
- Linhas de conexão limpas: âncoras nas bordas dos nós, em camada inferior (consulte a Armadilha nº 1).
Princípios fundamentais
O visual serve ao roteiro e à VO, não o contrário.
- Tudo que aparece na tela deve estar no roteiro e ser dito na VO. Elementos interessantes mas não narrados — remova, por melhores que sejam.
- Por outro lado, cada ideia/frase importante do roteiro deve ter uma imagem própria que aparece exatamente quando essa frase é dita. Frases que são apenas texto estático = cena "vazia" — adicione um visual.
- Muitas cenas não são problema — o importante é que cada cena siga a VO e o roteiro.
- Quanto mais imagens e animações, melhor (mais dinâmico). Não economize na adição de visuais; riqueza visual é um diferencial, não uma fraqueza.
- A ordem e o timing do visual = ordem e timing da menção na VO (a partir dos timestamps da transcrição), e não uma lógica própria.
- A qualidade dos detalhes visuais também é mantida: ícones claramente legíveis quanto ao seu significado, elementos equilibrados e sem flutuação.
Fluxo (siga a ordem)
| # | Etapa | Saída |
|---|---|---|
| 1 | Capturar VO do usuário + dividir por segmentos (pausas de respiração) | meta.json |
| 2 | Ajustar velocidade da VO via ffmpeg atempo + inserir pausas; escolher variante | vo.wav |
| 3 | Transcrição por palavra (faster-whisper, pip install faster-whisper) | assets/words.json |
| 4 | Construir index.html (8 cenas seguindo o timing da VO) + sfx_score.py | HTML + SFX WAV |
| 5 | Mixar VO + SFX → public/full_mix.mp3 | áudio final |
| 6 | Auditoria de layout (audit2.mjs + audit_s2.mjs) — obrigatório 0 overflow | relatório |
| 7 | Renderizar frames (render_frames.mjs) → 1338 PNGs | frames/ |
| 8 | Codificar (encode.sh) → MP4 | public/*.mp4 |
| 9 | Verificar visual do MP4 final — extrair frames do MP4, analisar via visão | confirmação limpa |
Instalação única
cd <projeto>
npm init -y && npm install playwright-core gsap
pip install faster-whisper # para transcrição por palavra
# necessário: Google Chrome (/Applications/Google Chrome.app), ffmpeg
Scripts do pipeline
assets/pipeline/:
render_frames.mjs— percorre a timeline quadro a quadro, captura 1080×1920 @30fps.snap.mjs— captura de segundos específicos (node snap.mjs 1.0 6.5 17.5) para verificar visuais.audit2.mjs— verifica TODAS as cenas: texto saindo do canvas / entrando na zona de UI inferior (>1560px) / colisões.audit_s2.mjs— auditoria de 1 cena (sc2) em vários segundos (detecta revelação prematura, encostado na borda).audit_overlap.mjs— detecta texto REALMENTE sobreposto (texto×texto, texto×img, texto×botão). Inteligente para distinguir colisões reais das que são by-design: label dentro de container svg, rabiscos/riscos/linhas transversais, legendas flex lado a lado → não são reportadas. Executenode assets/pipeline/audit_overlap.mjs→ alvoTOTAL sobreposição: 0.audit_center.mjs— detecta conteúdo "pendurado no topo" (2/3 inferior vazio). Mede o bounding do conteúdo de cada cena, calcula o desvio do ponto central ideal (y≈960 para 1920px). Desvio > 250px = ⚠ PENDURADO. Executenode assets/pipeline/audit_center.mjs.typing-prompt.js— receita de animação "typing prompt" (essência do tema coding/AI): o prompt é digitado letra por letra + cursor piscando, e então o app responde (muda cor → erro → corrige → itera). Exemplo completo: repo do vídeo09-vibe-coding/index.htmlcena SK4.encode.sh— ffmpeg → H.264 yuv420p CRF18 + AAC 192k ++faststart.sfx_score.py— partitura SFX procedural sincronizada com o timing das palavras.index.fc-reference.html— implementação completa (copie e substitua o conteúdo).
Convenções HTML (em index.fc-reference.html)
#stage1080×1920, fundo dot-grid;#world(câmera rígida, escala suave por cena); cenas =.scene(visibility hidden, exibir/esconder via timeline).- Legenda por palavra:
assets/words.json→ agrupar em chunks de ≤4 palavras, um chunk = uma.line(position:absolute, empilhadas para não expandir a caixa), palavra ativa.on, palavra-chave.key(âmbar). Posição 390px a partir da base (seguro contra UI do Reels/TikTok que cobre ~360px inferiores). - Linhas de conexão: função
link(svg,idA,idB)calcula âncora na BORDA do nó (edge/edgeT) — a linha NÃO sai do centro do logo. SVG.wirescolocado como primeiro filho da.scene(z-index:0) para ficar atrás dos cards (z-index:2). Curva suave (bow ≤26px), cor cinza#7A81888px; linha ativa.hotâmbar 15px. - Logo do agente:
OPENCLAW_SVGinline (lagosta vermelha), inserido automaticamente em cada.node.darkcontendo🤖. Substitua se desejar outra identidade. - GSAP determinístico: timeline
paused, exporwindow.__tlewindow.__updateSub. Modo?t=<segundo>para snapshot estático (headless),?debugpara scrub manual.
Gatilho
Quando o usuário mencionar a frase "pipeline motion explainer", ou pedir "vídeo motion explicativo 9:16", ou disser "igual ao vídeo do Function Calling da última vez" → carregue esta skill. Não confundir com motion-format / bang-motion (outras skills). O VO do usuário sempre é enviado como arquivo a cada sessão — esta skill armazena O MODO DE FUNCIONAMENTO, não ativos de áudio/conteúdo.
Armadilhas (não repita)
- Linha atravessando logo/texto → garantir: (a) SVG wires como primeiro filho da cena, (b)
z-index:0wires vsz-index:2cards, (c) âncora usandolink()na borda. - Legenda cobrindo cards / entrando na zona de UI → uma linha por empilhamento (absolute), no máximo 4 palavras/chunk, base ≥390px.
window.tlundefined durante render → o nome exposto deve serwindow.__tl(com__), senão 74% dos frames ficam idênticos/estáticos. Verificar:md5 frames/* | uniq -c.- Render do background reiniciado → garantir que não haja
render_framesantigo rodando (pgrep -fl render_frames) antes de novo render; apagarframes/antes de começar. - Auditoria DOM não substitui verificação visual do MP4. A auditoria detecta overflow e colisões de bounding-box, mas NÃO detecta linha atravessando logo / texto cobrindo card — isso só é visível no pixel final. Após codificação, extraia quadros-chave do MP4 (
ffmpeg -ss <t> -i out.mp4 -frames:v 1 f.png) e analise via vision_analyze. - Conteúdo "pendurado no topo" (2/3 inferior vazio). Isso é o que mais passa despercebido, pois a auditoria comum só verifica overflow, não equilíbrio. Causa: todos os filhos de
.herocomposition:absolute→ flexboxjustify-content:centerNÃO tem efeito sobre eles. Solução: tornar os filhos de.herocom fluxo normal (block/flex flow), apenas elementos sobrepostos (badge/rabisco/marcador) permanecem absolute. OBRIGATÓRIO executaraudit_center.mjs— desvio do centro > 250px = falha. - Visual não seguindo o roteiro (o mais prejudicial). Não considere a cena "pronta" só porque a animação funciona. Exemplo real: gráfico de correlação e gráfico de idade aparecem na tela mesmo a VO nunca os mencionando. Auditoria de roteiro antes do render: (a) extrair transcrição da VO + timestamp por palavra (
words.json), (b) mapear "esta frase aparece em que momento na tela?", (c) elementos que aparecem mas não estão no roteiro → remover; frases do roteiro que são apenas texto estático → adicionar visual. Ordem do visual = ordem da menção na VO. - Render OOM (Mac 8GB). O Chromium acumula memória ao capturar centenas de screenshots → trava no meio ("Target page closed"). Solução: reiniciar o navegador a cada ±400 frames + retomada automática (pular frames já existentes e >20KB). Não renderizar 2500+ frames em uma única sessão do navegador.
- Frames antigos misturados após revisão. Se apenas algumas cenas forem revisadas e apenas os frames daquele intervalo forem removidos,
frames/fica misturado (ex.: 2770 arquivos quando precisava de 2574). Mais seguro: apagar todoframes/antes do render completo. Se houver retomada, verificar número de arquivos = TOTAL de frames antes de codificar. - Emoji escapa da auditoria DOM. Usuário pediu sem emoji — se não for verificado automaticamente, emojis podem passar porque a auditoria de bounding-box não verifica o tipo de caractere. Antes do render, executar regex Python para buscar caracteres emoji; se encontrar → substituir por SVG inline. Ícones sempre SVG.
re.findall(r'[\U0001F300-\U0001FAFF\u2600-\u27BF\u2B00-\u2BFF\uFE0F]', html)→ obrigatório 0. - Ícones e detalhes visuais devem ser legíveis no TAMANHO DE EXIBIÇÃO — auditoria DOM e auditoria de layout não capturam "o ícone não está claro". Um SVG pode ter a forma correta no código mas, no tamanho de render (ex.: ícone de 180px em um diagrama), parecer outra coisa: ícone de cérebro com contorno aberto é lido como nuvem/flor, não como cérebro. Solução: antes do render completo, extrair frame do MP4 e ampliar (crop) o ícone/diagrama-chave e avaliar via vision_analyze — "isto é claramente legível como X?". Se ambíguo, simplificar a forma (silhueta inteira > contorno aberto) e aumentar o tamanho. Auditoria de bounding-box só verifica posição, não legibilidade da forma.
- Elementos de comparação equilibrados (barra/coluna A-vs-B) devem estar em um único grupo visual. Barras "soltas" fora do card pai (posição absoluta separada) quebram o equilíbrio e correm risco de sobrepor outros elementos quando o conteúdo muda de altura. Caso real: barras de músculo atrofiado/forte soltas fora do card de academia, colidindo com outro card. Solução: colocar cada barra DENTRO do seu próprio card/célula de coluna; diferenças de comprimento da barra são intencionais (comprimento = magnitude), mas a largura do card e a linha de base devem ser iguais. Verificar via audit_overlap após cada revisão de layout.
- Texto sobreposto mesmo parecendo "só um pouquinho". Não confie nos olhos; use
audit_overlap.mjsque mede o bounding-box real. Um enorme?, números grandes decorativos ou títulos longos frequentemente sobrepõem outro texto sem que se perceba. - Tema coding/AI parece sem vida sem animação de digitação. Texto estático não transmite o funcionamento do vibe coding. Use a receita
typing-prompt.js: prompt digitado letra por letra + cursor piscando + app responde (muda cor → erro → corrige → itera). - Logo/ícone vindo da web: baixar SVG oficial (CDN jsDelivr / repo GitHub da marca), então inserir inline como texto no HTML — não usar
<img src>para arquivos externos, para que o render headless não dependa de rede. Remover animações SMIL para que a saída seja determinística.
Regras de áudio (usuário Hasbi)
- A VO de produção deve ser a voz do próprio usuário (arquivo ElevenLabs enviado), não TTS.
- SFX procedural via skill
procedural-sfx(sem créditos da ElevenLabs). - Apagar frames brutos e arquivos auxiliares (
frames/,shots/,*.wavpor segmento) após o MP4 ser enviado — o armazenamento do MacBook é limitado.