Video Debugger

Extrae frames de screen recordings para que Claude pueda analizar visualmente animaciones, transiciones y comportamientos web frame-by-frame.

Fase 0: Verificar dependencias

which ffmpeg && ffmpeg -version | head -1
which ffprobe
which python3

Si falta alguna dependencia:

ffmpeg + ffprobe:
  macOS:   brew install ffmpeg
  Linux:   sudo apt install ffmpeg
  Windows: winget install ffmpeg  (o choco install ffmpeg)

python3:
  macOS:   incluido, o brew install python
  Linux:   sudo apt install python3
  Windows: winget install Python.Python.3

No continuar hasta que las 3 dependencias esten disponibles.

Dependencias opcionales (para --vision)

mlx-vlm (macOS Apple Silicon — default, no necesita app):
  pip3 install mlx-vlm

LM Studio (cualquier OS — fallback):
  Descargar desde https://lmstudio.ai, abrir al menos una vez para registrar CLI

Modelos de vision (descargar uno)

Recomendado — Qwen3-VL-30B-A3B (MLX, 17 GB, macOS Apple Silicon):
  Desde LM Studio UI buscar "Qwen3-VL-30B" o:
  huggingface-cli download mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit

Alternativa — Qwen3.5-35B-A3B (GGUF, 22 GB, cualquier OS via LM Studio):
  Desde LM Studio UI buscar "Qwen3.5-35B-A3B"

Nota: La version MLX del Qwen3.5 NO funciona con mlx-vlm (processor incompatible con transformers v5). Usar la version GGUF via LM Studio.

Fase 0.5: Detectar capacidad de vision local

bash scripts/analyze-frames.sh --check-vision

Resultados posibles:

• "available": true → modelo local disponible, usar --vision en Fase 4.5
• "available": false → sin modelo local, usar agente frame-analyzer (Sonnet) en Fase 4.5

Guardar resultado para decidir en Fase 4.5.

Fase 1: Recibir video y obtener metadata

El usuario provee el path al video. Ejecutar:

ffprobe -v quiet -print_format json -show_format -show_streams <video_path>

Extraer y mostrar resumen:

Video: 12.3s | 1920x1080 | 60fps | 8.2 MB

Datos relevantes: duration, width, height, r_frame_rate, tamaño del archivo.

Fase 2: Configurar extraccion

Preguntar al usuario que modo prefiere:

Modo	FPS	Uso
Rapido (default)	4 fps	Overview general, transiciones lentas
Detallado	10 fps	Frame-by-frame preciso, animaciones rapidas
Solo cambios	Auto (scene detect)	Detecta automaticamente donde hay cambios visuales
Tramo especifico	10 fps	Analizar solo un rango temporal (ej: "del segundo 2 al 5")

Formato default: JPEG q:v 2 (~150-300 KB/frame, texto legible).

Para comparativa de formatos y cuando usar cada uno: references/format-guide.md

Fase 3: Extraer frames

Output path

Guardar en ./debug-frames/{YYYY-MM-DD_HH-MM-SS}/:

OUTPUT_DIR="./debug-frames/$(date +%Y-%m-%d_%H-%M-%S)"
mkdir -p "$OUTPUT_DIR"

Agregar a .gitignore

grep -qxF 'debug-frames/' .gitignore 2>/dev/null || echo 'debug-frames/' >> .gitignore

Comandos segun modo

Ver references/ffmpeg-commands.md para los comandos exactos de cada modo.

Rapido:

ffmpeg -i <video> -vf "fps=4" -q:v 2 "$OUTPUT_DIR/frame_%04d.jpg"

Detallado:

ffmpeg -i <video> -vf "fps=10" -q:v 2 "$OUTPUT_DIR/frame_%04d.jpg"

Solo cambios:

ffmpeg -i <video> -vf "select=gt(scene\,0.3)" -vsync vfr -q:v 2 "$OUTPUT_DIR/scene_%04d.jpg"

Tramo especifico:

ffmpeg -i <video> -ss <inicio> -to <fin> -vf "fps=10" -q:v 2 "$OUTPUT_DIR/frame_%04d.jpg"

Mostrar cantidad de frames extraidos y tamaño total:

echo "Frames: $(ls "$OUTPUT_DIR"/*.jpg 2>/dev/null | wc -l)"
echo "Tamaño: $(du -sh "$OUTPUT_DIR" | cut -f1)"

Fase 4: Generar contact sheet

Siempre generar automaticamente despues de extraer frames.

Calcular grid

FRAME_COUNT=$(ls "$OUTPUT_DIR"/frame_*.jpg "$OUTPUT_DIR"/scene_*.jpg 2>/dev/null | wc -l)

Frames	Columnas	Escala
≤ 12	4	400:-1
13-30	5	320:-1
31-60	6	256:-1
> 60	8	200:-1

Generar con ffmpeg tile

ffmpeg -i <video> -vf "fps=<fps_usado>,scale=<escala>,tile=<cols>x0" -frames:v 1 -q:v 3 "$OUTPUT_DIR/contact_sheet.jpg"

Ejemplo para 24 frames a 4fps:

ffmpeg -i <video> -vf "fps=4,scale=320:-1,tile=5x0" -frames:v 1 -q:v 3 "$OUTPUT_DIR/contact_sheet.jpg"

Fase 4.5: Frame Diff & Vision Analysis

Despues de extraer frames, ofrecer análisis adicional con diff visual y modelo de vision local.

Diff visual (siempre disponible)

Correr el script de análisis que genera diffs con tblend y detecta cambios con scdet:

# Desde la raiz del repo llm-toolkit (o donde este el script)
bash scripts/analyze-frames.sh <video_path> "$OUTPUT_DIR" --threshold 8

Para GIFs (Gifox, etc): usar --threshold 12 o --threshold 14 porque el Bayer dithering genera ruido que confunde al scene detect.

Esto produce:

• diffs/ — frames de diferencia temporal (negro=sin cambio, brillante=movimiento)
• diff-motion.mp4 — video de movimiento amplificado
• diff-contact.jpg — contact sheet de los diffs
• diff-report.txt — manifest con frame index, timestamp, score, y rol (before/change/after)
• scores.txt — scores raw de scdet por frame

Leer diff-report.txt para identificar donde estan los cambios significativos antes de la fase de analisis visual.

Vision analysis (opcional)

Si el usuario quiere analisis semantico (descripcion de movimiento, deteccion de glitches), preguntar si quiere usar un modelo de vision local:

# macOS Apple Silicon (default — usa mlx-vlm, no necesita LM Studio)
bash scripts/analyze-frames.sh <video_path> "$OUTPUT_DIR" --vision --threshold 8

# Cualquier OS (fallback — requiere LM Studio corriendo)
bash scripts/analyze-frames.sh <video_path> "$OUTPUT_DIR" --vision --backend lmstudio --threshold 8

Backend mlx (default, macOS Apple Silicon):

1. Corre mlx-vlm directo con el modelo MLX (no necesita servidor ni app)
2. Default: Qwen3-VL-30B-A3B (17 GB, MoE, ~23s para 14 frames)
3. Auto-detecta el modelo en ~/.lmstudio/models/

Backend lmstudio (fallback, cualquier OS):

1. Levanta LM Studio server si no esta corriendo
2. Carga el modelo GGUF (Qwen3.5-35B-A3B por default, auto-descarga en 2 min)
3. Descarga el modelo al terminar

Ambos backends:

• Envian frames seleccionados al modelo (todos si ≤30, o ventanas ±3 alrededor de cada cambio)
• Generan vision-analysis.txt con descripcion de movimiento, glitches, transiciones

Importante: Si un modelo local genero vision-analysis.txt, leer ese archivo como texto (no tiene sentido re-analizar las imagenes). Si no hay modelo local, preferir el agente frame-analyzer (Sonnet) — hace el mismo analisis visual pero cuesta menos que cargar frames en Opus. Si por alguna razon se necesita cargar frames directamente en contexto, tambien funciona.

Opciones adicionales:

• --backend mlx|lmstudio — backend de vision (default: mlx)
• --model "path/o/key" — path MLX o key LM Studio (auto-detectado si no se especifica)
• --context 5 — mas frames de contexto alrededor de cada cambio (default: 3)
• --max-frames 15 — umbral para modo video corto vs ventanas (default: 30)
• --keep-model — no descargar el modelo al terminar (lmstudio only)
• --timeout 600 — timeout mas largo para modelos lentos (lmstudio only, default: 300s)

Sin modelo de vision local (fallback con agente Sonnet)

Si --check-vision dio available: false, correr solo el diff (sin --vision):

bash scripts/analyze-frames.sh <video_path> "$OUTPUT_DIR" --threshold 8

Luego lanzar el agente frame-analyzer con este prompt:

Analiza los frames en {OUTPUT_DIR}. Lee diff-report.txt para identificar frames de cambio.
Lee el contact sheet y los frames individuales de las zonas de cambio.
Diagnostica bugs visuales, layout shifts, y problemas de animacion.

El agente (Sonnet con vision multimodal) devuelve analisis textual equivalente a vision-analysis.txt.

Para referencia de comandos de diff: references/diff-tools.md

Fase 5: Analisis

1. Si hay diff-report.txt: leerlo primero → da los frames con cambios significativos y sus scores
2. Si hay vision-analysis.txt: leerlo → da descripcion semantica del modelo de vision local (NO cargar imagenes, solo el texto)
3. Leer contact sheet → overview rapido de toda la secuencia
4. Identificar zona problematica → usar diff-report + vision-analysis + contact sheet para triangular
5. Leer frames individuales de la zona problematica en secuencia (los diff frames en diffs/ muestran que pixels cambiaron)
6. Diagnosticar con referencia a frame numbers especificos:
   • Timing incorrecto (transicion demasiado rapida/lenta)
   • Easing problems (saltos, rebotes no deseados)
   • Layout shifts (elementos que se mueven inesperadamente)
   • Z-index issues (capas superpuestas mal)
   • Opacity/visibility glitches (parpadeos)
   • Reflow/repaint artifacts
7. Reportar hallazgos con: frame number, timestamp aproximado, descripcion del problema, causa probable

Troubleshooting

Problema	Causa	Solucion
"No such file or directory"	Path incorrecto o con espacios	Usar comillas dobles en el path
Frames en negro	Video con codec no soportado	ffmpeg -i <video> para ver codec, instalar codec faltante
Demasiados frames	FPS muy alto para video largo	Usar modo "Solo cambios" o "Tramo especifico"
Frames borrosos	Compresion del video fuente	No es problema de ffmpeg, es la calidad del recording
Contact sheet cortado	Demasiados frames para tile	Reducir fps o usar tramo especifico
ffmpeg slow/colgado	Video muy grande (>1GB)	Agregar -threads 4 al comando
Muchos false positives en scene detect	GIF con Bayer dithering	Subir --threshold a 12-14
--check-vision dice unavailable	No hay mlx-vlm ni LM Studio	Se usa agente Sonnet automaticamente; opcionalmente instalar mlx-vlm (macOS) o LM Studio (cualquier OS)
Vision analysis falla (mlx)	mlx-vlm no instalado o modelo no encontrado	pip3 install mlx-vlm, verificar modelo en ~/.lmstudio/models/
Vision analysis falla (lmstudio)	LM Studio no corriendo o modelo sin vision	Verificar lms server status y que el modelo tenga capability de vision
mlx-vlm no soportado	No es macOS Apple Silicon	Usar --backend lmstudio
Qwen3.5 MLX no funciona con mlx-vlm	Processor incompatible con transformers v5	Usar version GGUF via --backend lmstudio
Vision analysis lenta	Modelo grande + muchos frames	Usar --max-frames 15 o reducir frames con --context 1