remotion-broll

Engenharia de Materiais (Pipeline Executável)

Posicionamento: Este é um skill prático, não um documento de regras — execução, comandos, verificação e entrega integrados. A fonte completa das regras está em remotion-assembly/references/broll.md (detalhamento de prioridades de quatro níveis/obrigação de lista de materiais por caso/especificações de citação). Em caso de conflito, prevalece o documento de referência.

Quando Chamar

• Quando a Etapa 2 da Oficina de Segmentação identificar um segmento de material real (cenas de experiência de produto: digitação/geração/interface/demonstração/operação)
• Coleta de lista de materiais antes da finalização da tabela de plano de montagem (1 captura de tela do produto ou 5s de gravação de tela por caso, coleta automática pela IA, sem esperar por fornecimento)
• Quando o usuário fornece gravações de tela/materiais reais para incorporar no vídeo principal

Pipeline de Execução (Cada Etapa com Verificação, Passo a Passo)

① Classificação: Selecionar rota por prioridade de quatro níveis — gravação do usuário > vídeo oficial > captura de tela > cartão simulado de UI. Para casos com site oficial/canal oficial público, é proibido cair diretamente no Nível 4.

② Coleta

• Vídeo oficial: yt-dlp --print "%(channel)s | %(title)s | %(duration)ss | %(id)s" "ytsearch8:<nome do produto> official" identificar canal oficial → yt-dlp -f "bv*[height<=1080][vcodec^=avc1]+ba[ext=m4a]/b[vcodec^=avc1]/b" -o "public/broll/<nome>.mp4" <url> ([vcodec^=avc1] filtra o AV1 padrão, que junto com HEVC não é armazenado, veja broll.md 2c); em caso de 403, tentar UA / --cookies-from-browser / proxy.
• Captura de tela: node_modules/.remotion/chrome-headless-shell/*/chrome-headless-shell*/chrome-headless-shell --headless --screenshot=<out.png> --window-size=1920,1080 --virtual-time-budget=10000 <url>.

③ Verificação (Obrigatória): file <arquivo> para evitar "PNG ser na verdade HTML"; vídeo usar ffprobe para verificar codec, HEVC converter primeiro para H.264 (evitar tela preta); captura de tela inspecionar visualmente para confirmar que não é tela de login/pop-up de cookie.

④ Seleção de Trecho: ffmpeg -vf fps=0.5 extrair frames para montar contact sheet, Ler frame a frame, selecionar trecho de 3-8s sincronizado com o discurso (entrada → ação → espera → resultado), registrar segundos de início e fim.

⑤ Incorporação: Dentro de Takeover usar <Sequence from={beat(x)}> + <OffthreadVideo muted src={staticFile('broll/….mp4')} startFrom={F(segundo_início)}> (muted obrigatório); takeover sem PiP (decisão do usuário); capturas de tela usar ShotCard/WindowCard. Sequências com mídia adicionar premountFor≈fps para evitar quadro preto no primeiro frame, mas essa sequência não pode ter layout="none" (remoção do wrapper faz premount falhar); se o wrapper externo usar return null para controlar visibilidade, o null deve abrir cedo com ≥premountFor frames (testado em seg06: container frame<enterAt-30 return null com interno premountFor={30}), senão o pai null corta a janela de pré-carregamento e premount é inútil.

⑥ Uniformização de Cor: Camada de material adicionar filter: brightness(0.9-0.92) saturate(0.95) (ajustar sutilmente conforme luminosidade do vídeo principal); cor original direta = sensação de adesivo (erro #18); Segmentos de takeover usar configuração única brightness(.92) saturate(.95) (testado em seg06, não ajustar visualmente por segmento).

⑦ Edição: Ênfase com punch-in (crop+scale para área chave, altura da fonte da frase chave ≥40px), seleção de frames, mudança de velocidade; citações usar formato de dois estágios "cartão inteiro 2-3s → punch-in na frase chave". Janela de takeover deve se ajustar à duração natural do material, priorizar velocidade natural — material mais curto que a janela: reduzir janela + sobreposição antecipada, não desacelerar para preencher; playbackRate<1 apenas para cenas de rolagem de interface quando a janela não pode ser reduzida (≥0.7). Se o material tiver destaque queimado/legendas traduzidas e não houver frame limpo → método de revelação por máscara (máscara branca scaleX 1→0 revelando, e deve ser registrado em SOURCES.md como "com método de revelação por máscara", veja broll.md 8.5).

⑧ Verificação de Renderização de Segmento: Renderizar apenas o segmento com --frames=a-b, extrair frames e verificar: sensação de adesivo (ajuste de cor), legibilidade (≥16px), ultrapassagem de borda (caixa de segurança branca), sincronia com discurso.

Convenções de Armazenamento

Vídeos em public/broll/; capturas de tela em public/assets/; lacunas escrever na tabela de plano de montagem e solicitar fornecimento ao usuário. Diretriz de direitos autorais: materiais promocionais oficiais usados em vídeos de comentário.

Nomes de Pessoas Obrigatoriamente com Retrato (Decisão do Usuário em 2026-07-22, Regra de Ferro)

Quando o discurso menciona um nome específico de pessoa, o círculo do avatar da ficha da pessoa deve conter, sempre que possível, uma foto real dessa pessoa, sem usar monograma com a letra inicial como substituto (palavras do usuário: "Quando menciona nome de pessoa, sempre que possível coloque uma imagem, você pode pesquisar na internet a imagem mais representativa dessa pessoa e colocar no círculo do avatar"). Monograma/ícone só como último recurso quando não for possível obter a imagem.

Diretriz de obtenção de imagens (duas categorias, não misturar):

• Figura pública (Jobs, Musk etc.): IA pode obter a imagem, mas apenas de fontes explicitamente licenciadas para uso comercial — preferência por entradas do Wikimedia Commons com CC BY / CC BY-SA / Public Domain, em segundo lugar materiais de comunicados oficiais. Proibido pegar imagens aleatórias de buscadores (geralmente são fotografias comerciais com direitos incertos, o vídeo do usuário será publicado). Após obter, registrar obrigatoriamente em public/broll/<nome_do_vídeo>/SOURCES.md: nome do arquivo / URL de origem / tipo de licença / crédito do fotógrafo. Licenças CC BY-SA que exigem atribuição nos créditos finais ou na descrição, informar o usuário na entrega.
• Pessoa não pública (como professor, amigo, colega mencionado no discurso): IA não pode pesquisar imagens online — não é possível confirmar se é a pessoa nem a licença. Seguir o fluxo "mencionar necessidade de material" e solicitar ao usuário; se o usuário não fornecer, manter cartão de nome/monograma desenhado e explicar o motivo na entrega.

Esta regra substitui a versão anterior: A abordagem anterior de "proibir retrato de Jobs, usar apenas texto/icon chip" era uma medida conservadora por preocupação com direitos autorais. Agora, conforme decisão do usuário, mudou para "usar fotos reais com licença clara", resolvendo o problema de direitos autorais escolhendo fontes licenciadas em vez de não colocar foto.

B-roll Colado Gerado por IA (Cenas Emocionais/Metafóricas sem Material Real, Definido em 0722-01)

Quando não há material real nos quatro níveis, mas são necessárias cenas emocionais ou abstratas (repetição, cirurgia, uso de celular, fragmentação de atenção — situações impossíveis de gravar tela ou sem vídeo oficial), seguir este fluxo: Codex image_gen gera frame estático → Grok image_to_video anima → incorporar no vídeo principal. A execução segue o skill gbro-collage-broll com três Gates (Gate1 metáfora / Gate2 frame estático / Gate3 vídeo), mas o ritmo, suporte e composição seguem esta seção (substitui os defaults do gbro).

① Suporte: Padrão é cartão direito, não tela cheia. Colocar B-roll no cartão de evidência da área direita do layout de três colunas (16:9 proporcional objectFit:contain exibindo completo, sem cortar — decisão do usuário "reduzir proporcionalmente"), a pessoa permanece em cena, a área esquerda mantém sidebar + HUD de linha do tempo. Takeover de tela cheia apenas quando não há nenhuma informação que precise ser justaposta com o material (regra de A-roll: tela cheia é o único momento em que a pessoa pode ser cortada, veja layout §2). Componente de suporte consultar src/koubo/scenes-0722-01/CollageBroll.tsx (card + OffthreadVideo, borda segue a cor do capítulo). Não fazer tela cheia por padrão — em 0722-01, fazer tela cheia foi rejeitado pelo usuário e teve que ser refeito.

② Ritmo: Um frame por frase, corte no ritmo, sem depender de revelação interna do plano. Em discurso denso, cada frame dura apenas 1-3s, proibido animações de montagem assemble-from-empty (começar do vazio e só no último frame estar completo = informação sempre atrasada, conflitando com a curva de velocidade da fala, resultou em 8 vídeos descartados). Buscar "animação" — o frame estático já está completo no frame 0, Grok apenas adiciona movimento sutil contínuo (papel voando/engrenagem girando/faixa de luz deslizando/nevoeiro fluindo), a composição do frame não pode mudar.

③ Regras de Composição de Frame Estático (Codex image_gen):

• Proporção por tipo (generalização causa erro): Metáfora orientada por objeto (cama de hospital/comprimido/calendário/fragmentos/pilha de livros — pessoa é apenas elemento) pessoa ocupa 45-60% da altura; Metáfora orientada por pessoa (trabalhando/sentado/apertando botão/olhando para o vazio — pessoa é o sujeito principal) deve ser close-up 65-80%, plano geral falha diretamente.
• Linhas vermelhas rígidas: Sem texto falso/letras/números legíveis/logo/marca d'água/UI; verificar também as quatro bordas (Codex pode perder texto falso nas bordas, a sessão principal deve usar ffmpeg para cortar as quatro bordas, ampliar e verificar independentemente).
• Imagem de referência de identidade especificada pelo usuário (0722-01 usou my-face-studio-default.JPG); expressão facial conforme narrativa, em momentos baixos usar mais perfil/cabeça baixa/deitado para evitar estranheza, sem sorrir nem sofrer.
• Após cada lote, usar md5 para deduplicar, evitar arquivos duplicados.

④ Três Armadilhas da Animação com Grok (Erro #39 em Detalhes):

• Resolução: O parâmetro resolution_name do grok CLI image_to_video só tem duas opções: 480p/720p, sem 1080p (confirmado em teste em 2026-07-24, solicitar 1080p retrocede para 720p); a API xAI grok-imagine-video-1.5 suporta 1080p i2v (documentação oficial). Tela cheia precisa de 1080p = CLI não consegue: usar API xAI 1.5, trocar para material real ou outro gerador (Sora 2 / Veo / Kling / Seedance; ChatCut MCP já integra Seedance/Kling). O comando deve explicitamente fixar a resolução para obter a qualidade máxima — senão, o padrão é 736×400 (mais embaçado). 720p é suficiente dependendo do modo de suporte: cartão/PiP (área de exibição geralmente <720px) 720p é suficiente e nítido; tela cheia preenchendo 1920×1080 com 720p ampliado 1,5× fica suave. O vídeo final é 1080p, B-roll não precisa de 4K (não aparece, a menos que com zoom significativo).
• Crescimento morph: Elementos propensos a colapso (engrenagens/círculos/calendários) adicionar restrições de fixação no final do prompt (manter tamanho único original/número de células e cores inalteradas/círculo contínuo sem quebra).
• Preenchimento forçado: "Elementos esparsos + grande fundo vazio + figuras humanas ocas + fragmentos de rosto" ativam o modelo para preencher áreas vazias/preencher buracos/gerar rostos, alterando a composição em vez de adicionar proibições.
• Invocação: Headless precisa de --always-approve --permission-mode bypassPermissions --max-turns 10; múltiplos agentes compartilhando cwd desabilitar grok --continue (pode cruzar sessões e escrever o vídeo da sessão A no caminho da sessão B); antes da entrega, deduplicar todos os lotes com md5.

⑤ Pré-requisitos de Ambiente: O projeto Codex deve ser criado dentro de seu diretório de trabalho gravável (local = ~/Documents/remotion剪辑/); criar em ~/hyperframes-projects/ pode fazer o image_gen funcionar mas a gravação ser negada; tarefas com múltiplos itens: enviar um agente por item em paralelo, não deixar um agente fazer tudo em série (pode julgar concluído no meio do caminho e encerrar).