demo-video
Você precisa de um vídeo finalizado e projetado de um aplicativo. Esta skill é o pipeline testado e completo. Ela se baseia no HyperFrames (HTML→vídeo), mas adiciona as partes que são dolorosas de redescobrir: como gravar o próprio aplicativo, as soluções para o ffmpeg desta máquina, as receitas exatas de edição, o sistema de design com marca e as armadilhas que desperdiçam horas.
Nada aqui é marcado. A aparência é um design com tokens substituíveis; a marca de um vídeo é uma etapa, não uma suposição — veja a Fase 0B.
🚦 As fases são agrupadas por tópico, não por ordem de trabalho
Leia isto antes de seguir qualquer coisa abaixo em sequência. Os mecanismos de captura estão documentados primeiro porque pertencem ao mesmo grupo, mas a captura não é a primeira coisa a fazer:
O conceito vem primeiro: para que ISSO SERVE? → o arco → PLAN.md (+ SCRIPT.md) → APROVADO
(essa é a skill `video-plan`, não esta) │
│
↓ só agora existe filmagem ──────────────────────────────────────────────────────────┘
Fase 0 ambiente → 0B marca → 1A captura / 1B ingestão → 3 preparação → 4 composição
→ 5 verificação → 6 renderização
Filmar primeiro parece mais rápido e não é: o arco é o que muda sob revisão, e cada batida capturada contra um arco não acordado é recapturada. As Fases 0 e 0B são as duas coisas que você pode executar cedo — elas instalam ferramentas e definem a paleta. Tudo na Fase 1 espera por um plano aprovado.
🚀 Testando — o caminho rápido
🚨 Quem chama escolhe este modo. Você nunca escolhe. Você pode OFERECÊ-LO, em uma pergunta. Você não pode concluí-lo a partir das circunstâncias, e estas em particular não são consentimento:
- eles anexaram ou descompactaram o pacote da skill — isso é como alguém instala uma ferramenta, não uma declaração sobre o que querem que seja feito com ela;
- o pedido parece exploratório, ou veio sem um briefing;
- é a primeira coisa que pediram;
- você acharia o caminho rápido mais conveniente.
Alguém que diz "faça um vídeo de example.com" pediu um vídeo de example.com. Decidir por eles que realmente queriam um rascunho descartável entrega um rascunho mudo e sem marca em 1080p quando eles esperavam uma peça finalizada — e as partes que você pulou (o arco, as palavras, a marca) são exatamente aquelas que não podem ser adaptadas depois.
Quando não estiver claro, pergunte. "Isso é um teste rápido, ou um vídeo que você vai realmente mostrar a alguém?" Uma linha, e isso define em qual dos dois modos você está.
As portas de aprovação abaixo existem porque um vídeo que alguém verá é caro para errar. Uma execução descartável não é isso, e colocar um revisor em uma rodada de conceito para descobrir se a captura funciona é como uma boa ferramenta é abandonada nos primeiros dez minutos. Ambas as falhas são reais; só quem chama sabe qual se aplica.
O caminho rápido, uma vez que quem chama o escolheu:
- Repita de volta — uma frase: "considerando isso como um teste, então estou pulando as rodadas de aprovação e a marca; diga a palavra para o processo completo." Confirmar é melhor do que anunciar: dá a quem chama que está no outro modo um último momento barato para corrigi-lo.
- Um
PLAN.mdde duas linhas — o arco como uma frase, três ou quatro batidas. SemSCRIPT.md, sem rodada de aprovação. - A paleta neutra. Sem extração de marca, sem pré-visualização para aprovar.
- Mudo. Sem narração, sem chave ElevenLabs, sem verificação de transcrição.
- Apenas 1080p. Sem 4K, sem etapa de publicação.
- Apenas interno — não é mostrado a um cliente e não vai a lugar público algum. Se acontecer de alguém querer mostrá-lo, esse é um vídeo diferente: execute-o corretamente em vez de adaptar aprovação a um rascunho.
Todo o resto neste arquivo ainda se aplica — o caminho de captura, a verificação, a interrupção por consentimento ambíguo. Esses não são cerimônia; eles são o que impede que um vídeo quebrado pareça bom.
🛑 A porta do conceito
Esta skill não começa a partir de um pedido. Ela começa a partir de um PLAN.md aprovado (mais um SCRIPT.md literal para qualquer coisa voltada ao cliente). O caminho rápido acima é a única exceção, e só está disponível quando ninguém fora da sala verá o resultado.
Se não houver um, esse é o trabalho da skill video-plan, e leva uma passada: para que o vídeo SERVE, demo vs guia, o idioma, o arco, a lista de batidas, o texto. Faça isso primeiro e volte. Ler o aplicativo para escrever o plano é ok — gravá-lo não é.
Duas coisas que você deve independentemente de quem escreveu o plano, e ambas são perguntas, não anúncios:
Pergunte se deve analisar primeiro. "Devo olhar para o aplicativo e propor o que mostrar, ou você já sabe?" Ler um produto corretamente custa tempo real, e quem chama pode ter uma tela inicial diferente ou uma ideia pronta. Não gaste os minutos deles na sua suposição.
Faça a lista de batidas ser aprovada antes de filmar. Não o PLAN.md inteiro novamente aprovado — o plano já está aprovado — mas a lista concreta de tomadas que você está prestes a gravar: essas quatro batidas, nesta ordem, destacando estas coisas. Leva uma mensagem e é o último momento barato. Após a captura, mudar a ordem significa refilmar, porque uma batida cortada contra um arco diferente não se encaixa em um corte existente.
Confirme a origem da captura no chat. Qual ambiente será gravado e, portanto, qual versão do produto é a decisão do usuário e o alvo se move.
🚦 Primeira decisão: de onde vem a filmagem?
Se o assunto é uma página web que você pode alcançar → GRAVE VOCÊ MESMO. Não peça uma gravação de tela.
URL acessível? ── sim ──┬── é SEU (ou do seu cliente, com um briefing)
│ └─▶ Fase 1A · captura (references/playwright-capture.md)
│
└── é um site de OUTRA PESSOA
└─▶ Fase 1A · captura, mais references/foreign-sites.md
(porta de permissão, paredes de consentimento, cabeçalhos
fixos, desvio de retângulo de lazy-load — LEIA PRIMEIRO,
os primitivos de captura não são seguros em um DOM
estranho como está)
não (aplicativo desktop, Figma, ferramenta nativa, celular,
ou o usuário já te entregou um .mov)
▼
Fase 1B · ingerir uma gravação de tela
Aplicativo próprio e site de terceiros são o mesmo pipeline com uma passada de captura diferente. A composição, o sistema de design, a camada de verificação e a narração não mudam; a extração de marca já lê qualquer site ativo. O que muda é que você é apenas público por padrão, não pode definir estado, não deve escrever nada e está medindo um DOM que se move sob você. (Uma captura autenticada de terceiros é possível e desencorajada: precisa de aprovação explícita por domínio, o sandbox do navegador ativado e o arquivo de sessão destruído no final — references/foreign-sites.md §0.)
Isso não é uma preferência de estilo — o caminho de captura é uma filmagem melhor e aproximadamente metade do trabalho. Uma gravação de tela manual força você a re-engenharia reversa da linha do tempo a partir dos pixels, caçar e cortar as tentativas do autor, medir cada holofote manualmente, cortar o cromo do navegador e auditar a privacidade. Uma captura com script não tem nenhum desses problemas por construção, é livre de cromo, permite escolher o tamanho do texto e pode ser reexecutada quando a interface do usuário muda. Medido no mesmo fluxo: 71s de gravação de tela precisando de varredura densa de quadros vs uma captura de 28s com cada tempo de origem e retângulo de elemento entregue em beats.json — e 1,5x o tamanho do texto no quadro finalizado.
Mesmo assim, se o usuário já gravou algo, assista antes de capturar. Isso codifica o modelo deles do próprio produto — qual funcionalidade mostrar, em que ordem e qual é o ponto. Esse julgamento editorial é a única coisa que o caminho de captura não oferece de graça.
Leia as referências sob demanda — não as pré-carregue:
| Necessidade | Leia |
|---|---|
| de quem é a marca deste vídeo? (tokens, logotipo, tipo — um site funciona) | references/brand-style.md |
| dirija e grave o aplicativo você mesmo; 2x; cursor; autenticação; beats.json | references/playwright-capture.md |
| o alvo é um site que você NÃO possui (porta de permissão, paredes de consentimento, cabeçalhos fixos, desvio de retângulo de lazy-load, mídia ao vivo) | references/foreign-sites.md — leia ANTES de capturar |
| executando headless em um contêiner ou CI (fontes CJK/emoji ausentes, Chromium morrendo na primeira captura, "Executable doesn't exist" logo após instalar) | references/container-capture.md |
após alterar qualquer coisa em capture-lib.js | node <skill>/scripts/test-foreign-sites.mjs — fixtures locais, sem rede; cada caso é um defeito que foi enviado |
| o holofote enquadrou os pixels errados e as coordenadas estavam certas | references/foreign-sites.md §4 — meça com stableRect, não boundingBox |
| recapturar em outro idioma; re-temporizar um corte existente sem reconstruir a linha do tempo | references/playwright-capture.md §9-10 |
| recebeu um .mov cheio de tentativas — escolha e corte as tomadas limpas | references/multiple-takes.md |
| ffmpeg/CLI não funciona, "0 GB free", bunx, permissões | references/pitfalls.md §6 + execute scripts/setup-render-env.sh |
| comandos exatos de corte/recorte/velocidade/parado/remover-quadros | references/ffmpeg-recipes.md |
| a aparência: janela, holofote, cartões, crossfades, quadros congelados | references/design-system.md (+ assets/template.html) |
| construindo um guia de recursos de duas partes (painéis de conceito, batidas de ação, coreografia) | references/guide-track-build.md |
| narração / narração ElevenLabs, cota + armadilhas de voz | references/voiceover.md |
| a voz REALMENTE DIZ o script? (nomes de marca, acrônimos) | scripts/verify-narration.mjs — saída 1 = corrigir |
| o aplicativo renderiza vazio, 500, ou "offline" ANTES de você capturar | references/pitfalls.md §17 |
| o contrato TIMELINE.md; agindo no feedback "0:12 arrasta" | references/timeline-and-review.md |
| onde coloco o holofote? (nunca olhando) | references/design-system.md → "NUNCA olhe coordenadas" |
| uma borda do holofote continua cortando algo, seja qual for o padding usado | scripts/measure-spots.mjs — meça o espaço em branco do layout |
| o controle realmente não pode ser enquadrado (nenhuma faixa de 6px em alguma borda) | references/design-system.md → "Às vezes não há caixa" |
| o cromo do aplicativo fica onde o cartão de legenda vai | references/design-system.md → posicionamento de cartão por batida + dividir um cartão no corte |
| a imagem mostra o estado APÓS o clique (holofote em espaço vazio) | references/playwright-capture.md §16 — congele na marca _hover |
| uma mensagem de chat com script desapareceu; o agente "terminou" mas não tinha | references/playwright-capture.md §17-18 |
| "por que minha filmagem está congelada / desalinhada / com erro" | references/pitfalls.md |
| anéis pretos perdidos nos cliques; uma correção que silenciosamente não fez nada | references/pitfalls.md §11-13 |
| uma verificação disse PASS mas a coisa está errada | references/pitfalls.md §15 |
| antes de cada renderização (auditoria mecânica, saída 1 = corrigir) | scripts/audit-composition.mjs |
| o assunto está realmente visível? (limpeza de holofote + oclusão de cartão; saída 1 = corrigir, saída 2 = não foi possível verificar) | scripts/verify-material.mjs |
| após instantâneos: recorte ampliado por holofote (uma leitura de quadro completo perde texto cortado) | scripts/crop-spots.mjs |
| o quadro mostra o que a voz está FALANDO? (guias narrados, por tópico) | scripts/verify-topics.mjs |
| o aplicativo registra o que você faz — instantâneo antes, restaure depois | scripts/app-state.mjs |
| documentos de treinamento independentes ao lado do vídeo (apenas se solicitado) | references/companion-docs.md |
Trabalhe o loop em instantâneos, não em renderizações. snapshot --at t1,t2,… custa segundos; uma renderização custa minutos. Acerta o enquadramento, coordenadas do holofote, texto e privacidade em imagens estáticas, depois renderize uma vez e verifique o movimento.
Fase 0 — Ambiente (uma vez por máquina/sessão)
Um comando cobre todos os casos — macOS ou Linux, uma máquina saudável, um ffmpeg ausente ou removido, um HyperFrames ausente ou o bug falso de "0 GB free" statfs. Não diagnostique manualmente:
render_env="$(bash <skill>/scripts/setup-render-env.sh)" && eval "$render_env"
Não source <(…). Bash reporta o status de source, não da substituição de processo que o alimenta, então uma inicialização que morre no meio — sem rede, uma instalação falhada — reporta sucesso e deixa você com metade de suas exportações definidas. Capturar primeiro revela a falha e não aplica nada quando falha.
Isso instala hyperframes (fixado) se ausente, resolve um ffmpeg completo, corrige a verificação de disco apenas se este SO realmente tiver o bug e exporta HYPERFRAMES_FFMPEG_PATH, HYPERFRAMES_FFPROBE_PATH, PRODUCER_BROWSER_GPU_MODE e HYPERFRAMES_CLI.
Ele sonda por filtros, não por um binário chamado ffmpeg. O pipeline precisa de fps/pad (fixação de quadro da Fase 3), crop (remoção de cromo da Fase 1B) e freezedetect (audit-composition.mjs + a varredura de ar morto da Fase 6). Duas compilações removidas comumente já estão em PATH e passam uma verificação ingênua antes de falhar no meio do pipeline: o ffmpeg empacotado do Playwright e o pacote do compositor do Remotion. Ordem de resolução: um ffmpeg completo do sistema → brew (macOS) → os pacotes ffmpeg-static/ffprobe-static em ~/.hyperframes-cli (todas as plataformas, sem sudo — o caminho normal no Linux) → um pacote do compositor do Remotion como último recurso, que avisa porque não tem freezedetect, então essas duas verificações de congelamento passam silenciosamente e você deve verificar manualmente (armadilhas #1, #16).
Em seguida, renderize via a CLI local para a qual ele aponta ($HYPERFRAMES_CLI), nunca bunx/npx hyperframes — eles re-materializam uma cópia nova cada...