Communitygithub.com

Análise de Vídeo (brief principal)

Procedimento interno (não é um ponto de entrada independente) — pipeline compartilhado de análise de filmagens que produz transcrições de áudio, folhas de contato e resumos escritos pelo Sonnet. É invocado de ponta a ponta pelos skills process-library e reprocess-with-contact-sheets; não o acione por conta própria.

O que é Análise de Vídeo (brief principal)?

Este skill define o pipeline de análise de filmagens para o assistente buttercut, projetado para processar clipes de vídeo em três artefatos essenciais: transcrições de áudio, folhas de contato e resumos em markdown gerados pelo modelo Sonnet. Ele deve ser executado após a configuração da biblioteca e antes de qualquer trabalho de corte. O fluxo começa com a prevenção de hibernação da máquina durante o processamento (opcional), seguido pela execução sequencial de transcrição com WhisperX e geração de folhas de contato com ffmpeg. Depois, opcionalmente, refina as transcrições usando subagentes para corrigir nomes próprios mal interpretados. Por fim, despacha subagentes Sonnet para analisar as folhas de contato e transcrições, gerando resumos detalhados que alimentarão todas as decisões de corte posteriores. O skill suporta os principais sistemas operacionais (macOS e Windows) através de plataformas como Claude Code e Cursor, e gerencia o progresso com tarefas públicas visíveis ao usuário.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/barefootford/buttercut/tree/HEAD/skills/analyze-video

Perguntar na sua IA favorita

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

Documentação

Skill: Analisar Vídeo (brief principal)

Este é o manual do fluxo principal para a etapa de trabalho Analisar Vídeo. Execute-o após a configuração da biblioteca, antes de qualquer trabalho de corte. Ele cobre os três artefatos produzidos por clipe: transcript de áudio, contact_sheet e summary em markdown. O agente de roughcut lê o diálogo sob demanda executando script_extractor.rb sobre o JSON da transcrição — não há um artefato de script separado.

SKILL.md é o brief de despacho do agente principal. O prompt de trabalho do subagente reside em agent_prompt.md — inclua seu conteúdo ao iniciar um agente Task. Não passe SKILL.md.

Terminologia

  • Para o usuário: chame de "análise de filmagens" ou "analisando filmagens".
  • Interno/nomes de arquivo: "transcrição" (campo transcript no library.yaml, etc.).

Pré-requisitos

  • A configuração da biblioteca está completa (library.yaml existe, o esquema está atualizado — execute as migrações de AGENTS.md se não estiver).
  • Leia libraries/settings.yaml diretamente para obter whisper_model. Para campos da biblioteca, leia o snapshot via ruby lib/buttercut/library.rb <nome> summary e extraia os valores necessários do JSON — não analise library.yaml diretamente.

Neste ponto, crie uma lista de tarefas, visível ao usuário, com etapas de alto nível e não técnicas para que ele possa acompanhar o plano geral de processamento da biblioteca. Inclua etapas de cafeína apenas se ele tiver optado por elas. Ex.:

- [ ] Manter computador ativo
- [ ] Criar transcrições (0/30)
- [ ] Analisar filmagens (0/30)
- [ ] Deixar computador dormir novamente
- [ ] Revisar as filmagens juntos

Essas tarefas públicas mapeiam as etapas abaixo: "Manter computador ativo" é a Etapa 1 e "Deixar computador dormir novamente" é a Etapa 6; "Criar transcrições" cobre a execução mecânica na Etapa 2 mais a passagem de refinamento opcional na Etapa 3 (avance sua contagem a partir das linhas de progresso [transcript …] da Etapa 2; mantenha-a em andamento durante a Etapa 3 quando o refinamento estiver ativo); "Analisar filmagens" acompanha os resumos na Etapa 4 (avance sua contagem à medida que os clipes são resumidos, não após as folhas de contato); "Revisar as filmagens juntos" é a Etapa 5.

No chat público, refira-se a essas etapas não técnicas. Mantenha o trabalho técnico (WhisperX, geração de folhas de contato, resumos Sonnet) nos bastidores.

Etapa 1 — Evitar hibernação durante o processamento

Antes de iniciar a análise, pergunte ao usuário (via AskUserQuestion): "O processamento pode demorar um pouco — quer que eu mantenha seu computador ativo até terminar?" Opções: "Sim (Recomendado)" e "Não".

Se sim, inicie o auxiliar keep-awake da plataforma em segundo plano e armazene o PID — você o encerrará na Etapa 6 quando a análise terminar. (O backup é tratado pelo skill chamador — process-library — após este skill retornar.)

macOS:

caffeinate -i -w $$ &
KEEPAWAKE_PID=$!

Windows (Git Bash):

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/keep_awake.ps1 &
KEEPAWAKE_PID=$!

Ambos evitam a hibernação durante o processamento das filmagens (a tela pode desligar, o que é aceitável).

Etapa 2 — Processar filmagens (transcrições, depois folhas de contato)

(Se você chegou a este skill diretamente em vez de via process-library, primeiro informe ao usuário: "Encontrei [N] vídeos ([tamanho total]). Iniciando análise das filmagens...")

São dois comandos mecânicos que você executa um após o outro — primeiro as transcrições, depois as folhas de contato. Nunca os execute ao mesmo tempo: WhisperX consome muita RAM, e sobrepor os dois é exatamente o que queremos evitar. Não implemente manualmente nenhum deles com subagentes; cada um é executado de forma idêntica todas as vezes, ~2 clipes por vez, registrando cada clipe no library.yaml assim que termina. Ambos são idempotentes — eles só tocam nos clipes que ainda estão sem aquele artefato — portanto, uma nova execução termina apenas o que falta. Eles serão executados em um serviço de jobs no estilo Sidekiq em miniatura. Você executará o comando e depois monitorará o arquivo de log que será retornado para acompanhar o progresso.

Etapa 2a — Transcrições. Se estiver usando Claude Code, execute com run_in_background: true na ferramenta Bash. Caso contrário, use a ferramenta/argumento correto para executar em segundo plano.

ruby lib/buttercut/process_footage.rb transcripts <nome-da-biblioteca>

Imediatamente após iniciar, configure um Monitor ou equivalente no arquivo de log para receber uma notificação para cada clipe concluído ou com falha:

tail -f tmp/logs/processing/<nome-da-biblioteca>/$(date +%Y-%m-%d).log | grep --line-buffered -E "TranscribeJob  (done|error)|transcript: [0-9]+/[0-9]+|Error|error:|failed|Traceback"
ruby lib/buttercut/library.rb <nome> pending transcript   # Lista JSON; concluído = N − seu tamanho

Atualize "Criar transcrições 5/20", ou seja, número_de_clipes_concluídos/total_de_clipes à medida que os clipes terminam, para que o usuário veja o progresso. Quando a tarefa em segundo plano for concluída, ela sairá com código diferente de zero se algum clipe falhar. Em caso de falha, execute novamente uma vez. Se falhar novamente, investigue e então crie uma correção para lidar com isso de forma elegante ou informe o usuário sobre o problema com o clipe e, potencialmente, remova-o da biblioteca.

Aguarde a Etapa 2a terminar antes de iniciar a Etapa 2b.

Etapa 2b — Folhas de contato. Assim que as transcrições estiverem concluídas, construa as folhas (uma passagem ffmpeg rápida — pode ser em primeiro plano):

ruby lib/buttercut/process_footage.rb contact-sheets <nome-da-biblioteca>

As folhas de contato ficam nos bastidores — não as exiba como uma contagem pública. Marque "Criar transcrições" como concluído assim que a Etapa 2a terminar e qualquer refinamento (Etapa 3) estiver completo.

Ajuste (opcional): ambas as etapas leem parallel_jobs de libraries/settings.yaml (padrão 2); para sobrescrever em uma execução, use --jobs N. Cada uma escreve um log com timestamp em tmp/logs/processing/<biblioteca>/ para revisão posterior.

Reprocessamento. Cada etapa pula clipes que já possuem seu artefato. Para refazer um — por exemplo, uma transcrição que entendeu mal um nome — execute novamente essa etapa com --force --clips NOME.mov. --force sozinho reconstrói todos os clipes.

Etapa 3 — Refinar transcrições (julgamento — apenas se transcript_refinement: true)

O refinamento é a única parte da transcrição que envolve julgamento — corrigir nomes próprios mal interpretados com base no contexto da biblioteca — então permanece uma etapa de modelo, executada após a passagem mecânica. Pule esta etapa inteira se o transcript_refinement da biblioteca for false.

Quando for true, despache subagentes de refinamento (2-4 em paralelo, de forma contínua) sobre as transcrições que a Etapa 2a acabou de escrever. Inclua skills/transcribe-audio/refine_instructions.md como prompt de cada subagente e passe, inline:

  • transcript_path — caminho absoluto para o JSON da transcrição do clipe em libraries/<biblioteca>/transcripts/
  • user_context e footage_summary — valores atuais de ruby lib/buttercut/library.rb <nome> summary (strings vazias são aceitáveis; o refinamento ainda captura correções de tokens sem sentido e auto-testemunho)

Os subagentes editam o JSON da transcrição no local e retornam uma lista curta de correções. Eles NÃO tocam no library.yaml — a Etapa 2a já definiu o campo transcript. Marque a tarefa pública "Criar transcrições" como concluída quando o refinamento terminar.

Etapa 4 — Resumos (subagentes Sonnet, em lote, contínuos)

Despache subagentes analyze-video no modelo Sonnet. O Sonnet lê a folha de contato com uma especificidade visual notavelmente maior que o Haiku (captura roupas, arquitetura, enquadramento da câmera) — vale a pena, pois os resumos alimentam todas as decisões de corte posteriores.

Agrupe 10 clipes por subagente, até 10 subagentes em paralelo, com despacho contínuo. Cada subagente processa seus 10 clipes sequencialmente; o agrupamento amortiza a sobrecarga de ~5–10s por despacho de agente. Para uma biblioteca de 93 clipes, são ~10 subagentes no total, em vez de 93. Inicie o próximo subagente assim que um retornar — não espere toda a leva de 10 terminar, ou você perderá ~30% do tempo real para o agente mais lento da leva.

Para cada subagente, passe uma lista de 10 registros de clipe inline. Cada registro de clipe precisa de:

  • video_filename — nome base do vídeo (usado no cabeçalho do resumo e na linha de resposta)
  • duration — string de duração do library.yaml (ex.: 00:01:19); o agente a renderiza no cabeçalho do resumo
  • contact_sheet_path — caminho absoluto para o _full.jpg (da etapa 2)
  • transcript_path — caminho absoluto para o JSON da transcrição de áudio (da etapa 2); o subagente extrai o diálogo sob demanda via script_extractor.rb
  • summary_output_path — caminho absoluto onde o agente deve escrever o resumo em markdown. Não construa este nome de arquivo manualmente; peça à biblioteca o caminho canônico: ruby lib/buttercut/library.rb <nome> field_path summary <clipe> (lida com a convenção summaries/summary_<clipe>.md para você, com ou sem a extensão do arquivo)

À medida que cada subagente retorna seu lote, atualize library.yaml com summary para cada clipe desse lote:

ruby lib/buttercut/library.rb <nome> complete summary <nome-do-arquivo> [<nome-do-arquivo>...]

O campo contact_sheet já foi populado na etapa 2, portanto o retorno do subagente contribui apenas com resumos.

Se um subagente retornar resumos inline em vez de escrevê-los no disco (às vezes o Sonnet alucina dizendo "a ferramenta Write está bloqueada" e despeja o markdown em sua resposta), não tente novamente cegamente — apenas extraia cada resumo da resposta do agente e Write para o summary_output_path correspondente a partir do thread pai. Em seguida, execute o comando complete summary normalmente. Mais rápido do que redespachar, e o conteúdo já está lá.

(As folhas de contato por segmento geradas para clipes longos residem no disco junto com a folha _full e são descobertas por convenção — elas não são listadas no library.yaml.)

Não avance até que os resumos estejam completos. Avance a contagem de "Analisar filmagens" à medida que os clipes são resumidos; marque como concluído quando terminar.

Imagens. Imagens estáticas pulam as Etapas 2–3 inteiramente (sem áudio para transcrever, sem folha de contato para construir) — um summary é o único artefato de que precisam, e elas aparecem em ruby lib/buttercut/library.rb <nome> pending summary junto com os vídeos. A imagem é a coisa a ser observada, portanto resuma-a diretamente: leia o arquivo de imagem (é pequeno) a partir do thread principal ou de um subagente Sonnet e escreva uma descrição de 3–4 frases — assuntos, cenário, composição, qualquer texto na imagem — para o caminho canônico de ruby lib/buttercut/library.rb <nome> field_path summary <nome-do-arquivo-de-imagem>. Observe que as chaves de clipe de imagem incluem a extensão (title-card.png → summaries/summary_title-card_png.md), o que field_path trata para você. Em seguida, registre-o da mesma forma: ruby lib/buttercut/library.rb <nome> complete summary <nome-do-arquivo-de-imagem>.

Etapa 5 — Confirmar compreensão das filmagens com o usuário

(Esta é a tarefa "Revisar as filmagens juntos".) Assim que cada resumo estiver escrito, converse sobre o que as filmagens realmente mostram — confirme nomes de personagens, locais, o fio narrativo, quaisquer clipes perdidos ou fora do tema, e a intenção criativa do usuário para esta biblioteca. Use uma conversa simples;recorra ao AskUserQuestion apenas ao oferecer uma escolha discreta. À medida que aprender coisas, atualize:

  • footage_summary e user_context via ruby lib/buttercut/library.rb <nome> update_metadata footage_summary "..." (e o mesmo com user_context)
  • arquivos individuais summary_*.md quando um resumo rotular alguém incorretamente ou perder um detalhe importante (ex.: "um homem de jaqueta marrom" → o nome do usuário)

Este é o único lugar para fazer esta passagem completa. Cada execução de planejamento de roughcut posterior herda o contexto resultante em vez de reinterrogar a biblioteca.

Etapa 6 — Parar o auxiliar keep-awake

Se você iniciou um na Etapa 1, mate-o agora (ambas as plataformas):

kill $KEEPAWAKE_PID 2>/dev/null

Padrão de subagente paralelo (referência)

Usado nas etapas 3 e 4.

Responsabilidades do agente pai:

  • Ler library.yaml e settings.yaml uma vez para reunir todos os valores necessários para os subagentes.
  • Iniciar agentes Task passando todos os valores necessários inline no prompt.
  • Atualizar library.yaml sequencialmente à medida que os agentes concluem (via API Library — consulte AGENTS.md).
  • Tratar erros e novas tentativas.

Responsabilidades do agente filho:

  • Processar seu(s) clipe(s) atribuído(s) usando apenas as entradas passadas inline pelo pai.
  • Refinar um JSON de transcrição no local (refinamento) ou ler a folha de contato pré-gerada, extrair o diálogo da transcrição via script_extractor.rb e escrever o resumo em markdown em uma única chamada Write (analyze-video). (WhisperX não é mais um subagente — process_footage.rb transcripts o executa na Etapa 2a.)
  • Retornar uma resposta curta e estruturada com caminhos de arquivo.

O agent_prompt.md de cada skill documenta seu próprio contrato de IO — incluindo se o subagente lê ou escreve no library.yaml. (Spoiler: ele nunca escreve no library.yaml. Apenas o pai escreve, via API Library.)

Se o usuário solicitar um roughcut antes da conclusão da análise

Aviso: "Posso criar um roughcut agora, mas farei um trabalho melhor depois de analisar todas as filmagens. Continuar mesmo assim?" Se o usuário confirmar, prossiga. Caso contrário, aguarde a conclusão da análise.

Habilidades Relacionadas