video-understand
Compreenda o conteúdo de vídeos localmente usando ffmpeg para extração de quadros e Whisper para transcrição. Totalmente offline, sem necessidade de chaves de API.
Pré-requisitos
ffmpeg+ffprobe(obrigatório):brew install ffmpegopenai-whisper(opcional, para transcrição):pip install openai-whisper
Comandos
# Detecção de cena + transcrever (padrão)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# Extração de quadro-chave
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# Extração em intervalo regular
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# Limitar quadros extraídos
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# Usar um modelo Whisper maior
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# Apenas quadros, pular transcrição
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# Modo silencioso (apenas JSON, sem progresso)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# Saída para arquivo
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o resultado.json
Opções de CLI
| Flag | Descrição |
|---|---|
video | Arquivo de vídeo de entrada (posicional, obrigatório) |
-m, --mode | Modo de extração: scene (padrão), keyframe, interval |
--max-frames | Número máximo de quadros a manter (padrão: 20) |
--whisper-model | Tamanho do modelo Whisper: tiny, base, small, medium, large (padrão: base) |
--no-transcribe | Pular transcrição de áudio, extrair apenas quadros |
-o, --output | Escrever o JSON de resultado em um arquivo em vez de stdout |
-q, --quiet | Suprimir mensagens de progresso, saída apenas JSON |
Modos de Extração
| Modo | Como funciona | Melhor para |
|---|---|---|
scene | Detecta mudanças de cena via ffmpeg select='gt(scene,0.3)' | Maioria dos vídeos, conteúdo variado |
keyframe | Extrai quadros I (quadros-chave do codec) | Vídeo codificado com posicionamento natural de quadros-chave |
interval | Quadros espaçados uniformemente com base na duração e max-frames | Amostragem fixa, saída previsível |
Se o modo scene não detectar mudanças de cena, ele automaticamente cai para o modo interval.
Saída
O script gera JSON para stdout (ou arquivo com -o). Consulte references/output-format.md para o esquema completo.
{
"video": "video.mp4",
"duration": 18.076,
"resolution": {"width": 1224, "height": 1080},
"mode": "scene",
"frames": [
{"path": "/caminho/absoluto/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "Olá e bem-vindo..."}
],
"text": "Transcrição completa...",
"note": "Use a ferramenta Read para visualizar as imagens dos quadros para compreensão visual."
}
Use a ferramenta Read nos caminhos das imagens dos quadros para inspecionar visualmente os quadros extraídos.
Referências
references/output-format.md-- Documentação completa do esquema de saída JSON