Ablation-Lab/revisão-de-vídeo

Revisão de vídeo

A ferramenta transforma um arquivo de vídeo ou um projeto Remotion em um pacote de revisão que você pode ler: frames como PNGs, resultados de áudio, a linha de narração e o texto na tela (OCR) em cada frame, verificações automáticas e o que mudou desde a última revisão, tudo em report.md. Seu trabalho é executá-la e depois revisar o vídeo a partir do pacote.

1. Executar a ferramenta

Execute-a com este comando exato (funciona tanto no Bash quanto no PowerShell), usando o caminho do usuário entre aspas:

powershell -NoProfile -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/review-video.ps1" "<arquivo de vídeo ou pasta do projeto Remotion>" [opções]

• Arquivo de vídeo (MP4, MOV etc.): frames a cada 2 s, ao redor de cada mudança de cena e no final.
• Pasta do projeto Remotion: stills renderizados com npx remotion still (sem necessidade de renderização completa) e o áudio renderizado separadamente. Usa a primeira composição, a menos que -Composition <id> seja fornecido; a saída lista as demais. Requer que npm install já tenha sido executado no projeto.

Opções úteis (todas opcionais):

Opção	Uso
-Composition <id>	Remotion: qual composição renderizar.
-Frames 0,90,450	Remotion: renderizar apenas estes números de frame.
-Interval <s>	Segundos entre frames regulares (padrão 2). Use 4 ou mais para vídeos longos.
-Narration <arquivo>	Fonte da narração se não for encontrada automaticamente: .srt, .vtt, .csv, .md (tabela de gravação) ou voiceover.json.
-Project <pasta>	Pasta para procurar a narração quando o vídeo está fora do seu projeto.
-OutDir <pasta>	Onde escrever o pacote.
-CompareWith <pasta>	Comparar com uma pasta de revisão mais antiga (ex.: de um nome de arquivo anterior). Por padrão, cada execução compara com a última execução do mesmo vídeo.
-ChangesPdf	Também gerar um PDF apenas dos frames alterados, quando o usuário quer apenas as mudanças.
-KeyFramesPdf	Gerar key-frames.pdf na pasta de revisão: cerca de 15 a 20 frames, um frame totalmente construído por cena mais os frames sinalizados, rotulados com timestamp, cena e descoberta, abaixo de 10 MB. Se a pasta de revisão já contiver uma revisão completa, ele é construído a partir desses frames e nada mais muda; caso contrário, a revisão é executada primeiro. Adicione -NoPdf para pular a folha de contato completa.
-KeyFramesMaxMB <n>	Limite de tamanho para key-frames.pdf (padrão 10).
-WordsPerSecond <n>	Velocidade de leitura para a verificação de tempo de leitura (padrão 3).
-NumberWordsFrom <n>	Verifica palavras de números falados a partir deste valor (padrão 10).
-SafeMargins t,r,b,l	Margens da área segura para Shorts em 1080x1920 (padrão 288,192,672,48, valores cautelosos do Google).
-WordList <arquivo>	Palavras extras que a verificação ortográfica aceita.
-SceneThreshold 0.3	Para filmagens com câmera (o padrão 0.02 é adequado para slides com transições suaves).
-NoOcr	Pular as verificações de texto na tela.
-NoPdf	Pular o PDF quando o usuário quer apenas sua revisão.
-NoAudio	Remotion: pular a renderização de áudio.

Vídeos longos demoram um pouco: cerca de 2 minutos para 8 minutos de vídeo e cerca de 4 s por still do Remotion. Use um tempo limite de 10 minutos. As últimas linhas da saída fornecem os caminhos de report.md, da pasta de frames e dos PDFs, além de totais de uma linha para áudio, verificações de texto e alterações. O pacote vai para <nome-do-vídeo>-review\ ao lado do vídeo, ou para out\<composição>-review\ dentro de um projeto Remotion, a menos que -OutDir seja fornecido. Cada execução mantém a anterior em previous\.

Se a saída terminar com FAILED:, pare e informe ao usuário o motivo. Se o ffmpeg estiver faltando, a correção é winget install --id Gyan.FFmpeg -e e, em seguida, um novo terminal. Linhas começando com WARNING: também aparecem no topo do relatório. Repasse-as.

2. Revisão superficial ou completa

Executar a ferramenta é barato; abrir frames é o que consome o uso do usuário, porque cada frame aberto é uma imagem a ser lida. Uma revisão completa de um vídeo de 15 minutos, com seis subagentes Opus abrindo cada frame, já consumiu uma sessão de uso inteira. Portanto:

• Revisão superficial por padrão, a menos que o usuário peça uma revisão completa (com palavras como "revisão completa", "cada frame", "passar por tudo"). Em uma revisão superficial, trabalhe a partir de report.md: o resumo, as verificações, a linha do tempo da narração e o texto OCR de cada frame e suas sinalizações. Olhe os frames de mudança de cena (end of scene e scene change) por meio de suas linhas no relatório e abra uma imagem de frame apenas onde algo parecer errado: uma verificação sinalizada, uma linha de narração que não corresponde ao texto na tela, um frame alterado, um problema de áudio naquele momento ou texto OCR vazio ou distorcido onde deveria haver um slide. Diga ao final que foi uma revisão superficial e quantos frames você abriu.
• Sempre abra alguns frames reais, seja em uma revisão superficial, revisão apenas de texto ou veredito apenas da linha do tempo: cerca de um slide totalmente construído por cena (o frame end of scene, quando tudo já apareceu), ou 15 a 20 distribuídos pelo vídeo se não houver cenas claras. Eles mostram o estilo visual (layout, sobreposições, caixas transbordando, contraste, frames em branco) que o texto não pode mostrar. Para um vídeo longo, peça ao subagente Sonnet que está fazendo a revisão superficial para abri-los. Sempre diga ao final quantos frames foram abertos.
• Revisão completa apenas quando solicitada. Se o vídeo tiver mais de 5 minutos (veja Length e Frames no resumo de report.md), pare antes de abrir qualquer frame: informe ao usuário quantos frames existem e quantos você abriria, que uma revisão completa consumirá muito do uso deles e pergunte se deseja prosseguir, ofereça uma revisão superficial ou execute novamente com um -Interval maior para menos frames (-Interval 4 reduz os frames regulares pela metade). Aguarde a resposta.
• Ao fazer uma revisão completa: execute no máximo dois subagentes por vez e abra no máximo 100 frames no total, a menos que o usuário tenha fornecido outro número ou dito "cada frame, sem limite". Use Sonnet para os subagentes, a menos que o usuário peça Opus; se pedir, use-o, mas mencione uma vez que consome muito mais uso. Dê a cada subagente seu próprio intervalo de frames e as linhas correspondentes de report.md, e peça que ele retorne apenas os problemas encontrados.

Contagens aproximadas de frames: -Interval 2 (o padrão) fornece 30 frames regulares por minuto de vídeo, -Interval 4 fornece 15 e -Interval 10 fornece 6, mais até dois por mudança de cena.

Como os usuários pedem

O usuário diz	Faça
"Revisar C:\caminho\para\video.mp4"	Revisão superficial.
"Faça uma revisão completa de C:\caminho\para\video.mp4"	Revisão completa, até 100 frames (pergunte primeiro se tiver mais de 5 minutos).
"...revisão completa..., cada frame, sem limite"	Revisão completa de todos os frames. Pergunte primeiro se tiver mais de 5 minutos, dizendo que pode consumir uma sessão de uso inteira.
"...use subagentes Sonnet" / "...use Opus"	Esse modelo para os subagentes (Sonnet é o padrão de qualquer forma).
"Faça uma revisão superficial com Sonnet e escreva um arquivo de linha do tempo, depois me dê sua opinião geral a partir da linha do tempo"	Execute a ferramenta, depois peça a um subagente Sonnet para revisar superficialmente o pacote, abrir a amostra de frames-chave (um slide totalmente construído por cena) e escrever timeline.md na pasta de revisão: uma entrada por cena com seu intervalo de tempo, a narração resumida, o texto na tela resumido, a aparência visual e quaisquer problemas. Leia apenas esse arquivo (não abra frames você mesmo) e dê uma opinião geral: estrutura, ritmo, clareza, estilo visual e se os slides apoiam a narração. Diga quantos frames foram abertos.
"Crie o PDF de revisão para C:\caminho\para\video.mp4 para que eu possa anexá-lo a um chat"	Execute a ferramenta e forneça o caminho completo do PDF. Não revise nem abra frames a menos que solicitado.
"Crie um arquivo de linha do tempo e um PDF de frames-chave ... para que eu possa anexar ambos a um chat"	Execute a ferramenta com -KeyFramesPdf (veja "Compartilhamento com um chat de IA" abaixo) e escreva a linha do tempo como acima.

Compartilhamento com um chat de IA

Para um vídeo longo, não anexe o PDF da folha de contato completa (centenas de frames). Dê ao usuário duas coisas: um arquivo de texto da linha do tempo (timeline.md, como acima) e o PDF de frames-chave, criado com -KeyFramesPdf (adicione -NoPdf se o PDF completo não for desejado; em uma pasta que já tenha uma revisão, ele reutiliza os frames e é executado em segundos). Ele contém cerca de 15 a 20 frames: um frame totalmente construído por cena mais os frames sinalizados pela revisão, cada um rotulado com timestamp, nome da cena e a descoberta, abaixo de 10 MB, salvo como key-frames.pdf na pasta de revisão. Forneça seu caminho completo. Se a ferramenta não conseguir encontrar cenas claras (sem badge de rodapé numerado), ela distribui os frames uniformemente e informa isso nos rótulos. Ela não consegue detectar problemas visuais por si só, então, se você encontrou algum (uma sobreposição, um frame em branco), diga quais timestamps observar ao entregá-lo. O PDF completo é melhor para vídeos curtos, como Shorts, ou -ChangesPdf para apenas os frames alterados.

3. Revisar o vídeo

1. Leia report.md. Na ordem: avisos; mudanças desde a última revisão (apenas quando houve uma execução anterior: os frames alterados, com um link para o frame antigo e as palavras adicionadas e removidas); um resumo; resultados de áudio; a linha do tempo da narração (cada linha com seu início, fim e pontuação de correspondência); as verificações de texto na tela (ortografia, tempo de leitura, números, áreas seguras do Shorts); em seguida, uma tabela de cada frame com seu tempo, motivo pelo qual foi capturado, seu arquivo em frames/, a narração naquele momento, seu texto OCR e suas sinalizações. "(pausa; última linha)" significa que ninguém está falando e a linha mostrada foi a que acabou de ser dita.
2. Se o usuário perguntou o que mudou, ou uma seção de alterações está presente, comece pelos frames alterados: abra cada um ao lado de seu frame anterior e diga o que mudou.
3. Compare cada slide com sua linha de narração. Em uma revisão superficial, faça isso a partir do texto OCR no relatório e abra apenas os frames que parecerem errados (veja seção 2). Em uma revisão completa, abra os frames com a ferramenta de leitura, dentro do limite acordado: primeiro os frames marcados como end of scene (cada um é um slide finalizado pouco antes de mudar) e scene change (cada um é o próximo slide depois de estabilizado), depois cada frame sinalizado, depois os frames regulares onde a linha de narração muda ou algo se constrói na tela.
4. Trate as verificações automáticas como pistas, não como vereditos, e confirme cada uma na imagem do frame:
   • Ortografia: o OCR pode ler mal texto pequeno, fraco ou monoespaçado, e algumas palavras sinalizadas são intencionais (nomes, palavras ouvidas erroneamente mostradas de propósito). Relate apenas as que a imagem confirmar.
   • Tempo de leitura: slides sinalizados têm mais palavras novas do que cabem no tempo disponível, na velocidade de palavras por segundo fornecida. Diagramas narrados com muitos rótulos disparam isso facilmente; diga quais slides realmente precisam de mais tempo.
   • Números: um número falado não encontrado na tela é ou uma incompatibilidade real (o slide mostra um valor diferente) ou um número que o OCR perdeu, geralmente dígitos grandes de título. Verifique o frame.
   • Áreas seguras: texto dentro das margens de sobreposição do YouTube em vídeos verticais. As margens padrão são as mais cautelosas divulgadas, portanto, priorize texto perto das bordas inferior e direita.
5. Nos frames que você abrir, verifique também visualmente se há: texto na tela, números, nomes ou rótulos que divergem da narração, texto cortado ou sobreposto, baixo contraste, frames vazios ou pretos e conteúdo de placeholder ou remanescente; linhas de narração marcadas como "não encontrada"; e problemas de áudio no relatório (clipping, pico verdadeiro acima de -1 dBTP, cliques ou estalos, silêncios no meio do vídeo, volume muito distante de cerca de -14 LUFS).
6. Relate de forma breve: primeiro os problemas, cada um com o número do frame e o timestamp (por exemplo, #14 00:22.00) e o que está errado, depois os resultados de áudio e, em seguida, qualquer coisa que a ferramenta não pôde verificar. Diga claramente se tudo corresponde. Não altere o projeto a menos que o usuário peça; se uma palavra sinalizada estiver correta, você pode sugerir adicioná-la a review-words.txt na pasta do projeto.

Os PDFs

<nome>-review.pdf está na mesma pasta: uma página de rosto com os resultados de áudio, as verificações e quaisquer alterações, depois 6 a 9 frames por página, cada um rotulado com seu timestamp, quaisquer problemas encontrados (vermelho), a linha de narração e o texto OCR (azul, erros de ortografia sublinhados). É mantido abaixo de 20 MB. Com -ChangesPdf, também existe <nome>-changes.pdf apenas com os frames alterados. Quando o usuário quiser algo para anexar a um chat do Claude ou enviar para alguém, forneça o caminho completo. Use -MaxPdfMB <n> para um limite menor. key-frames.pdf (com -KeyFramesPdf) é o que deve ser anexado para vídeos longos.