wbr664393425-lgtm/rui-ui-promo-video

Fluxo de Trabalho para Vídeo Promocional com Componentes Reais

Estilo padrão = "Uma Linha": Um tema visual do produto (a "linha") percorre todo o vídeo, com pausas e três clímax acionados por interações reais. Para referência, veja o manual criativo com exemplos de tomadas estilo manual de instruções versus tomadas com efeitos empilhados estilo apresentação.

templates/ = Estrutura de captura (genérica, com correções de bugs) + scripts de composição, estilo, trilha sonora e exportação da versão final v3. Copie para videos/<nome>/ e altere apenas nos trechos marcados como 【OBRIGATÓRIO ALTERAR】.

Leia conforme necessário:

• references/creative-playbook.md: Tema visual, três clímax, regras de pausa, texto, tabela de ritmo. Leia antes de definir os storyboards.
• references/compose-recipes.md: Medição de coordenadas, mapeamento de tempo, contêineres de cena, painéis de luz, linhas de contorno, holofotes, inversão de mundo, montagem de logotipo, transições, escrita de linha do tempo. Leia antes de compor.
• references/pitfalls.md: Tabela de sintomas → causa raiz → solução e comandos de verificação para captura, renderização, áudio e entrega. Consulte primeiro ao encontrar anomalias.

Stack Tecnológica

Etapa	Tecnologia	Pontos-chave
Composição/Renderização	HyperFrames (fixo [email protected], npx --yes, não instalar como dependência do projeto)	check para validação, snapshot para extrair frames, render para gerar vídeo
Animação	GSAP (copiar versão já instalada no projeto para assets/vendor/gsap.min.js)	Registrar timeline única paused em window.__timelines[id]
Build de Captura	Vite + @vitejs/plugin-vue (usar createRequire para resolver dependências do frontend)	Root independente; envDir/publicDir apontar para o projeto frontend; vendor em bloco separado
Clock Determinístico	Plugin transform do Vite	Converter chamadas setTimeout/rAF/Date.now/performance.now (nuas ou com prefixo window.) para window.__shoot
Isolamento de Dados	fixtureFetch em memória (incluindo simulação de operações de escrita) + lista branca de rede + seed fixa + epoch fixo + localização fixa	Dados fictícios, requisições de negócio redirecionadas para fixtures, clock fixo de captura
Script de Interação	performActions(t) + once/byText/rowButton/typeInto	Conduzir cliques, entradas de texto e arrastos reais em segundos específicos
Material	Landscape PROMO_RESOLUTION=4k com 2x pixels; celular 430×932 viewport separado	Composição pode aproximar bastante mantendo nitidez
Trilha Sonora	Python3 + NumPy (96 BPM, reverb FFT, seed fixa)	Silêncios nas pausas, acentos nos clímax, sinos nos pontos de destaque
Loudness/Exportação	FFmpeg loudnorm dupla passagem (−14 LUFS / TP −3), empacotamento da trilha original normalizada, versão comprimida e capa	Vídeo principal + -share.mp4 (~11 MB) + PNG de capa

Estrutura de Diretórios

videos/<nomedoprojeto>/
  promo.config.mjs   appDir/srcDir/entry/motionFile/id/duration/coverAt/hyperframes — única configuração específica do projeto
  capture/           index.html (estrutura de captura) bootstrap.ts (clock/isolamento/interações) fixtures.ts (dados fictícios, precisam ser escritos) vite.config.mjs
  scripts/           render-footage.mjs compose-film.mjs compose-audio.py normalize-audio.mjs render-film.mjs remux.mjs
  assets/            footage/ footage-4k/ audio/score-final.wav vendor/gsap.min.js
  index.html (gerado pela composição) film.css package.json README.md

npm scripts: capture / compose / audio / check / snap -- <segundo,segundo> / render / remux / dev.

Fluxo

1. Definir Direção: Leia PRODUCT.md/DESIGN.md/identidade da marca. Com base no creative-playbook, encontre o tema visual e desenhe os três clímax. Confirme apenas duas coisas com o usuário: linha criativa principal (dê 2–3 direções, recomende "um tema") e tom do texto (manter ou renovar).
2. Storyboard: Cada cena = página real + título em Songti + segundos-chave da interação + forma do tema visual nesta cena; ritmo de referência de 45 segundos no playbook. Escreva na tabela de storyboard do README.
3. Estrutura de Captura: bootstrap.ts instala window.__shoot, lista branca de rede, localização fixa, limpa storage (incluindo rascunhos do IndexedDB), pré-configura tema/visual/token offline, faz replaceState para a rota e depois import da entrada do produto; páginas lentas usam waitFor/settle para drenar rAF; injeta estilos para cursor oculto, scrollbar e caret. fixtures.ts mantém campos das APIs reais; operações de escrita só alteram memória. Primeiro, faça pré-visualização no navegador com ?shot=<cena>&live.
4. Captura: Execute npm run capture (worker único). Para cenas landscape com grande aproximação, execute também PROMO_RESOLUTION=4k npm run capture.
5. Medir Coordenadas: Extraia frames do material (coordenadas 1920; para 4K, recorte local para valores precisos) e meça posições de trajetórias, botões, modais, nós de passo.
6. Composição: Edite compose-film.mjs com a tabela de cenas, coordenadas, texto e pontos de tempo; reutilize funções utilitárias. Regras no compose-recipes. A cada rodada, execute npm run compose && npm run check, depois npm run snap -- <segundos-chave> para verificar contact sheet (entrada/saída de clímax, transições, alinhamento de anotações).
7. Trilha Sonora: Edite compose-audio.py com os pontos de tempo (acentos nos clímax, silêncios, cliques, sinos nos nós), execute npm run audio.
8. Renderização e Verificação: Execute npm run render em segundo plano. Após a conclusão, use ffprobe para verificar duração/quadros/resolução/framerate, ebur128 para verificar loudness e pico verdadeiro, blackdetect (explique pausas intencionais), e extraia cerca de 18 frames para inspeção visual. Para alterar apenas a capa, execute npm run remux.

Restrições

• O código-fonte e dependências do produto não devem ser alterados; a modificação do clock ocorre apenas no build de captura.
• Use apenas dados fictícios; não conecte ao backend de negócio/banco de dados; não leia credenciais reais; recursos online de terceiros (como mapas) devem estar na lista branca; chaves de API só em diretórios ignorados pelo git. O README deve descrever explicitamente o isolamento, seed e data fixa.
• Anotações devem usar apenas números que realmente aparecem na interface; o texto e as imagens não devem conter "demonstração/amostra/simulação".
• O visual deve seguir o DESIGN.md do projeto e as cores da marca; fontes declaradas localmente (Songti SC / PingFang SC / Georgia).
• Artefatos intermediários (.capture-build/ .shots/ .quality/ renders/ logs) vão para .gitignore; versões antigas do projeto são mantidas intactas; versões novas criam novo diretório.
• Não commitar, nem publicar em plataformas externas, a menos que o usuário solicite explicitamente.
• Antes de escrever ou modificar a composição, consulte hyperframes-core, hyperframes-animation, hyperframes-cli conforme necessário para verificar a API atual.

Lista de Entrega

• Vídeo principal MP4 (45.000 s / 2700 frames / 1920×1080 / 60 fps / H.264 yuv420p / AAC 320k 48 kHz / −14 LUFS / pico verdadeiro ≤ −1 dBTP).
• Versão comprimida -share.mp4 e capa PNG, entregues por meio compatível com a plataforma atual.
• index.html + film.css editáveis, além dos materiais e scripts.
• README: descrição visual, tabela de storyboard, descrição da trilha sonora, comandos de reprodução, isolamento de captura, verificação de entrega.