pr-explainer-film
Um filme silencioso por padrão, de ~30s em cinco movimentos. A forma é o ponto: o espectador sente que o diff é ilegível, depois obtém a resposta em palavras simples, então vê a prova e, por fim, sabe o que digitar.
| Tempo | Movimento | Propósito |
|---|---|---|
| 0-2s | Gancho | Nomear o tamanho da mudança ("15 arquivos alterados.") |
| 2-8s | Borrão do diff | Pedaços reais passam rapidamente; contadores sobem |
| 8-13s | Palavras simples | Manchete de uma frase mais três pontos curtos |
| 13-23s | Quatro batidas | Uma capacidade cada, mostrada ao lado das linhas reais por trás |
| 23-30s | Fechamento | Comando de instalação digitado, depois a URL |
Entradas
Colete estas antes de construir. Pergunte apenas pelo que estiver faltando.
- Fonte da mudança: um PR ou release do GitHub (
gh pr diff,gh pr view --json title,body,files), ou uma árvore de trabalho local (git diffmais arquivos não rastreados). Somente leitura; nunca modifique o repositório. - Público-alvo: quem não lerá o diff (clientes, colegas de equipe, seguidores). Isso decide o vocabulário no resumo e nas batidas.
- CTA: o comando de instalação e/ou URL exatos. Use-o textualmente. Se o produto tiver um comando canônico, mostre apenas esse comando e nenhum nome de outra ferramenta.
- Marca: paleta, logotipo (seu próprio arquivo), fonte. Os padrões no template são neutros e escuros.
Fluxo de trabalho
- Leia a mudança. Obtenha a lista de arquivos com contagens de adições/remoções e os pedaços reais. Escreva a mudança em uma frase que um não engenheiro entenderia; se não conseguir, você ainda não entendeu a mudança.
- Escolha o conteúdo (veja
references/content-rules.md): número do gancho, 5-8 pedaços de diff para o borrão, 3 pontos de resumo, exatamente 4 batidas de capacidade, CTA. - Estrutura inicial.
npx --yes hyperframes init <dir> --non-interactive --example=blank, depois copietemplate/index.htmletemplate/film.config.jssobre os arquivos gerados. Coloque seu logotipo emassets/logo.pngse tiver um. - Preencha
film.config.js. Todas as palavras, trechos e números ficam lá. Editeindex.htmlapenas para alterar variáveis de marca em:root, tempos ou layout. - Valide:
npx --yes hyperframes lintdepoisnpx --yes hyperframes check. Corrija todos os erros. Avisos aceitáveis conhecidos:nested_structure_needs_subcomposition(o filme é intencionalmente um arquivo para facilitar a re-marca). - Veja-o.
npx --yes hyperframes snapshot --at 1,4,6,8.3,11,14,17,19.5,22,26,29e abrasnapshots/contact-sheet-*.jpg. Verifique a lista abaixo; corrija e faça novos snapshots até estar limpo. - Renderize.
npx --yes hyperframes render --quality high --workers 2 --output final.mp4. Confirme comffprobeque é 1920x1080, H.264 e 28-34s. - Revise 4-6 quadros extraídos do MP4 (
ffmpeg -ss T -i final.mp4 -frames:v 1 f.png), não apenas os snapshots.
Regras que fazem o formato funcionar
- O diff deve ser real. Copie linhas reais do diff real. Nunca invente código ou contagens. Calcule contagens a partir de
git diff --shortstatmaiswc -lde novos arquivos. - Ilegível de propósito. A rolagem acelera (
power2.in) e borra. Não a desacelere para que as pessoas possam ler; o cartão "muita coisa para ler" compensa isso. - Palavras antes da prova. O resumo vem antes de qualquer batida de capacidade. Cada título de batida é um benefício em 2-4 palavras; a descrição é uma frase sem jargão; o trecho tem 1-5 linhas reais com a linha-chave destacada.
- Exatamente quatro batidas, uma ideia cada, cerca de 2,6s cada. Corte as mais fracas em vez de encolher o texto.
- Superfícies alternadas. Escuro para o diff e batidas, uma cena clara para o resumo. A mudança de fundo sinaliza "agora é simples".
- Feche com o comando. Digite o comando real caractere por caractere, depois mostre a URL. Sem segundo CTA.
- Higiene de cópia. Remova comentários de código que mencionem concorrentes ou ferramentas não relacionadas antes de chegarem a um trecho. Nunca mostre uma CLI diferente daquela no CTA.
- Possua seus ativos. Use seu próprio logotipo, fontes que a máquina já possui e nenhuma mídia de terceiros ou estoque. Música é opcional; se usada, apenas faixas licenciadas para uso comercial (resolva via
media-use) e mantenha o filme totalmente legível sem som. - Determinismo. Sem
Math.random,Date.nowou chamadas de rede na composição; anime texto digitado e contadores a partir de um valor de progresso de interpolação para que a busca seja exata.
Lista de verificação de quadros (etapas 6 e 8)
- Número e texto do gancho correspondem à mudança real.
- Janela do diff recorta dentro de seu quadro; cabeçalhos de arquivo e linhas verdes/vermelhas são legíveis em repouso, borradas quando em movimento.
- Contadores terminam nos números verdadeiros.
- Slide de resumo mostra todos os três pontos antes de desaparecer.
- Cada batida tem título, frase e trecho visíveis juntos, nada cortado.
- Quadro final mostra o comando completo e a URL, escritos exatamente.
Entrega
Entregue final.mp4 e a pasta do projeto (index.html, film.config.js, assets/, meta.json). Informe o caminho, a duração e quaisquer avisos de validação que foram aceitos. A pasta re-renderiza com o mesmo comando; para re-marcar ou reutilizar para o próximo lançamento, edite apenas film.config.js.
Veja references/content-rules.md para limites de tamanho e redação.