every-app/video-skills

Vídeo narrado

A pessoa grava uma única tomada de si mesma falando sobre um storyboard. O agente edita a tomada e anima capturas de tela reais do produto para ela: cada cena começa, cada clique é executado e cada busca é digitada na palavra que a nomeia. O vídeo inteiro é código (uma composição HyperFrames mais uma lista de edição), então uma nova tomada, uma tela alterada ou uma ordem diferente é uma reexecução, não uma reedição.

O vídeo se adapta à narração, nunca o contrário. A pessoa dita o gosto; o agente produz cortes, mostra quadros e pergunta.

Configuração

• ffmpeg no PATH, uv, Node 20+ com npx (HyperFrames 0.8.62 roda via npx), e Playwright com Chromium para capturas. Funciona em macOS, Linux e Windows.
• Whisper roda localmente: mlx-whisper no Apple Silicon, faster-whisper em outros. uv run instala o correto.
• SK=<diretório deste skill>/scripts. Cada ferramenta roda como uv run $SK/<ferramenta>.py; cada uma declara suas próprias dependências.
• Trabalhe em uma pasta fora dos arquivos rastreados de qualquer repositório (uma .logs/<vídeo>/ ignorada pelo git, ou uma pasta temporária):

<work>/
  assets/            capturas, plano de fundo, cartão final
  storyboard.json    as cenas -> storyboard/index.html
  takes/<nome>/      uma pasta por tomada gravada: saída da sonda, transcrições, edit.json, a narração editada e webcam
  video.py           o script de composição -> comp/ (index.html, renders/)
  NOTES.md           todas as decisões: cortes e motivos, início de cenas, comandos de reconstrução

1. Briefing

Confirme em uma breve troca, oferecendo padrões:

• Formato: vídeo de lançamento, demonstração de funcionalidade ou tutorial (referências/formatos.md). Um vídeo de lançamento fica abaixo de 2:00 incluindo o cartão final.
• Público-alvo, os três ou quatro momentos que o vídeo deve acertar e a chamada para ação.
• Dados de exemplo que demonstram bem: um negócio ou busca de exemplo que seja legível de relance para este público.
• Marca: uma imagem de fundo (ou o gradiente padrão), um cartão final (a imagem OG do produto funciona bem), a URL mostrada na barra de título da janela.

2. Captura

Capturas de tela reais do produto em execução a 1440x900, 2x, a partir de um script Playwright baseado em $SK/capture.mjs: quadros por tecla para qualquer coisa digitada na tela, estados antes e depois para qualquer coisa clicada, tomadas altas para qualquer coisa rolada e alvos de clique medidos para o ponteiro. Se o aplicativo precisar de login, passe login e a primeira execução abrirá uma janela do navegador para a pessoa fazer login uma vez. Nunca desenhe interface do usuário ou edite pixels. Observe cada captura antes de usá-la. Detalhes e a questão de privacidade: referências/captura.md.

3. Storyboard

Escreva storyboard.json, um cartão por cena: a captura de tela, o que está na tela, três a seis marcadores do que dizer (notas curtas, não frases) e segundos aproximados. Construa e mostre:

uv run $SK/storyboard.py storyboard.json storyboard/

É uma página simples, uma seção por cena. Publique storyboard/ (index.html mais frames/) quando o harness puder publicar uma página; caso contrário, abra localmente. Itere até a pessoa estar pronta para gravar, então entregue as notas de gravação em referências/storyboard-and-recording.md. Depois que ela começar a gravar a partir dele, não altere o storyboard sem perguntar.

4. Gravação

A pessoa grava uma tomada, webcam e voz em um único arquivo (qualquer gravador de webcam: QuickTime, Photo Booth, Windows Camera, OBS), falando através das cenas. Erros são aceitáveis: ela recomeça a frase e continua. Várias tomadas são aceitáveis; cada uma recebe uma pasta de tomada.

5. Editar a tomada

uv run $SK/sonda.py <gravação> takes/<nome>       # take.wav, cam.mp4, take.json; verificar still.jpg, reexecutar com --crop se necessário
uv run $SK/transcrever.py takes/<nome>            # duas passagens: simples, e uma que escreve vícios de linguagem
uv run $SK/analisar.py takes/<nome>               # candidatos: pausas longas (com cortes), vícios, recomeços, sons estranhos
uv run $SK/rastrear.py takes/<nome> <a>:<b>       # colocar cada corte no traço de energia (--fine para linhas de 5 ms)
uv run $SK/testar_corte.py takes/<nome> c1=<a>:<início_corte>,<fim_corte>:<b>   # ouvir um corte: deve soar como a frase pretendida
uv run $SK/saltar.py takes/<nome> <início_corte>:<fim_corte> --slide 0.3        # quão visível o corte é na bolha da webcam
# escrever takes/<nome>/edit.json, então:
uv run $SK/editar.py takes/<nome>                 # edl.json; imprime a narração editada e os vícios mantidos: ler tudo
uv run $SK/construir.py takes/<nome>              # narração-edit.wav, cam-edit.mp4 (crossfades e dissolução da webcam em cada corte)
uv run $SK/mestre.py takes/<nome>                 # narração.wav a -16 LUFS

Dois níveis de edição (referências/edição.md):

• Leve, o padrão: cortar recomeços e falsos inícios, e aparar silêncios (uma pausa acima de ~1,1 s mantém 0,7 s, 0,9 s em uma mudança de cena). Cada "um" e hesitação curta permanece.
• Menos vícios de linguagem, quando solicitado: também remover a maioria dos "ums" que ficam sozinhos entre frases, e aparar pausas acima de ~0,8 s para cerca de 0,55 s. Deixe qualquer vício de linguagem colado a uma palavra vizinha.
• Cada corte se situa no tom ambiente no traço e passa em um teste de splice antes de ser incluído. Cortes de recomeço vão em mudanças de cena quando possível, para que o corte de imagem esconda o salto na bolha.

6. Compor para as palavras

uv run $SK/cues.py takes/<nome>       # words.json, a folha de cues (transcrições em nível de clipe da narração final)
NV_SCRIPTS=$SK ASSETS=assets uv run --with numpy python video.py   # o script de composição -> comp/; imprime cada cue em contexto
uv run $SK/render.py comp lint
uv run $SK/render.py comp snapshot 1,14.2,22.5,40.1

Escreva video.py a partir do exemplo trabalhado, examples/openseo-launch/video.py: inícios de cena e tempos de cue a partir da folha de cues, camadas de câmera sobre as capturas e uma coreografia baseada em palavras. As posições de cue do exemplo se ajustam apenas à sua própria edição: reancore cada uma e leia a tabela de cues que imprime após cada mudança na edição. As regras de temporização estão em referências/composição.md; as mais importantes:

• Uma cena começa 0,3 s antes de sua primeira palavra, ou exatamente em um corte na pausa antes dela.
• Cada ação ocorre na palavra que a nomeia: o clique em "copiar", a digitação enquanto a busca é falada, o zoom em um número enquanto é dito, o ponteiro em cada item enquanto é nomeado.
• O primeiro quadro é o pôster: o aplicativo inteiro, sem fade-in. Algo se move em cada quadro.
• Um rótulo curto por momento. Faça snapshot de cada início de cena, clique e rótulo, e observe-os antes de renderizar.

7. Renderizar e verificar

uv run $SK/render.py comp render
uv run $SK/compositor.py comp takes/<nome> comp/renders/<vídeo>-1080p.mp4
uv run $SK/verificar.py comp/renders/<vídeo>-1080p.mp4 comp takes/<nome>
uv run $SK/quadros.py comp/renders/<vídeo>-1080p.mp4 comp/renders/quadros.png

Nada vai para a pessoa até que a verificação mostre a janela em todos os quadros, cada ponto da webcam no deslocamento de quadro 0, uma mediana de áudio de 0 ms e cerca de -16 LUFS, e você tenha lido a transcrição e olhado os quadros (referências/verificação.md).

8. Revisar e iterar

• Dê à pessoa o caminho do mp4, o que foi cortado e algo para ouvir.
• Mantenha NOTES.md atualizado: cada corte com seu motivo, inícios de cena, comandos de reconstrução. Espere várias rodadas.
• Variantes são baratas: outra tomada, uma edição leve e uma com menos vícios, uma ordem diferente de cenas. Cada uma é uma pasta de tomada ou um script de composição; com subagentes, construa-as em paralelo sob nomes de arquivo separados para que nunca colidam.

Regras rígidas

• Apenas telas reais. Esconda o que não faz parte da história (um banner, um aviso de cookie); nunca pinte sobre pixels.
• Verifique capturas e gravações quanto a segredos e dados pessoais (chaves de API, e-mails e nomes de outras pessoas, dados de clientes, URLs de localhost) antes de renderizar; emoldura ao redor deles ou recapture, e tenha qualquer chave que apareceu na tela revogada. O próprio nome ou e-mail da pessoa no aplicativo é aceitável depois que ela confirmar.
• As gravações e sessão de login da pessoa permanecem na máquina dela. Não publique nada sem ser solicitado.

O que ainda pega as pessoas: referências/armadilhas.md.