geração de vídeo remotion (design.md)

remotion-build — Gerar Vídeo Remotion

Gera um MP4 usando código React a partir do DESIGN.md (produzido pela consulta remotion-consult). As legendas são a única linha do tempo, os efeitos são importados da biblioteca geral e os assets seguem o roteamento entre harnesses.

Fluxo de Trabalho

Passo 0 — Seleção de Modo (escolha um dos quatro, decida antes de agir)

1. Por modelo de categoria: o usuário quer um estilo definido, ou escolhe uma das quatro categorias em remotion-shared/categories/ (legendas para locução / visualização de dados / demonstração de produto / animação de marca) → leia o DESIGN.template.md + motion-list.md da categoria, herde o sistema de design, troque apenas conteúdo e legendas.
2. Inspiração de Referência: o usuário fornece um vídeo de referência (prioridade máxima) ou escolhe do remotion-shared/video-real-library.md → analise seu estilo de legenda, transições, ritmo e recrie com componentes da biblioteca geral de efeitos.
3. Design Livre: sem referência nem modelo → apenas evite os prompts negativos de video-anti-slop.md.
4. Seguir DESIGN existente (produzido pela consulta): a consulta já definiu DESIGN + amostra de estilo aprovada → execute estritamente segundo os tokens/§8 do DESIGN, não pergunte novamente sobre direção de estilo (Passo 0.5 alinha apenas os critérios de aceitação, não repete a Fase 1 de esclarecimento). Se não tiver certeza, liste as opções para o usuário.

Escolha do Núcleo de Renderização (quinta dimensão, anotada no DESIGN): Além dos quatro modos acima, defina também o backend de renderização (esta skill usa o núcleo Remotion por padrão; use o núcleo HyperFrames se anotado no DESIGN ou solicitado pelo usuário):

• Núcleo Remotion (padrão): efeitos complexos em React / cartões shotcraft / src/ com camadas + Sequence + useCurrentFrame. Use quando quiser a máxima liberdade de animação.
• Núcleo HyperFrames (HeyGen open source HTML→MP4, opcional): atributos de dados em index.html + timeline GSAP (npx hyperframes init/render, gratuito local) → mais próximo da sensação web, inclui npm run check (lint+contraste+movimento). Assets/BGM/legendas/validação todos reutilizados, apenas a escrita da renderização muda. Regras em references/hyperframes-guide.md.
• Decisão: cartões de câmera complexos (virada de carta/partículas/3D) ou projeto Remotion existente → Remotion; animações puramente HTML/GSAP, deseja sensação web, precisa de lint embutido → HyperFrames. Não misture os dois núcleos no mesmo projeto.

Passo 0.5 — Alinhamento de Requisitos + Critérios de Aceitação (grill-me, obrigatório, ≤10 rodadas)

Execute a skill grill-me para alinhar: requisito em uma frase, proporção/duração/plataforma, fonte das legendas (.srt/.vtt/script de locução/do zero), modo, direção de estilo. Deve produzir critérios de aceitação em quatro categorias:

• Estrutura: categoria/proporção/duração/fps
• Visual: fonte das legendas/cores/composição consistentes com DESIGN.md ou referência (modo livre "sem cheiro de IA")
• Conteúdo: todas as falas das legendas presentes, sem erros de digitação, timestamps cobrindo todo o vídeo, texto verídico
• Técnico: alinhamento de legendas aos quadros (quadro de início e fim de cada fala com legenda presente), extração de stills bem-sucedida, renderização MP4 bem-sucedida

Se não alinhar em 10 rodadas → registre pendências e prossiga para a construção mesmo assim.

Passo 1 — Processo Orientado por Legendas (Central)

Siga references/captions-guide.md:

1. Roteamento da Fonte: .srt/.vtt existente → use diretamente; script de locução.md existente → elabore um rascunho de .srt; do zero → primeiro faça um rascunho de script de locução e depois .srt.
2. parseSrt({input}) → Caption[], valide segmentos vazios, sobreposição de tempo, fora dos limites.
3. Alinhamento ao Quadro: startFrame = Math.round((startMs/1000)*fps), endFrame = Math.round((endMs/1000)*fps), cada fala <Sequence from={startFrame} durationInFrames={endFrame-startFrame}>.
4. Destaque por Palavra/Frase: createTikTokStyleCaptions → componente CaptionLayer; frase inteira em chinês como um único token → degrade para destaque por frase (decidido pelo highlightMode no DESIGN.md).
5. Ritmo visual vinculado ao início de cada fala startMs; duração total do vídeo durationInFrames = round(max(endMs)/1000*fps) + trailing.
6. Após alterar palavras, reescreva com serializeSrt.

Passo 1.5 — Reconstrução de SRT Orientada por Locução (suposição de temporização real, primeiro locução, depois extração de stills)

A locução é um processo obrigatório para vídeos com narração (não pergunte ao usuário): Geração TTS → medição com ffprobe → reconstrução do SRT definindo a linha do tempo, a temporização real do TTS é a referência (suposição de temporização real do DESIGN §4). Primeiro locução, depois extração de stills — evita que o alinhamento do SRT no Passo 1 seja invalidado pela reconstrução da locução, tornando os passos anteriores inúteis.

1. python scripts/media/tts_gen.py --provider edge-tts --lines lines.txt --save-dir public/audio/ --voice <voice> (padrão sem chave como fallback; quando MiniMax disponível, mude explicitamente para --provider minimax, TTS em nuvem doméstica consulte mmx-media-pipeline.md §2).
2. Meça a duração de cada fala com ffprobe (ffprobe -show_entries format=duration), respiro de 0.8s entre falas.
3. Reconstrua o SRT (rebuild_srt.py): início/fim de cada fala = acúmulo de durações medidas + respiro; escreva em public/captions.srt.
4. Atualize os intervalos de quadros do SHOTS raiz conforme o novo SRT (round(ms/1000*fps)), cada Sequence receba <Audio src={staticFile("audio/s{n}.mp3")}>.
5. BGM: se não precisar de música gerada por IA, obtenha da biblioteca de assets licenciados do projeto; se precisar de música gerada por prompt, use por padrão o ACE-Step para geração local, com backend de música em nuvem como alternativa opcional. Após obter, corte para a duração total (ffmpeg -t segundos do vídeo), volume baixo para não atrapalhar a locução (0,22-0,3).
6. Orçamento de quadros por cena + pré-verificação de temporização (evita "animação chave não aparece", já ocorreu 3 vezes): o to-from de cada fala na saída do rebuild_srt é o orçamento de quadros para aquela cena. Antes de escrever cartões/animações de dados, verifique: o último quadro-chave dentro do cartão ≤ orçamento da cena, caso contrário, comprima a temporização do cartão (não espere até a validação para descobrir) —
   • Frases curtas (2-3s≈60-90f): animações de fim do cartão (selo/varredura de círculo/acender cíclico) são as que mais facilmente excedem o orçamento (S2 selo vermelho original 70-88f excedeu 68f da fala → comprimido para 55-65f; S6 acender cíclico original 46-70 excedeu 70f → comprimido para 46-64; S9 varredura de 5 círculos original 136f excedeu 128f da fala → comprimido para 108f).
   • Regra: último quadro-chave do cartão = início + duração total em cascata + parada final, deve ser ≤ orçamento da fala; se exceder, comprima proporcionalmente o stagger/duração única, parada final ≥4f mantida.

Passo 2 — Encontrar Referência

A referência fornecida pelo usuário tem prioridade máxima → video-real-library.md → design livre. Se houver referência, use o "método de desmontagem de animação" (referência → combinação de componentes da biblioteca geral, consulte motion-patterns-video.md).

Passo 3 — Prompts Negativos (versão condensada para vídeo, única restrição rígida)

• Não use o mesmo ritmo de legendas o tempo todo (todas as falas com mesma duração, destaque por palavra piscando sem diferenciação)
• Não use a mesma composição central em todas as cenas, apenas fade o tempo todo ou apenas cortes secos
• Não corte a imagem uniformemente (corte a cada N segundos = sem sensação de respiração)
• Não use gradiente padrão roxo-índigo como fundo, não use fontes de IA genéricas
• Não use legendas de narração vagas ("Bem-vindo", "Vamos começar")
• Animações são obrigatórias: cada cena deve ter pelo menos animação de entrada + transição entre cenas
• É isso.

Passo 4 — Construção (Linha de Base Técnica)

Siga references/remotion-build-guide.md:

• Inicialização do projeto: copie o esqueleto de _dev/remotion-tutorial + npm i @remotion/captions@<versão alinhada> + mantenha o caminho do Chrome.
• Importe componentes da biblioteca geral de animações (workbench/video/_animation-library/) ou copie para src/components/.
• Cartões de câmera opcionais: se o DESIGN §8.2 selecionar cartões, siga remotion-shared/video-shots-spec.md «Passos de integração de cartões de câmera» (incluindo marcações de intenção [copy]/[borrow idea]); para vídeos em chinês, use borrow idea por padrão.
• Camadas em src/: Root.tsx / theme.ts / captions.ts / components/.
• Animações determinísticas (useCurrentFrame/interpolate/spring, proibido Math.random e timers do navegador).
• Se existir DESIGN.md, execute estritamente conforme os tokens.
• Assets conforme references/video-image-spec.md com roteamento entre harnesses (Codex image_gen / ida e volta de prompts GPT / imagens fornecidas pelo usuário).
• Revalidação do esboço após geração de assets (obrigatório): após gerar os assets, compare com o esboço do DESIGN §8 frase por frase — ① a imagem corresponde ao significado/layout daquela frase? (avaliação vision de aderência, <7 regere ou ajuste o prompt) ② as palavras-chave grandes são coordenadas com a imagem da cena, sem obstrução? ③ a ordem z das camadas está de acordo com o design do esboço? Se não → ajuste as palavras-chave ou regere o asset, não "use o que foi gerado"; para cada elemento visual, tenha múltiplos candidatos e escolha o melhor.

Passo 5 — Fechamento da Validação (tabela de nós grill-me)

Nó	Gatilho	Limite de Rodadas	Condição de Saída
Início	Passo 0.5	10 rodadas	Critérios de Aceitação finalizados
Modificação	Usuário solicita alteração	5 rodadas/vez	O que alterar está claro, a cada rodada compare com os critérios de aceitação
Final	Antes da entrega	4 rodadas	Verificar cada critério de aceitação um por um

Ações de Validação Obrigatórias (primeiro extraia stills, depois renderize, evite renderizações longas em vão): Quantificação em Camadas (4 camadas, verifique no DESIGN §8.2 os quadros-chave de prova = início/frase/0,82 estado final):

• Camada 1 Imagem de Fundo (a imagem da cena em si): python scripts/media/layout_calc.py <imagem da cena> — composição/espaço em branco/área de texto sugerida (encontre área vazia com base na estrutura de espaço em branco da imagem, não force topo limpo; se o topo estiver invadido → mova o texto para a área sugerida text_zone, ou regere uma imagem mais limpa);
• Camada 2 Imagem de Fundo + Texto (still com texto): ponto de queda do texto do layout_calc + frame_judge --subtitle-hex para WCAG real (texto grande ≥3,0/ texto corpo ≥4,5);
• Camada 3 + Animação (quadros contínuos): diferença de quadros/quadros contínuos vision para julgar se a animação realmente ocorreu + animação não sobrepõe a cena (se o cartão for uma imagem completa, não trate como sobreposição de imagem de cena, modos visuais veja §8.2);
• Camada 4 Geral (vídeo finalizado): frame_judge no vídeo inteiro + audio_sync_check.py para sincronia áudio-visual + verificação de oclusão + pontuação das quatro skills + prova de ação.

1. npx remotion compositions confirme o id real;
2. Extraia 3-5 stills (início da fala/fim da fala/quadro de transição) — extraia "quadros de estado final" não durante a animação (lição aprendida em 2026-08-17): selecione para extração quadros após a conclusão da ação (0,82 estado final / após parada final), não extraia quadros durante a animação — quadros intermediários podem fazer a vision/olho humano julgar erroneamente "ausente/estático/quadro preto" (S2 virada de carta sem selo vermelho no meio, S6 hodômetro rolando sem ponto cíclico no meio, S7 linha do tempo no meio sem cartão de retrato são todos erros de momento de extração; extraia quadros de estado final). Legendas presentes e alinhadas, composição intacta;
3. Validação de alinhamento de legendas: no quadro de início da fala a legenda já apareceu, no quadro de fim da fala a legenda não desapareceu antes;
4. Indicadores rígidos automatizados: após extrair stills, execute python scripts/media/frame_judge.py preview/*.png --subtitle-hex <cor da legenda do DESIGN, ex. E8833A> --subtitle-threshold 3.0 --text-bg-hex <cor de fundo do balão de texto, ex. F2F0EB> (--text-region se o texto estiver no canto, passe a posição real tl/tr/bl/br/center, evite falso positivo no fundo; --text-bg-hex se o fundo do balão for conhecido, calcule diretamente o contraste legenda vs fundo real, pulando a moda — a moda pega a cor da cena, imprecisa quando o texto está sobre a cena; limite para cenas de texto grande 3,0 / texto corpo 4,5; qualquer FALHA aciona revisão); opcional pip install iqa-pytorch depois adicione pontuação estética NIMA (>6,5 registra como referência); limites dos indicadores veja references/video-quality-metrics.md; falha de brilho em design escuro não bloqueia (veja explicação de design escuro nas métricas, prevalece o contraste);
5. Cada still verificado contra checklist (itens fracos <3 acionam revisão):
   • Composição: ≥2 elementos visuais, nem toda cena centralizada, ordem z das camadas correta (bg/mid/fg)
   • Legendas: presentes e alinhadas, legíveis (contraste ≥3:1), sem caracteres quebrados
   • Transição: entre falas há transição/animação de entrada, não corte puro ou estático
   • Assets: sem caracteres de IA corrompidos, camadas conforme §8.1, sobreposições transparentes limpas
   • Animação: pelo menos 2 tipos de animação na cena (entrada/saída de assets + fonte + fundo, escolha dois de três), fundo com animação
   • Sem cheiro de IA: verifique contra prompts negativos de video-anti-slop.md
6. Verificação de oclusão + conferência de modo visual (inspirado em paper-collage-video spatial-contract, expandido em 2026-08-16): verifique still por still — ① balão de texto grande na área reservada (espaço branco no topo) ② sujeito principal não pressiona área de texto/legenda ③ primeiro plano não obstrui sujeito do plano médio/fundo ④ animação do cartão não sobrepõe a imagem da cena: cartões de imagem completa (hodômetro/mostrador/coluna de partículas/campo escuro de luz) nunca tratados como sobreposição de imagem de cena (modo visual escolha um de três, veja DESIGN §8.2) ⑤ significado da animação ecoa o sentido da fala (vision julga se coluna de partículas/varredura de luz/rolagem de números expressa algo naquela cena, se é consistente com o significado da locução; significado pouco claro aciona revisão). Oclusão/significado pouco claro → mude o modo visual ou remova cartão desnecessário.
7. Portal rígido de revisão das quatro skills (qualquer portal não aprovado → revisão, não é referência): execute com subagentes independentes (hallmark/taste executados por agente independente, não auto-revisão do modelo principal):
   • taste-skill Pre-Flight (40+ itens de verificação de bom gosto)
   • hallmark audit (57 portais anti-AI slop)
   • ui-ux-pro-max (diretrizes UX: legibilidade/hierarquia/consistência)
   • open-design/anti-ai-slop ("sete pecados" anti-template) Verifique stills/vídeo finalizado, pontue por número de itens aprovados para liberar (revisão complementar, evita auto-liberação): hallmark 57 portais aprovados ≥90% (≥51 itens) para liberar, taste 40+ itens aprovados ≥85% para liberar, ui-ux-pro-max / open-design todos os itens críticos aprovados; liste itens não aprovados acionando revisão, só renderize e entregue após todos os portais aprovados.
8. npx remotion render <id> out/final.mp4;
9. Momento de prova de ação (inspirado em paper-collage-video proof moments): conforme DESIGN §8.2, para cada fala, extraia stills nos momentos de prova (início da fala/meio/0,82 estado final) + verifique se o tipo de ação realmente ocorreu (entrada ocorreu/continua em movimento/parada final); ffmpeg -vf "fps=4" extraia quadros contínuos → vision julgue se a ação ocorreu conforme DESIGN — um quadro estático de translação ≠ prova de ação (partículas/luz/números precisam de quadros contínuos para confirmar); transição suave/entrada e saída sem saltos (video-quality-metrics §4.6);
10. Conferência de sincronia áudio-visual (eixo principal de vídeos com locução, revisão complementar): execute no vídeo finalizado python scripts/media/audio_sync_check.py out/final.mp4 public/captions.srt — para cada fala, ±0,15s do início do SRT deve haver som de locução (RMS≥0,01); início em silêncio = locução desalinhada/ausente/corte no final da fala → revisão;
11. Verifique cada critério de aceitação um por um → STATUS PASS/FAIL/BLOCKED, NEXT_OWNER.

Linhas Vermelhas

• Legendas como eixo é restrição rígida: captions.srt existente é a única fonte da linha do tempo, a duração é derivada dele.
• Primeiro extraia stills, depois renderize: stills não aprovados, não renderize o vídeo completo.
• Inspiração de cartões de câmera não é obrigatória: se DESIGN §8 selecionar cartões, integre (copie shotcraft/demos/{categoria}/{cartão} e adapte); se não selecionou cartões ou para vídeos em chinês usar borrow idea não conta como omissão; cartão não integrado não é BLOCKED.
• Assets usam geração de imagem real, não gere SVG: assets principais priorizam Codex ou backend de imagem já configurado; transparência use --transparent/remove_white_bg.py.
• Cartões de dados programáticos priorizam cópia real da versão completa do shotcraft, não escreva SVG simplificado manualmente (lição aprendida em 2026-08-17): cartões de dados auto-construídos (mostrador/anel/hodômetro/gráfico) se escritos como SVG simplificado manual (círculo/linha/path nus, sem escala/zona vermelha/cubo/brilho/detalhes) ficarão grosseiros (S9 ring versão manual mmx vision 3,5/10, após cópia real do shotcraft NeedleSweepSelftest com detalhes completos 8,5/10). Cartões de dados sempre copiem a versão completa de shotcraft demos/data, typography (escala/principal-secundário/brilho/cubo do mostrador/ponta do ponteiro etc. todos os detalhes presentes), depois remodele as cores; apenas decorações simples (manchas de luz de fundo/trilho base) podem ser desenhadas programaticamente.
• Reconstrução de SRT orientada por locução é obrigatória (Passo 1.5, primeiro locução, depois extração de stills): para vídeos com locução, o Passo 1.5 deve obrigatoriamente fazer TTS→ffprobe→reconstruir SRT definindo a linha do tempo (a temporização real do TTS é a referência, DESIGN §4), a extração de stills e validação ocorrem após a reconstrução do SRT pela locução, não pergunte ao usuário.
• Não mude a direção do design: DESIGN.md está definido, siga-o; se precisar mudar de direção, volte para remotion-consult.
• Proibido inventar: não fabrique legendas/dados.

Arquivos de Referência

Arquivo	Quando Ler
references/captions-guide.md	Passo 1 Alinhamento de timestamps de legendas (central)
references/remotion-build-guide.md	Passo 4 Normas de engenharia
references/motion-patterns-video.md	Passo 2/5 Implementação de animações
references/video-image-spec.md	Passo 4 Roteamento de assets
references/codex-imagegen.md	Passo 4 Quando usar Codex para assets
references/mmx-media-pipeline.md	Passo 4 Backend de mídia (MiniMax opcional + cadeia de degradação TTS/BGM + armadilhas conhecidas)
references/video-quality-metrics.md	Passo 5 Indicadores de discriminação automatizada (frame_judge.py + limites VMAF/NIMA/ASL)
references/hyperframes-guide.md	Passo 0 Quando núcleo de renderização = HyperFrames: atributos de dados HTML/GSAP/regras check + CLI
references/hyperframes-blocks.md	Quando núcleo de renderização = HyperFrames selecione blocos de animação: registry blocks 154 itens consulta rápida por categoria (equivalente a shotcraft)
.claude/skills/remotion-shared/video-anti-slop.md	Passo 3 Linha de base de prompts negativos
.claude/skills/remotion-shared/video-tokens-spec.md	Ao escrever theme.ts
.claude/skills/remotion-shared/categories/{categoria}/motion-list.md	Selecionar combinações de animação
.claude/skills/remotion-shared/video-shots-spec.md	Sistema de receitas de cartões de câmera + técnicas autoritativas (construção selecione cartões de câmera: demos/{categoria}/{cartão} copie para o projeto)
.claude/skills/remotion-shared/aesthetic-judgment/	Passo 5 Validação: discriminação de seis eixos de fotografia/edição/layout front-end (<3 aciona revisão)
.claude/skills/ui-ux-pro-max/SKILL.md	Motor de regras de design: Passo 4 durante a construção consulte diretrizes UX + prioridades
.claude/skills/taste-skill/SKILL.md	Passo 5 Verificação final: Pre-Flight 40+ itens (auto-inspeção antes da entrega)
.claude/skills/hallmark/SKILL.md	Passo 5 Revisão de design: 57 portais / hallmark audit (antes da validação)
database/AI tools/design-skills/open-design/craft/anti-ai-slop.md	Passo 3 Regras anti-template ("sete pecados") + 151 alternativas de sistema de design
.claude/skills/design-shared/review-panel.md	Painel de revisão: perspectiva agency-agents + sistema de design/biblioteca de referência estética como critério de julgamento (Passo 5 pontuação da validação)

Saída e Encerramento

STATUS: PASS | FAIL | BLOCKED
Produtos: caminho out/final.mp4 + caminho dos stills preview/
Critérios de Aceitação: item por item Atingido / Não Atingido / Pendente
NEXT_OWNER: user (ver resultado) | remotion-consult (mudar direção)
Pendente: itens não resolvidos