Video Understand: quadros e transcrição local para revisar vídeos

ANÁLISE EDITORIAL

Video Understand é uma Skill do OpenMontage para decompor um arquivo de vídeo local em metadados, quadros representativos e, quando o Whisper está instalado, uma transcrição segmentada. O objetivo não é editar nem gerar vídeo. É produzir uma visão estruturada que um agente e uma pessoa possam revisar antes de resumir uma gravação, investigar uma cena ou verificar uma entrega audiovisual.

O fluxo usa ffprobe para duração e resolução, ffmpeg para extrair imagens e o pacote opcional openai-whisper para transformar o áudio em texto. Isso reduz a dependência de uma API de vídeo, mas não elimina riscos. Os arquivos continuam sensíveis, os quadros ocupam disco, o primeiro uso do Whisper pode baixar um modelo e a análise final ainda pode perder contexto entre os frames.

O que esta Skill faz de verdade

O script understand_video.py recebe um caminho de arquivo e oferece três formas de amostragem. scene procura mudanças de cena com o filtro select do FFmpeg e limiar 0,3. keyframe coleta I-frames do arquivo codificado. interval distribui quadros ao longo da duração. O limite padrão é 20 imagens.

Quando nenhuma mudança é encontrada no modo scene, o código tenta interval. Depois, reduz o conjunto ao máximo solicitado, associa timestamps, extrai áudio mono de 16 kHz para um WAV temporário e tenta transcrever com Whisper. A saída reúne duração, resolução, modo efetivamente usado, caminhos absolutos dos JPEGs, segmentos com início e fim e texto completo.

Isso é amostragem, não compreensão automática garantida. Uma ação rápida entre dois quadros pode desaparecer. I-frames refletem decisões de codificação, não necessariamente mudanças semânticas. A transcrição pode errar nomes, sotaques, ruído, sobreposição de vozes e idioma. O agente precisa abrir as imagens, confrontar texto e vídeo e declarar lacunas.

Para quem serve

Serve a editores, equipes de conteúdo, suporte, treinamento, documentação, pesquisa e qualidade que já possuem acesso legítimo ao arquivo. Pode ajudar a preparar índice de uma aula, localizar mudanças de tela em uma demonstração, revisar se um vídeo exportado contém as cenas esperadas ou criar um primeiro mapa antes de uma análise humana mais detalhada.

Também é útil quando uma política impede enviar mídia confidencial a um serviço externo. Nesse caso, o processamento local oferece uma alternativa técnica, desde que o computador, os modelos, as pastas e os backups estejam sob controle. A Skill não anonimiza rostos, vozes, nomes ou telas. Local não significa automaticamente seguro.

Não é adequada como única evidência para investigação, compliance, acessibilidade, moderação ou decisão sobre pessoas. Não substitui legenda revisada, audiodescrição, inspeção quadro a quadro, consentimento, cadeia de custódia ou análise especializada.

Compatibilidade e pré-requisitos

O SKILL.md fixado exige ffmpeg e ffprobe. Python 3 executa o script. Whisper é opcional e só é necessário para transcrição. O documento upstream mostra brew install ffmpeg, que atende macOS com Homebrew; Windows e Linux devem seguir a rota aprovada para seu sistema e confirmar que os dois binários aparecem no PATH.

• Python 3 compatível com as dependências escolhidas.
• FFmpeg e ffprobe instalados e executáveis no terminal.
• Espaço para JPEGs, WAV temporário, ambiente Python e modelo Whisper.
• Cópia autorizada do vídeo em diretório controlado.
• Opcionalmente, openai-whisper e suas dependências.
• Um agente capaz de ler o JSON e abrir as imagens pelos caminhos retornados.

A documentação oficial do Whisper lista instalação, modelos e requisitos. Verifique a versão atual antes de instalar. Tamanho do modelo, memória, CPU ou GPU e duração do vídeo alteram tempo e consumo. Esta curadoria não publica estimativa de desempenho porque não fez benchmark.

Instalação recomendada

O ZIP do Bastidores é um espelho documental com quatro arquivos: SKILL.md, references/output-format.md, LICENSE e ORIGEM.md. Ele não contém understand_video.py, FFmpeg, ffprobe, Whisper, modelos, dependências, vídeos, imagens extraídas, áudio ou transcrições. Para executar, obtenha o script no diretório oficial fixado e preserve a licença.

git clone https://github.com/calesthio/OpenMontage.git
cd OpenMontage
git checkout cd9f3c1f03368be87b140af494914b8ee4e3c7a4
python -m venv .venv
# Ative o ambiente conforme o sistema.
# Leia SKILL.md, output-format.md e understand_video.py.
ffmpeg -version
ffprobe -version

Ambiente virtual ajuda a isolar pacotes. A documentação do Python sobre venv explica criação e ativação. Instalação por pip consulta a rede e executa código distribuído. Faça isso somente após revisar origem, lock ou versões aprovadas e política da máquina.

Configuração antes do primeiro uso

Comece sem transcrição. Copie uma amostra pública ou sintética para uma pasta vazia. Não aponte diretamente para um arquivo único e valioso. O script cria {nome}_frames ao lado do vídeo e usa nomes como frame_0001.jpg. O FFmpeg recebe -y, portanto arquivos com esses nomes podem ser sobrescritos.

Há um limite importante no código auditado: a pasta de quadros é reutilizada e não é limpa antes de uma nova execução. Se uma segunda rodada produzir menos imagens, JPEGs antigos podem permanecer e entrar na coleta. Use uma pasta nova por tentativa ou remova somente a pasta exata depois de confirmar seu caminho e preservar o que precisa ser auditado.

Defina modo, máximo de quadros, transcrição e destino do JSON. Para vídeos com cortes claros, scene é um início razoável. Para uma amostra previsível, escolha interval. keyframe é útil para inspecionar a estrutura codificada, mas não promete representar cada mudança visual importante.

Primeiro uso seguro

python .agents/skills/video-understand/scripts/understand_video.py \
  amostra.mp4 --no-transcribe -m interval --max-frames 6 \
  -o resultado.json

Abra resultado.json e confira nome, duração, resolução, modo e quantidade. Depois, abra cada JPEG e compare os timestamps com o vídeo original. Só então habilite transcrição em uma cópia autorizada. Se o caminho da Skill foi instalado em outro diretório, ajuste o comando para o local real, sem inventar uma estrutura.

Nesta curadoria, um teste local descartável foi executado no Windows com Python 3.12, FFmpeg 8.1.1 e um vídeo sintético de 2 segundos, 320 por 180 pixels. O modo interval, sem Whisper, retornou quatro quadros, timestamps de 0 a 1,5 segundo e JSON coerente. Isso confirma apenas esse caminho estreito. Não comprova transcrição, desempenho, detecção de cena em mídia real ou compatibilidade universal.

Como o fluxo deve funcionar

1. Confirmar autorização, finalidade, retenção e pasta de trabalho.
2. Copiar uma amostra para um diretório vazio e controlado.
3. Registrar hash do original quando integridade for relevante.
4. Executar ffprobe e verificar duração e resolução.
5. Escolher scene, keyframe ou interval conforme a pergunta.
6. Definir --max-frames para limitar disco e revisão.
7. Rodar primeiro com --no-transcribe.
8. Abrir todos os quadros retornados e verificar timestamps.
9. Habilitar Whisper somente após aprovar dependências e modelo.
10. Comparar transcrição, áudio e imagem, marcando incertezas.
11. Guardar JSON e evidências somente pelo período necessário.
12. Repetir em pasta limpa quando mudar modo ou parâmetros.

Os filtros e opções devem ser confrontados com a referência oficial de filtros do FFmpeg. Metadados vêm do ffprobe, cuja documentação oficial descreve o formato e as opções. Se a versão instalada divergir, confira o help local antes de alterar comandos.

Resultado esperado

A estrutura documentada em output-format.md traz o nome do vídeo, duração em segundos, largura, altura, modo, lista de frames, quantidade, segmentos da transcrição, texto completo e uma nota para abrir as imagens.

Um resultado bom permite reproduzir a amostragem e localizar cada evidência. Ele não deve esconder que a transcrição ficou vazia, que o modo caiu de scene para interval ou que certos quadros parecem duplicados. Se a pergunta exige precisão temporal fina, aumente a amostragem ou volte ao vídeo original.

Permissões, privacidade e riscos

O script lê o vídeo, executa subprocessos locais, cria diretório, grava JPEGs, cria WAV temporário, pode gravar JSON e pode solicitar instalação do Whisper em sessão interativa. O carregamento do modelo pode consultar a internet na primeira vez. Não há chave de API exigida pelo fluxo auditado, mas isso não torna dependências e downloads automaticamente confiáveis.

Quadros podem revelar telas, documentos, rostos, placas ou mensagens. Áudio e transcrição podem conter biometria vocal, dados pessoais, segredos e informação contratual. Restrinja acesso, evite pastas sincronizadas sem necessidade, criptografe quando exigido e descarte derivados conforme a política. Não envie a saída ao agente errado só porque a extração ocorreu localmente.

A AGPL-3.0 permite redistribuição com condições. O texto da licença acompanha o ZIP. Quem modificar ou redistribuir material coberto precisa avaliar as obrigações aplicáveis. Esta página não substitui orientação jurídica.

Erros comuns

Executar na pasta de quadros antiga. Imagens remanescentes podem contaminar a nova saída. Use diretório limpo.

Tratar I-frame como cena importante. Keyframes pertencem à codificação. Compare com scene ou interval.

Acreditar que 20 quadros cobrem todo o vídeo. A cobertura depende de duração, movimento e pergunta.

Chamar modo local de isolamento total. Pip e modelos podem acessar a rede; pastas podem sincronizar.

Instalar Whisper no Python global. Prefira ambiente virtual e versões revisadas.

Ignorar vídeo sem áudio. O script pode retornar transcrição vazia. Isso não é prova de silêncio sem conferir a faixa.

Aceitar nomes transcritos sem revisão. Confronte termos próprios, números e trechos críticos com o áudio.

Apagar temporários por caminho amplo. Resolva a pasta exata e preserve o original.

Versão, licença e origem verificadas

A API oficial do GitHub foi consultada em 05/09/2026. O repositório calesthio/OpenMontage registrava 56.217 estrelas, estava público, não arquivado e declarava licença AGPL-3.0. Estrelas mostram atenção ao repositório inteiro, não adoção desta Skill, precisão da transcrição ou qualidade da amostragem.

A curadoria fixou o commit cd9f3c1f03368be87b140af494914b8ee4e3c7a4, que ainda era o HEAD de main na consulta. O último commit específico retornado para o SKILL.md foi a3e735cc7abb7f5c703944d763bd1d847ead544b. Não há release publicada nem versão própria declarada para Video Understand.

O ZIP local contém quatro arquivos textuais, tem 16.162 bytes e SHA-256 e663fb39efa27efa4c8f7ce80287d9dcc8f5b5cf9277479496c46d7529454203. O script Python foi omitido conforme a política do catálogo. Para execução, obtenha-o no repositório oficial fixado.

Checklist antes de automatizar

• Fixe repositório, commit, Skill, script e licença.
• Confirme autorização para o vídeo, áudio, pessoas e telas presentes.
• Use cópia de teste em pasta vazia e controlada.
• Valide Python, ffmpeg e ffprobe pelo help local.
• Comece com --no-transcribe e limite de quadros pequeno.
• Abra cada frame e compare o timestamp com o vídeo.
• Instale Whisper e modelo somente após revisão e aprovação.
• Não misture quadros antigos com uma nova execução.
• Marque lacunas, quedas de modo e transcrição ausente.
• Não trate amostragem nem transcrição automática como prova completa.
• Proteja JSON, JPEGs, WAV, cache de modelos e mídia original.
• Autorize separadamente qualquer envio externo, edição ou publicação.

Fontes primárias

• Repositório oficial do OpenMontage.
• Commit auditado do repositório.
• Diretório oficial da Skill no commit fixado.
• SKILL.md da Video Understand.
• Script Python auditado, não incluído no ZIP.
• Formato de saída documentado.
• Guia oficial de arquitetura e uso de Skills do OpenMontage.
• Licença GNU AGPL-3.0.
• Índice oficial da documentação do FFmpeg.
• Filtros oficiais do FFmpeg.
• Documentação oficial do ffprobe.
• Repositório oficial do OpenAI Whisper.
• Ambientes virtuais na documentação oficial do Python.