Agent-Skills.md

Agent Skills: Video Debugger

|

UncategorizedID: testacode/llm-toolkit/video-debugger

Repository

testacode/llm-toolkit
testacodeLicense: Apache-2.0

Install this agent skill to your local

pnpm dlx add-skill https://github.com/testacode/llm-toolkit/tree/HEAD/skills/video-debugger

Skill Files

Browse the full folder contents for video-debugger.

Download Skill

Loading file tree…

skills/video-debugger/SKILL.md

Skill Metadata

Name
video-debugger
Description
|

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 |