video-understand
Comprende el contenido de videos localmente usando ffmpeg para extracción de fotogramas y Whisper para transcripción. Completamente fuera de línea, no se requieren claves API.
Requisitos previos
ffmpeg+ffprobe(obligatorio):brew install ffmpegopenai-whisper(opcional, para transcripción):pip install openai-whisper
Comandos
# Detección de escenas + transcripción (por defecto)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# Extracción de fotogramas clave
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# Extracción a intervalos regulares
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# Limitar fotogramas extraídos
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# Usar un modelo Whisper más grande
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# Solo fotogramas, omitir transcripción
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# Modo silencioso (solo JSON, sin progreso)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# Salida a archivo
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json
Opciones de CLI
| Banderas | Descripción |
|---|---|
video | Archivo de video de entrada (posicional, obligatorio) |
-m, --mode | Modo de extracción: scene (por defecto), keyframe, interval |
--max-frames | Máximo de fotogramas a conservar (por defecto: 20) |
--whisper-model | Tamaño del modelo Whisper: tiny, base, small, medium, large (por defecto: base) |
--no-transcribe | Omitir transcripción de audio, extraer solo fotogramas |
-o, --output | Escribir el JSON de resultado en un archivo en lugar de stdout |
-q, --quiet | Suprimir mensajes de progreso, mostrar solo JSON |
Modos de extracción
| Modo | Cómo funciona | Mejor para |
|---|---|---|
scene | Detecta cambios de escena mediante ffmpeg select='gt(scene,0.3)' | La mayoría de videos, contenido variado |
keyframe | Extrae fotogramas I (fotogramas clave del códec) | Video codificado con ubicación natural de fotogramas clave |
interval | Fotogramas espaciados uniformemente según duración y max-frames | Muestreo fijo, salida predecible |
Si el modo scene no detecta cambios de escena, automáticamente recurre al modo interval.
Salida
El script genera JSON en stdout (o en un archivo con -o). Consulta references/output-format.md para el esquema completo.
{
"video": "video.mp4",
"duration": 18.076,
"resolution": {"width": 1224, "height": 1080},
"mode": "scene",
"frames": [
{"path": "/abs/path/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "Hello and welcome..."}
],
"text": "Transcripción completa...",
"note": "Usa la herramienta Read para ver las imágenes de los fotogramas y obtener comprensión visual."
}
Usa la herramienta Read en las rutas de las imágenes de los fotogramas para inspeccionar visualmente los fotogramas extraídos.
Referencias
references/output-format.md-- Documentación completa del esquema de salida JSON