video-analysis

Análisis de video — lo que se ve, lo que se dice

No tienes entrada directa de video o audio. Lees imágenes extraídas del video y una transcripción de su audio. Todo lo que sigue convierte un video en esas dos cosas y luego te dice cómo leerlas sin exagerar.

Dónde va todo — regla estricta del propietario

Todo el material extraído va a una carpeta de trabajo junto al video: <carpeta del video>\<nombre del video>.analysis\ — nunca en un bloc de notas, un directorio temporal o el proyecto. El propietario la elimina cuando termina el trabajo con ese video, para recuperar espacio en disco. Nunca la elimines tú mismo. Si te piden limpiar, usa la habilidad trash en esa carpeta exacta (Papelera de reciclaje, nunca rm). Tu análisis escrito (el entregable) pertenece donde el proyecto lo requiera, no dentro de la carpeta .analysis, para que al vaciar la carpeta no se pierda nada de valor.

1. Herramientas (una vez por máquina)

python ~/.claude/skills/video-analysis/scripts/setup_tools.py --check   # verificar
python ~/.claude/skills/video-analysis/scripts/setup_tools.py           # instalar lo que falte

Instala con pip --user: imageio-ffmpeg (un binario ffmpeg empaquetado — sin ffmpeg del sistema, sin administrador, sin winget/choco), Pillow, numpy, faster-whisper, y almacena en caché el modelo Whisper small (el único acceso a red; después todo es sin conexión). Salida 0 = LISTO.

Autocomprobación (video sintético, 9 verificaciones, --full agrega Whisper): python ~/.claude/skills/video-analysis/scripts/selftest.py

2. Extraer

python ~/.claude/skills/video-analysis/scripts/extract_video.py "<ruta del video>" --language es

Ejecútalo en segundo plano para videos de más de unos minutos: la transcripción corre ~5 veces más rápido que el tiempo real en CPU (un video de 15 minutos toma ~3 minutos). Opciones: --interval 5 (segundos entre fotogramas; usa 2 para pantallas que cambian rápido, 10-15 para cabezas parlantes), --model small (medium = mejor, 3 veces más lento), --skip-frames, --skip-transcript, --at HH:MM:SS[.mmm] (repetible, fotograma a resolución completa en un instante exacto — se usa en el paso 3d).

Produce en <video>.analysis\: frames\ (cada intervalo), sheets\ (hojas de contacto 3x3, cada imagen con marca mm:ss en amarillo), keyframes.txt + keysheets\ (solo los fotogramas que cambiaron visiblemente — los cambios de diapositiva/pantalla), audio.wav, transcript.txt ([mm:ss] texto) + transcript.json, at\, manifest.json. Volver a ejecutar reanuda y omite etapas ya terminadas; parámetros cambiados o un video diferente son rechazados (código de salida 3) en lugar de mezclar salidas. Salida 1 = fallo de procesamiento, 2 = entrada incorrecta.

3. Leer — en este orden

a. Primero la transcripción completa (transcript.txt). En cursos y demostraciones, el contenido decisivo (números, reglas, excepciones, el método real) suele estar en la voz, no en la pantalla. b. Las hojas de fotogramas clave (keysheets\) para ver cada diapositiva/pantalla distinta una vez. c. Las hojas de contacto (sheets\) — todas, en orden, para seguir lo que se mueve entre fotogramas clave (cursor, dibujos, gráficos que se actualizan). d. Acercar donde apunta el habla: cuando el orador dice "aquí", "esta vela", "mira…", vuelve a ejecutar con --at <marca de tiempo> y las mismas opciones que la primera ejecución (de lo contrario la verificación del manifiesto lo rechaza con código 3), luego lee ese fotograma a resolución completa. Las hojas son de 640 px por celda — demasiado pequeñas para etiquetas de gráficos o texto pequeño. e. Escribe el análisis (paso 4).

4. Informe — mantén tres cosas separadas

Para cada pasaje, cita marcas de tiempo y etiqueta cada afirmación como uno de:

• EN PANTALLA — lo que realmente muestra una imagen (texto de diapositiva, gráfico, anotación, IU).
• DICHO — lo que afirma la voz (cita o paráfrasis cercana, con [mm:ss]).
• INFERENCIA — tu interpretación que vincula ambos. Nunca la presentes como visto o dicho.

Incluye siempre:

• las brechas entre lo escrito y lo dicho (por ejemplo, una diapositiva dice una cosa y la voz añade la regla que realmente importa, o la contradice);
• lo que solo se muestra una vez (un único ejemplo demostrado es una ilustración, no evidencia);
• límites: los fotogramas se muestrean cada N s y pueden perder eventos breves; la marca de un fotograma es su índice × intervalo, por lo que es aproximada (± medio intervalo, más en grabaciones de velocidad de fotogramas variable); la deduplicación de fotogramas clave puede ocultar pequeñas ediciones; Whisper escribe mal nombres y jerga (verifica con las imágenes); no hay lectura fiable de tono, emoción, música, identidad del orador o movimiento.

5. Después

Informa al usuario la ruta de la carpeta de trabajo y su tamaño (impreso al final de la extracción). Déjala en su lugar hasta que diga que el trabajo con el video ha terminado; luego elimínala con la habilidad trash.

Errores conocidos (ya manejados por los scripts)

• faster_whisper model.transcribe("<ruta>") lanza TypeError: open() got an unexpected keyword argument 'metadata_errors' con PyAV reciente. El script extrae WAV de 16 kHz mono PCM16 con ffmpeg y pasa un array float32 en su lugar.
• imageio-ffmpeg incluye ffmpeg pero no ffprobe: la duración y la presencia de audio se leen desde el propio banner de ffmpeg.
• La detección de escenas mediante select='gt(scene,N)' + showinfo no imprime nada bajo -loglevel error; los fotogramas clave se calculan usando diferencias de miniaturas en su lugar.