video-understand
Comprende el contenido de vídeos de forma local usando ffmpeg para la extracción de fotogramas y Whisper para la transcripción. Completamente fuera de línea, sin necesidad de claves API.
Prerrequisitos
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 (I-frames)
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 el número de 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
| Banderín | Descripción |
|---|---|
video | Archivo de vídeo de entrada (posicional, obligatorio) |
-m, --mode | Modo de extracción: scene (por defecto), keyframe, interval |
--max-frames | Número 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 resultante 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 vídeos, contenido variado |
keyframe | Extrae I-frames (fotogramas clave del códec) | Vídeos codificados con colocación natural de fotogramas clave |
interval | Fotogramas espaciados uniformemente según la 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": "/ruta/absoluta/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "Hola y bienvenidos..."}
],
"text": "Transcripción completa...",
"note": "Usa la herramienta Read para ver las imágenes de los fotogramas y comprender visualmente el contenido."
}
Usa la herramienta Read en las rutas de los fotogramas para inspeccionar visualmente las imágenes extraídas.
Referencias
references/output-format.md-- Documentación del esquema completo de la salida JSON