/daniel-video-annotate
Entrada: um arquivo de vídeo, mais o motivo de cada passo (um ticket, um merge request, a mensagem do usuário). Saída, ao lado da entrada: <nome>-trimmed.mp4 e <nome>-explained.mp4. O arquivo de entrada nunca é alterado.
O vídeo explicado reproduz a gravação e, em cada pausa, segura um quadro pelo tempo de espera, escurece a tela ao redor de um controle destacado e mostra uma legenda de uma frase em uma faixa preta abaixo ou acima da gravação. A faixa torna o vídeo mais alto, de modo que a gravação nunca é coberta.
annotate.py fica ao lado deste arquivo. Nos comandos abaixo, A representa python3 "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/daniel-video-annotate/annotate.py". Ele precisa apenas de ffmpeg, ffprobe e a biblioteca padrão do Python. <work> é uma pasta temporária: o scratchpad da sessão quando houver um, senão ${TMPDIR:-/tmp}/video-annotate/<nome>/.
Se o vídeo estiver na VM de desenvolvimento, copie-o primeiro com dvm get <caminho remoto> <diretório local>.
0. Escolha a velocidade de leitura
O tempo de espera é por quanto tempo cada legenda fica legível na tela. Cada pausa segura 1,5 s mais o tempo para ler sua legenda na velocidade de leitura, e pelo menos 2,5 s. Use a velocidade em palavras por minuto que o usuário forneceu, senão 350 ppm. Não pergunte. Quando o usuário forneceu um tempo fixo de espera em segundos, use-o para cada pausa.
Feito quando você tem uma velocidade de leitura ou um tempo fixo de espera.
1. Corte as esperas
A trim <vídeo> <nome>-trimmed.mp4
Ele encontra cada trecho onde a imagem fica parada por 1,5 s ou mais, mantém o primeiro segundo de cada e corta o resto. Ele imprime o número de trechos e a duração antes e depois. Pule esta etapa quando o usuário quiser manter as esperas e use o original como <cortado> abaixo.
Cada tempo nas etapas posteriores é um tempo em `. Cortar novamente move todos os tempos, então refaça as etapas 2 a 6 após qualquer novo corte.
2. Aprenda a história
A sheets <cortado> <work>/sheets
Ele escreve folhas de contato com seis quadros cada, um quadro por segundo, com o tempo exato queimado em cada quadro. Leia cada folha. Leia o ticket ou outra fonte para o motivo de cada passo.
Feito quando você pode dizer, em ordem, o que a pessoa faz na tela, qual valor cada ação define e qual resultado prova o ponto da gravação.
3. Escolha as pausas
Pause uma vez para cada escolha (um valor selecionado, um botão pressionado, uma página aberta intencionalmente) e uma vez para cada resultado que prova o ponto. Pule navegações que não envolvem decisão.
Para cada pausa, encontre o quadro e a caixa:
A frames <cortado> <work>/frames 23.0 23.2 23.4 23.6
Ele escreve um PNG em tamanho real por tempo, nomeado pelo seu tempo exato, com uma grade vermelha a cada 100 px e as coordenadas de pixel rotuladas ao longo das bordas superior e esquerda.
- Escolha um quadro estável. Gravações contêm quadros parcialmente renderizados, como um painel que fica em branco por alguns quadros após um clique. Avance em incrementos de 0,2 s até que o controle e seu entorno estejam totalmente desenhados.
- Para uma escolha em uma lista, prefira o quadro onde a lista está aberta e o cursor está sobre a opção. Se esse quadro estiver parcialmente renderizado, use o quadro logo após, onde o campo mostra o novo valor.
- Leia a caixa como
[x, y, largura, altura]a partir dos rótulos da grade, em pixels de origem. A ferramenta Ler reduz imagens grandes, portanto posições medidas na imagem exibida estão erradas; os rótulos permanecem corretos. - Destaque o único controle sobre o qual a legenda fala, com alguns pixels de margem. Uma pausa pode omitir
caixa, e então nada é escurecido.
Feito quando cada pausa tem um tempo cujo quadro você examinou e uma caixa lida desse mesmo quadro.
4. Escreva as legendas
Uma frase por pausa. Ela diz o que fazemos e por quê, ou o que a tela agora mostra e por quê. Nomeie a coisa concreta: a linha, o campo, o valor antigo e o novo valor.
Tire o "porquê" da fonte. Quando a fonte não fornecer o motivo de um passo, escreva o que é visível e liste essa legenda como inferida no relatório. Aplique a skill writing-tics às legendas. Mantenha cada uma com cerca de 180 caracteres, porque a faixa é tão alta quanto a legenda mais longa.
5. Renderize
Escreva <work>/spec.json, uma lista em ordem de tempo:
[
{"at": 12.0, "box": [399, 569, 180, 29], "caption": "Alteramos o Tamanho do Item 1 de M para L na tabela, o que salva L no servidor."},
{"at": 23.6, "box": [659, 500, 192, 24], "caption": "..."}
]
at está em segundos em <cortado>. Em seguida, defina hold em cada pausa:
A holds <work>/spec.json [--wpm <velocidade>]
Ele escreve o tempo de espera de cada pausa no spec e o imprime ao lado da contagem de palavras. Com um tempo fixo de espera, defina hold em cada pausa você mesmo. Uma pausa sem hold segura 6 segundos.
A annotate <cortado> <work>/spec.json <nome>-explained.mp4 [--position top|bottom] [--clearance <linhas>]
A faixa de legenda vai para onde o usuário pediu. Sem solicitação, ela vai para a parte inferior.
--position bottomé o padrão. Players de vídeo desenham seus controles sobre a borda inferior, então a faixa ganha espaço vazio sob a legenda:--clearancelinhas dele, 3 por padrão, que limpa os controles de um pequeno player embutido.--position topcoloca a faixa acima da gravação, onde nenhum player desenha controles. Não requer clearance.
As caixas permanecem nas coordenadas de <cortado> para ambas as posições.
6. Verifique cada pausa
A check <nome>-explained.mp4 <work>/spec.json <work>/check
Ele escreve um quadro do meio de cada pausa. Leia cada um. A caixa deve estar sobre o controle, a legenda deve estar completa e não cortada na borda direita, e o quadro deve ser o estável que você escolheu. Corrija o spec e renderize novamente até que cada pausa passe.
7. Relatório
Forneça o caminho, o tamanho e a duração do vídeo explicado, depois as legendas em ordem, cada uma com o controle que destaca. Diga quais legendas são inferidas. Diga que você verificou um quadro por pausa e não assistiu à reprodução.
Limites
- A saída não tem áudio. Informe ao usuário quando a entrada tinha uma faixa de voz.
- A taxa de quadros é a taxa média da entrada, arredondada e mantida entre 5 e 30 quadros por segundo.
trimsó corta uma imagem que está completamente parada. Um spinner, uma barra de progresso, um cursor piscando ou um relógio mantêm a imagem em movimento, então essas esperas permanecem. Uma espera interrompida por uma pequena mudança é mantida como várias peças de um segundo.trimsó corta quadros dentro de um trecho parado, e mantém o primeiro quadro de cada mudança. Uma mudança menor que a tolerância--noise(padrão 0.003), como um caractere pequeno, conta como parada e pode ser cortada. A etapa 2 é a verificação: toda ação deve aparecer nas folhas. Reduza--noisepara 0.001 quando uma estiver faltando.
Erros
| O que você vê | Causa | Correção |
|---|---|---|
this ffmpeg build has no drawtext filter | ffmpeg foi compilado sem libfreetype | Instale uma versão completa, ex.: brew install ffmpeg |
no font file found | Nenhum dos caminhos de fonte conhecidos do macOS ou Linux existe | Passe --font /caminho/para/fonte.ttf para sheets, frames e annotate |
Unrecognized option 'fps_mode' | ffmpeg é mais antigo que 5.1 | Atualize o ffmpeg |
no still stretches found, nothing written | A imagem nunca fica parada por 1,5 s | Use o original como <cortado>, ou reduza --min-freeze |
| O vídeo cortado ainda parece lento | Esperas animadas foram mantidas, ou um segundo por trecho parado se acumula | Reduza --keep para 0.5 |
| O vídeo cortado pula rápido demais para acompanhar | Um segundo por tela é muito curto para esta gravação | Aumente --keep para 2 e --min-freeze para 3 |
pause N at Ts is past the end of the video | Os tempos vieram do original e não de <cortado> | Leia os tempos novamente de sheets e frames de <cortado> |
pause N box ... is outside the frame, ou a caixa erra o controle em check | A caixa foi medida em uma imagem reduzida | Leia-a dos rótulos da grade do PNG frames |
| A legenda é cortada na borda direita | A fonte é mais larga do que o script assumiu | Passe --wrap 80, ou um número menor, para annotate |
| Os controles do player cobrem a legenda | O espaço sob a legenda é mais curto que os controles | Aumente --clearance para 5, ou passe --position top |
pause N would sit at ..., past the end | check recebeu o vídeo cortado | Dê a ele o vídeo explicado |
Qualquer outro ffmpeg failed | Desconhecido | Execute A selftest. Ele corta e anota um clipe gerado, então uma passagem significa que ffmpeg funciona e a entrada ou o spec está com defeito |
dvm get --help falha com um erro scp | dvm get passa todos os argumentos para scp | Execute dvm help |
macOS não tem comando timeout. Um vídeo 720p de um minuto renderiza em alguns segundos, então execute os comandos diretamente.