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
transcriptno library.yaml, etc.).
Pré-requisitos
- A configuração da biblioteca está completa (
library.yamlexiste, o esquema está atualizado — execute as migrações de AGENTS.md se não estiver). - Leia
libraries/settings.yamldiretamente para obterwhisper_model. Para campos da biblioteca, leia o snapshot viaruby lib/buttercut/library.rb <nome> summarye 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 emlibraries/<biblioteca>/transcripts/user_contextefootage_summary— valores atuais deruby 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 resumocontact_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 viascript_extractor.rbsummary_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çãosummaries/summary_<clipe>.mdpara 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_summaryeuser_contextviaruby lib/buttercut/library.rb <nome> update_metadata footage_summary "..."(e o mesmo comuser_context)- arquivos individuais
summary_*.mdquando 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.yamlesettings.yamluma 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.rbe escrever o resumo em markdown em uma única chamada Write (analyze-video). (WhisperX não é mais um subagente —process_footage.rb transcriptso 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.