Communitygithub.com

daniel-video-annotate

Transforma uma gravação de tela em uma versão explicada, cortando pausas, pausando em cada ação-chave, destacando os controles e adicionando legendas sobre o que foi feito e por quê. Use quando o usuário invocar /daniel-video-annotate, ou pedir para anotar ou explicar um vídeo.

O que é daniel-video-annotate?

Esta skill processa gravações de tela (screen recordings) e produz um vídeo explicativo editado. Primeiro, ela remove trechos de inatividade (onde a imagem fica parada por mais de 1,5s), mantendo apenas o primeiro segundo de cada pausa. Em seguida, gera folhas de contato para entender a sequência de ações, e o usuário escolhe pontos de pausa que correspondam a decisões ou resultados importantes para a demonstração. Para cada pausa, a skill extrai frames individuais e permite definir uma caixa delimitadora ao redor do controle sendo usado. Finalmente, ela insere legendas descritivas e escurece o restante da tela, criando um vídeo explicativo pronto para ser compartilhado. A ferramenta é útil para tutoriais, demonstrações de produto e análise de fluxos de trabalho. Suporta os seguintes parâmetros: posição da legenda (acima ou abaixo), velocidade de leitura, e tolerância para ruído na detecção de movimento.

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/dancodes/skills-agents/tree/HEAD/skills/daniel-video-annotate

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

/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: --clearance linhas dele, 3 por padrão, que limpa os controles de um pequeno player embutido.
  • --position top coloca 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.
  • trim só 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.
  • trim só 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 --noise para 0.001 quando uma estiver faltando.

Erros

O que você vêCausaCorreção
this ffmpeg build has no drawtext filterffmpeg foi compilado sem libfreetypeInstale uma versão completa, ex.: brew install ffmpeg
no font file foundNenhum dos caminhos de fonte conhecidos do macOS ou Linux existePasse --font /caminho/para/fonte.ttf para sheets, frames e annotate
Unrecognized option 'fps_mode'ffmpeg é mais antigo que 5.1Atualize o ffmpeg
no still stretches found, nothing writtenA imagem nunca fica parada por 1,5 sUse o original como <cortado>, ou reduza --min-freeze
O vídeo cortado ainda parece lentoEsperas animadas foram mantidas, ou um segundo por trecho parado se acumulaReduza --keep para 0.5
O vídeo cortado pula rápido demais para acompanharUm segundo por tela é muito curto para esta gravaçãoAumente --keep para 2 e --min-freeze para 3
pause N at Ts is past the end of the videoOs 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 checkA caixa foi medida em uma imagem reduzidaLeia-a dos rótulos da grade do PNG frames
A legenda é cortada na borda direitaA fonte é mais larga do que o script assumiuPasse --wrap 80, ou um número menor, para annotate
Os controles do player cobrem a legendaO espaço sob a legenda é mais curto que os controlesAumente --clearance para 5, ou passe --position top
pause N would sit at ..., past the endcheck recebeu o vídeo cortadoDê a ele o vídeo explicado
Qualquer outro ffmpeg failedDesconhecidoExecute 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 scpdvm get passa todos os argumentos para scpExecute 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.

Habilidades Relacionadas