vidlizer

Extrae JSON estructurado de videos, imágenes y PDFs usando LLMs locales (Ollama, LM Studio, oMLX) o mediante OpenRouter. Funciona completamente sin conexión.

GitHub

Prueba este MCPPatrocinado

Documentación

vidlizer

Apúntalo a un video, imagen o PDF. Obtén JSON estructurado — escena por escena.

demo

vidlizer extrae fotogramas de cualquier video, imagen o PDF usando ffmpeg, los envía a un LLM de visión y devuelve un array flow — una entrada por escena. Cada entrada te dice qué sucedió, quién estaba en pantalla, qué texto era visible y qué cambió. Si el video tiene audio, lo transcribe con Apple MLX Whisper y fusiona el habla en cada paso.

Se ejecuta completamente local mediante Ollama o cualquier servidor compatible con OpenAI (LM Studio, vLLM, oMLX) — sin clave API, sin que los datos salgan de tu máquina. O conecta OpenRouter para modelos en la nube. vidlizer setup detecta lo que tienes instalado y escribe tu configuración en menos de un minuto.

vidlizer demo.mp4
vidlizer "https://youtube.com/watch?v=..."
vidlizer screenshot.png
vidlizer document.pdf

✨ Características

Cualquier entrada — video local, imagen (jpg/png/webp/…), PDF o URL (YouTube, Loom, Vimeo, Twitter)
4 proveedores — Ollama (totalmente offline), LM Studio (puerto 1234), oMLX (Apple Silicon, puerto 8000), OpenRouter (nube) — auto-detectados en ese orden
Respaldo entre proveedores — si el modelo principal falla → cambia automáticamente de proveedor (p. ej. oMLX → OpenRouter)
Reparación de JSON — la salida malformada del modelo se reenvía al modelo para corregirla antes de omitirla; se recupera de JSON parcial
Protección de modelos gratuitos — los modelos :free de OpenRouter fuerzan automáticamente concurrency=1 para mantenerse dentro de los límites de tasa
3 formatos de salida — --format json (predeterminado), summary (texto plano por fase), markdown (documento paso por sección)
Seguimiento de uso — --stats muestra el desglose de tokens y costos por modelo en todas las ejecuciones; herramienta MCP get_usage_stats()
Transcripción automática — detecta audio, transcribe con Apple MLX Whisper (Neural Engine), fusiona el habla en cada paso del flujo
Deduplicación perceptual — elimina fotogramas casi duplicados antes de enviarlos (ahorra tokens)
analyze_moment — banderas --start/--end para enfocarse en un rango de tiempo
Caché en memoria — las ejecuciones repetidas del mismo archivo omiten la llamada a la API
Protección de costos — aborta si el gasto supera MAX_COST_USD (predeterminado $1.00)
Progreso en vivo — indicador de transmisión Rich muestra el tiempo transcurrido y el recuento de tokens por lote
Servidor MCP — úsalo desde Claude Code, Cursor, Claude Desktop; proveedor/modelo bloqueados mediante variables de entorno; el resultado incluye model_used + provider_used
Autoinstalación — si falta ffmpeg, se instala con brew; mlx-whisper incluido en la instalación predeterminada (macOS)
doctor --fix — asistente de reparación interactivo: instala ffmpeg/Ollama/LM Studio faltantes mediante Homebrew, vuelve a ejecutar vidlizer setup para .env, actualiza mlx-whisper
mcp-setup — asistente de configuración MCP de un comando: detecta vidlizer-mcp, lee .env, escribe la configuración del editor o muestra una línea única claude mcp add-json
Nativo para Mac — diálogo de selector de archivos, transcripción Apple MLX, maneja nombres de archivo Unicode de macOS (p. ej. "11:26 AM")

📦 Requisitos

macOS (Apple Silicon recomendado para velocidad de transcripción)
Python 3.10+
Modo Ollama: Ollama instalado + un modelo de visión descargado (5 GB+ de RAM)
Modo LM Studio: LM Studio 0.3.16+ con un modelo de visión cargado
Modo nube: Una clave API de OpenRouter

ffmpeg se instala automáticamente mediante Homebrew en la primera ejecución si falta.

🚀 Instalación

Opción 1 — uvx (sin instalación, ejecutar directamente)

uvx vidlizer setup

Opción 2 — pipx (aislado, disponible globalmente)

pipx install vidlizer
vidlizer setup    # interactive wizard: detects providers, writes .env

Opción 3 — pip / virtualenv

pip install vidlizer
vidlizer setup

Opción 4 — desde el código fuente

git clone https://github.com/arizawan/vidlizer.git
cd vidlizer
python -m venv .venv && source .venv/bin/activate
pip install -e .
vidlizer setup    # or: cp env.sample .env

Asistente de primera ejecución

vidlizer setup detecta todos los proveedores instalados, te permite elegir el principal + el de respaldo y escribe un .env para ti. También ofrece descargar un modelo de visión para Ollama si no hay ninguno instalado.

$ vidlizer setup
  Detected providers:
    1.  Ollama        → qwen2.5vl:3b
    2.  OpenRouter    → google/gemma-3-27b-it:free

  Primary provider (1–2): 1
  Fallback (1–1, Enter to skip): 2

✓  .env written → /your/project/.env

Verificación de salud

vidlizer doctor          # shows ffmpeg, .env, provider, mlx-whisper status
vidlizer doctor --fix    # interactive repair: brew-installs ffmpeg/Ollama/LM Studio, re-runs setup

Configuración manual del proveedor

Ollama (totalmente offline, sin clave API):

# Install Ollama from https://ollama.com, then:
ollama pull qwen2.5vl:3b   # ~3.2 GB, requires 5 GB+ RAM (recommended)
ollama pull qwen2.5vl:7b   # ~6.0 GB, requires 10 GB+ RAM (best quality)

LM Studio (inferencia local acelerada por GPU):

# In LM Studio: load a vision model (e.g. Qwen2.5-VL 7B), enable the local server
# Set PROVIDER=openai and OPENAI_BASE_URL=http://localhost:1234/v1 in .env

OpenRouter (nube):

# Paste your OpenRouter key in .env:
# OPENROUTER_API_KEY=sk-or-v1-...

⚡ Inicio rápido

# Ollama — fully local, no API key
vidlizer demo.mp4 --provider ollama --model qwen2.5vl:3b

# LM Studio (or any OpenAI-compat server)
vidlizer demo.mp4 --provider openai --model qwen/qwen2.5-vl-7b-instruct

# OpenRouter (cloud)
vidlizer demo.mp4 --provider openrouter --model google/gemini-2.5-flash

# Analyze a YouTube video
vidlizer "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

# Analyze a single image or PDF
vidlizer screenshot.png
vidlizer report.pdf

# Focus on a time range
vidlizer demo.mp4 --start 30 --end 90

# Output as Markdown or plain-text summary
vidlizer demo.mp4 --format markdown -o result.md
vidlizer demo.mp4 --format summary -o result.txt

Ejecuta sin argumentos para un selector de archivos interactivo + selector de proveedor/modelo.

📄 Salida

Tres formatos mediante --format:

Formato	Bandera	Extensión predeterminada	Descripción
JSON	`--format json`	`.analysis.json`	Array de flujo estructurado completo (predeterminado)
Markdown	`--format markdown`	`.analysis.md`	Documento paso por sección con escena/acción/habla
Resumen	`--format summary`	`.analysis.txt`	Texto plano agrupado por fase

La ruta de salida predeterminada es <normalized-name>.analysis.json (o extensión correspondiente), o pasa -o path.

{
  "flow": [
    {
      "step": 1,
      "timestamp_s": 0.0,
      "phase": "Introduction",
      "scene": "Title card with product logo on dark background.",
      "subjects": ["Logo", "Text overlay"],
      "action": "Static title card displayed.",
      "text_visible": "vidlizer — analyze any video",
      "context": "Opening of a product demo.",
      "observations": "Clean minimal design.",
      "next_scene": "Screen recording of the CLI.",
      "speech": "Welcome to the vidlizer demo."
    }
  ],
  "transcript": [
    { "start": 0.0, "end": 2.4, "text": "Welcome to the vidlizer demo." }
  ],
  "model_used": "gemma-4-E2B-it-MLX-4bit",
  "provider_used": "openai"
}

model_used y provider_used reflejan el modelo que realmente produjo el resultado — incluso después del respaldo. Se muestran en la respuesta MCP analyze_video para que los agentes sepan qué proveedor se ejecutó.

Campos de paso de flujo

Campo	Descripción
`step`	Entero secuencial
`timestamp_s`	Tiempo aproximado en segundos (desde la etiqueta del fotograma)
`phase`	Sección lógica — Introducción, Demo, Acción, Conclusión…
`scene`	Lo que es visible actualmente
`subjects`	Personas clave, objetos, elementos de UI presentes
`action`	Qué está sucediendo — interacción, movimiento, narración, evento
`text_visible`	Todo el texto legible en pantalla
`context`	Estado persistente — temporizador, puntuación, tema, marca…
`observations`	Errores, anomalías, emociones, hechos clave
`next_scene`	Breve descripción de lo que sigue
`speech`	Texto de transcripción hablado durante este paso (solo videos con audio)

🤖 Modelos

Todos los proveedores envían un fotograma por solicitud (batch_size=1) para máxima compatibilidad con modelos de contexto limitado. La salida en modo pensamiento (etiquetas <think>) se elimina automáticamente.

Local — Ollama

Totalmente offline, sin clave API. Instala con ollama pull <name>:

Modelo	Disco	RAM	Notas
`qwen2.5vl:3b` ★	3.2 GB	~5 GB	Recomendado — 128K ctx, JSON sólido, multi-imagen
`qwen2.5vl:7b` ★	6.0 GB	~9 GB	Mejor calidad de Ollama — 128K ctx, necesita 10+ GB de RAM
`minicpm-v:8b`	5.5 GB	~8 GB	OCR sólido + razonamiento visual, 32K ctx
`llava-onevision:7b`	5.5 GB	~8 GB	Multi-imagen sólida + fotogramas de video, JSON confiable

Orden de respaldo (si el modelo configurado no está disponible): qwen2.5vl:7b → qwen2.5vl:3b → minicpm-v:8b → llava-onevision:7b → llava:13b → llava:7b

Usa el /api/chat nativo de Ollama con format: json para una salida estructurada confiable.

Local — LM Studio / oMLX / vLLM / LocalAI (compatible con OpenAI)

Inferencia acelerada por GPU mediante cualquier servidor compatible con OpenAI. Establece PROVIDER=openai y apunta OPENAI_BASE_URL a tu servidor.

Modelo	VRAM	Notas
`qwen/qwen2.5-vl-7b-instruct` ★	~8 GB	Recomendado — 128K ctx, JSON confiable, multi-imagen
`qwen/qwen3-vl-8b` ★	~10 GB	Última visión Qwen — etiquetas de pensamiento eliminadas automáticamente
`qwen/qwen2.5-vl-3b-instruct`	~5 GB	Ligero — rápido, 5–6 GB de VRAM
`google/gemma-4-e4b-it`	~6 GB	Google MoE — soporte nativo de LM Studio 0.3.16+
`google/gemma-4-9b-it`	~10 GB	Gemma 4 más fuerte — 128K ctx, mejor seguimiento de instrucciones
`zai-org/glm-4.6v-flash`	~8 GB	ZhipuAI MoE — 128K ctx, JSON sólido, baja latencia
`openbmb/minicpm-v-4.5`	~8 GB	Basado en Qwen3 8B — OCR sólido, multi-imagen, listo para vLLM

oMLX (nativo de Apple Silicon, omlx.ai) — modelos en formato MLX de HuggingFace, auto-detectado en el puerto 8000 (distinto de LM Studio). Los ID de modelo son rutas de HuggingFace:

Modelo oMLX	RAM unificada	Notas
`mlx-community/Qwen2.5-VL-7B-Instruct-8bit` ★	~8 GB	Mejor opción para Apple Silicon — rápido, JSON sólido
`mlx-community/Qwen2.5-VL-3B-Instruct-8bit`	~4 GB	Ligero — 4–5 GB de RAM
`mlx-community/Qwen3-VL-8B-8bit`	~9 GB	Última visión Qwen — etiquetas de pensamiento eliminadas
`mlx-community/MiniCPM-V-2_6-8bit`	~8 GB	OCR sólido + razonamiento

Los ID de modelo son como se muestran en el navegador de modelos de LM Studio, el panel de administración de oMLX o tu configuración de vLLM. LM Studio / oMLX sirven un modelo a la vez (no se necesita respaldo). vLLM con múltiples modelos cargados usa la misma secuencia de respaldo.

Orden de fragmentos de respaldo (vLLM / oMLX con múltiples modelos): qwen2.5-vl-7b → qwen2.5-vl-3b → qwen3-vl → gemma-4 → glm-4 → minicpm-v → llava-onevision → llava

Nube — OpenRouter

Modelos obtenidos en vivo con precios actuales. Ejecuta vidlizer --list-models para ver la lista en vivo.

Modelo	Entrada / 1M tokens	Notas
`google/gemini-2.5-flash` ★	$0.15	Recomendado — 1M ctx, rápido, preciso
`google/gemini-2.5-flash-lite`	$0.075	Más barato — ligeramente menos preciso
`google/gemini-2.5-pro`	$1.25	Mejor calidad, mayor costo
`openai/gpt-4o`	$2.50	Buque insignia de OpenAI
`openai/gpt-4o-mini`	$0.15	Opción económica de OpenAI
`nvidia/nemotron-nano-12b-v2-vl:free`	free ⚡	Limitado por tasa (8K/solicitud), 128K ctx
`google/gemma-4-31b-it:free`	free ⚡	Limitado por tasa, 128K ctx

Los modelos gratuitos recurren automáticamente al modelo de pago más barato disponible en caso de fallo.

🎙️ Transcripción

Para videos con pista de audio, vidlizer automáticamente:

Extrae un WAV mono de 16 kHz con ffmpeg
Transcribe con Apple MLX Whisper (Neural Engine + GPU en la serie M)
Fusiona cada segmento de transcripción en el paso de flujo más cercano como speech

mlx-whisper está incluido en la instalación predeterminada en macOS. El modelo base de Whisper (~150 MB) se descarga en la primera transcripción.

Para optar por no participar: --no-transcript

🛠️ Referencia de CLI

Subcomandos

vidlizer setup              # interactive wizard: detects providers, writes .env
vidlizer doctor             # health check: ffmpeg, .env, providers, mlx-whisper
vidlizer doctor --fix       # auto-repair: brew-installs missing deps, re-runs setup
vidlizer mcp-setup          # generate MCP config for Claude Code / Cursor / Claude Desktop

Opciones de análisis

vidlizer [video] [options]

positional:
  video                 Path to file or URL (YouTube/Loom/Vimeo/Twitter)

options:
  -o, --output PATH     Output path (default: <name>.analysis.json/.md/.txt)
  --format FORMAT       Output format: json (default), summary, markdown
  --provider PROVIDER   ollama | openai | openrouter  (openai covers LM Studio + oMLX + vLLM)
  --model MODEL         Model slug — Ollama name, OpenAI-compat ID, or OpenRouter slug
  --max-frames N        Max frames to send (default 60, hard cap 200)
  --start SECONDS       Analyze from this timestamp
  --end SECONDS         Analyze up to this timestamp
  --scene THRESHOLD     Scene-change sensitivity 0–1 (default 0.1)
  --min-interval SECS   Minimum seconds between frames (default 2)
  --fps FPS             Extract at fixed FPS instead of scene-change
  --scale PX            Frame width in pixels (default 512)
  --batch-size N        Frames per API call (0 = auto, default 1 for all providers)
  --concurrency N       Parallel batch workers (default: 4 for OpenRouter, 1 for local)
  --dedup-threshold N   Perceptual dedup Hamming distance (default 8, 0 = off)
  --no-transcript       Skip audio transcription
  --max-cost USD        Abort if spend exceeds this (default 1.00)
  --timeout SECS        Per-request timeout (default 600)
  -v, --verbose         Debug output
  --stats               Show token + cost usage stats by model, then exit
  --clear-stats         Reset usage log, then exit

🔧 Variables de entorno

Copia env.sample a .env:

# ── Provider ────────────────────────────────────────────────────────────────
# ollama    — local Ollama server (no API key, no cost)
# openai    — any OpenAI-compatible server (LM Studio, oMLX, vLLM, LocalAI, real OpenAI)
# openrouter — cloud inference via OpenRouter
PROVIDER=ollama

# ── Ollama (local, no API key) ──────────────────────────────────────────────
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen2.5vl:3b

# ── OpenAI-compatible (LM Studio, oMLX, vLLM, LocalAI, real OpenAI) ─────────
#   LM Studio default port: 1234  |  oMLX default port: 8000  |  vLLM: 8000
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_API_KEY=lm-studio        # "not-needed" for oMLX/vLLM, real key for OpenAI
OPENAI_MODEL=                   # exact model ID as shown in server (required)

# ── OpenRouter (cloud) ──────────────────────────────────────────────────────
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=google/gemini-2.5-flash

# ── Frame extraction ────────────────────────────────────────────────────────
SCENE_THRESHOLD=0.1     # lower = more frames
MIN_INTERVAL=2          # seconds between forced frames
MAX_FRAMES=60
FRAME_WIDTH=512
MAX_COST_USD=1.00
BATCH_SIZE=0            # 0 = auto (defaults to 1 per request for all providers)
REQUEST_TIMEOUT=600

# ── Fallback ────────────────────────────────────────────────────────────────
# Same-provider fallback: set FALLBACK_MODEL only.
#   Blank = auto-detect installed models (Ollama) or available models (OpenAI-compat).
# Cross-provider fallback: set FALLBACK_PROVIDER + FALLBACK_MODEL.
#   FALLBACK_BASE_URL and FALLBACK_API_KEY default to the primary provider's values
#   if not set — override only when the fallback uses a different server/key.
FALLBACK_PROVIDER=      # ollama | openai | openrouter  (blank = same as PROVIDER)
FALLBACK_MODEL=         # model ID for fallback  (blank = auto-detect same-provider)
FALLBACK_BASE_URL=      # base URL for fallback openai/ollama server (optional)
FALLBACK_API_KEY=       # API key for fallback provider (optional)

📊 Seguimiento de uso

Cada ejecución exitosa agrega un registro a ~/.cache/vidlizer/usage.jsonl. Las ejecuciones de prueba (pytest) se excluyen.

vidlizer --stats          # print per-model breakdown
vidlizer --clear-stats    # reset log

Ejemplo de salida:

Usage statistics  (/Users/you/.cache/vidlizer/usage.jsonl)

  Total runs:       12
  Total tokens in:  58,240
  Total tokens out: 6,102
  Total cost:       ~$0.0312
  Total steps:      94

  Model                               Provider     Runs   Tokens in  Tokens out  Cost USD
  gemma-4-E2B-it-MLX-4bit             openai          9      45,800       4,900      free
  google/gemini-2.5-flash             openrouter       3      12,440       1,202  ~$0.0312

También disponible como herramienta MCP: get_usage_stats() → mismos datos como JSON. clear_usage_stats() restablece el registro.

🔌 Servidor MCP

Usa vidlizer desde cualquier agente compatible con MCP — Claude Code, Cursor, Claude Desktop, Gemini CLI.

El modelo y el proveedor se establecen mediante variables de entorno y no pueden ser anulados por el agente de IA. Esto evita que los agentes cambien a modelos inesperados o costosos a mitad de sesión.

Instalación

# uvx (no install — run directly)
uvx "vidlizer[mcp]" vidlizer-mcp

# pipx (isolated, globally available)
pipx install "vidlizer[mcp]"

# If vidlizer is already installed via pipx — inject mcp into the same venv
pipx inject vidlizer mcp

# pip / virtualenv
pip install "vidlizer[mcp]"

vidlizer-mcp se agrega a tu PATH automáticamente. Verifica con which vidlizer-mcp.

Nota sobre pipx: pipx install vidlizer crea el punto de entrada vidlizer-mcp pero el paquete mcp no está instalado. Ejecuta pipx inject vidlizer mcp para agregarlo, o usa pipx install "vidlizer[mcp]" desde el principio.

Configuración MCP de un comando

vidlizer mcp-setup

Asistente interactivo — detecta vidlizer-mcp, lee tu .env, y escribe la configuración en el archivo de configuración de tu editor o muestra una línea única para copiar y pegar. Soporta Claude Code, Cursor, Claude Desktop, Windsurf.

Configurar manualmente

Inicio rápido — uvx (sin instalación requerida)

No se necesita pip install ni pipx. uvx descarga y ejecuta vidlizer sobre la marcha:

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "vidlizer[mcp]", "vidlizer-mcp"],
      "env": {
        "PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "gemma4:2b"
      }
    }
  }
}

Cambia el bloque env por cualquier proveedor (OpenRouter, LM Studio, oMLX) — los command/args permanecen iguales.

Usa la ruta absoluta al binario — which vidlizer-mcp la proporciona. Todas las configuraciones a continuación usan JSON (funciona en Claude Code, Cursor, Claude Desktop, Gemini CLI).

Para Claude Code mediante CLI:

claude mcp add-json vidlizer '{"type":"stdio","command":"/path/to/vidlizer-mcp","env":{"PROVIDER":"openrouter","OPENROUTER_API_KEY":"sk-or-v1-...","OPENROUTER_MODEL":"google/gemini-2.5-flash"}}'
# Add --scope project for per-project config instead of global

Proveedor único — OpenRouter (nube)

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "openrouter",
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "OPENROUTER_MODEL": "google/gemini-2.5-flash"
      }
    }
  }
}

Los modelos gratuitos (sufijo :free) recurren automáticamente al modelo de pago más barato si se limitan por tasa — no se necesita configuración adicional.

Proveedor único — Ollama (local, sin clave de API)

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "gemma4:2b"
      }
    }
  }
}

FALLBACK_MODEL es opcional — omitirlo auto-detecta los modelos instalados y los prueba en orden preferido.

Proveedor único — LM Studio (compatible con OpenAI, puerto 1234)

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "openai",
        "OPENAI_BASE_URL": "http://localhost:1234/v1",
        "OPENAI_API_KEY": "lm-studio",
        "OPENAI_MODEL": "qwen/qwen2.5-vl-7b-instruct"
      }
    }
  }
}

Proveedor único — oMLX (Apple Silicon, puerto 8000)

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "openai",
        "OPENAI_BASE_URL": "http://localhost:8000/v1",
        "OPENAI_API_KEY": "not-needed",
        "OPENAI_MODEL": "mlx-community/Qwen2.5-VL-7B-Instruct-8bit"
      }
    }
  }
}

Respaldo entre proveedores — oMLX → OpenRouter

El principal se ejecuta en oMLX local; si falla, cambia automáticamente a OpenRouter en la nube.

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "openai",
        "OPENAI_BASE_URL": "http://localhost:8000/v1",
        "OPENAI_API_KEY": "not-needed",
        "OPENAI_MODEL": "mlx-community/Qwen2.5-VL-7B-Instruct-8bit",
        "FALLBACK_PROVIDER": "openrouter",
        "FALLBACK_MODEL": "google/gemini-2.5-flash",
        "FALLBACK_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Respaldo entre proveedores — oMLX → Ollama

Ambos locales; si oMLX falla (modelo faltante / servidor caído) → Ollama se hace cargo.

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "openai",
        "OPENAI_BASE_URL": "http://localhost:8000/v1",
        "OPENAI_API_KEY": "not-needed",
        "OPENAI_MODEL": "mlx-community/Qwen2.5-VL-7B-Instruct-8bit",
        "FALLBACK_PROVIDER": "ollama",
        "FALLBACK_MODEL": "qwen2.5vl:7b"
      }
    }
  }
}

FALLBACK_BASE_URL tiene como valor predeterminado OLLAMA_HOST (o http://localhost:11434) — solo configúralo si Ollama está en un host no estándar.

Respaldo entre proveedores — Ollama → OpenRouter

Primero local; la nube entra en acción si no hay modelo instalado o la inferencia falla.

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "qwen2.5vl:7b",
        "FALLBACK_PROVIDER": "openrouter",
        "FALLBACK_MODEL": "google/gemini-2.5-flash",
        "FALLBACK_API_KEY": "sk-or-v1-..."
      }
    }
  }
}

Respaldo del mismo proveedor — fijar modelo de respaldo explícito

Cuando no se desea auto-detección; ambos modelos usan el mismo proveedor.

{
  "mcpServers": {
    "vidlizer": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/vidlizer-mcp",
      "env": {
        "PROVIDER": "ollama",
        "OLLAMA_MODEL": "qwen2.5vl:7b",
        "FALLBACK_MODEL": "qwen2.5vl:3b"
      }
    }
  }
}

Referencia de variables de entorno de respaldo:

Var	Propósito	Valor predeterminado
`FALLBACK_PROVIDER`	Proveedor para respaldo (`ollama`/`openai`/`openrouter`)	igual que `PROVIDER`
`FALLBACK_MODEL`	ID del modelo para respaldo	auto-detección (mismo proveedor)
`FALLBACK_BASE_URL`	URL base para el servidor de respaldo `openai`/`ollama`	`OPENAI_BASE_URL` o `OLLAMA_HOST`
`FALLBACK_API_KEY`	Clave de API para el proveedor de respaldo	`OPENAI_API_KEY` o `OPENROUTER_API_KEY`

Registros

Toda la actividad (extracción de fotogramas, llamadas a API, errores) se escribe en:

tail -f ~/.cache/vidlizer/mcp.log

Herramientas

Herramienta	Devuelve	Tokens de salida
`analyze_video(path, **opts)`	`analysis_id` + metadatos	~100
`list_analyses()`	Todos los análisis almacenados (solo metadatos)	~50/entrada
`get_summary(id, level)`	Resumen de texto breve/medio/completo	~200–2K
`get_step(id, step)`	Paso de flujo individual	~150
`get_steps(id, start, end)`	Rango de pasos	escalado
`get_phase(id, phase)`	Todos los pasos en la fase nombrada	escalado
`search_analysis(id, query)`	Pasos que coinciden con texto (`query` o `keyword`)	solo coincidencias
`get_transcript(id, start_s, end_s)`	Segmento de transcripción	escalado
`get_full_analysis(id)`	Flujo completo + transcripción	completo
`delete_analysis(id)`	Confirmación	~10
`get_usage_stats()`	Desglose de tokens y costos por modelo	~50/modelo
`clear_usage_stats()`	Reiniciar registro de uso	~10

Flujo de trabajo eficiente en tokens

analyze_video almacena el resultado completo en el disco y devuelve solo analysis_id + metadatos (~100 tokens). El LLM extrae partes específicas bajo demanda — un video de 60 pasos cuesta ~100 tokens para registrarse, pero solo carga lo necesario por consulta.

agent: analyze_video("demo.mp4")
→ { "analysis_id": "abc123", "step_count": 42, "phases": ["Intro", "Demo", "Outro"] }

agent: get_summary("abc123", level="brief")
→ "Intro: Title card displayed | Demo: CLI recording | Outro: Results shown"

agent: get_phase("abc123", "Demo")
→ [ { step, timestamp_s, action, scene }, … ]

agent: search_analysis("abc123", "error")
→ [ { step: 17, matched_field: "observations", matched_value: "Stack trace visible" } ]

Recursos MCP

URI	Contenido
`vidlizer://analyses`	Todos los análisis (metadatos JSON)
`vidlizer://analyses/{id}`	Análisis completo en JSON
`vidlizer://analyses/{id}/summary`	Resumen de texto medio

🧪 Pruebas

Suite de pruebas completamente automatizada — 248 pruebas unitarias + de integración, 3 pruebas e2e.

make install-dev    # installs pytest, pytest-html, pytest-mock
make test           # runs unit + integration (no network) → reports/test-report.html
make test-e2e       # also runs YouTube download + full pipeline e2e
make smoke          # real-provider smoke test against all detected providers

Informe de unitarias/integración: reports/test-report.html. Las pruebas cubren:

Extracción de fotogramas (ffmpeg), deduplicación perceptual, TTL de caché
Detección de audio, fusión de transcripciones (sin duplicados)
PDF → fotogramas, codificación de imágenes, detección de URLs
Formateador de salida: correctitud de json/resumen/markdown
Pipeline completo con OpenRouter simulado (servidor HTTP falso)
Capa HTTP: análisis SSE, manejo de 429, límite de costos, streaming de Ollama
Lote: reintento de reparación JSON, guardia de concurrencia de modelos gratuitos
Modelos: consulta de precios, secuencias de respaldo, auxiliares de formato
Seguimiento de uso: ciclo de vida de registro/estadísticas/limpieza
Invocaciones reales de subprocesos CLI contra medios reales
Descarga real de YouTube + análisis completo (opt-in -m e2e)

Prueba de humo

make smoke ejecuta el pipeline completo con proveedores reales contra cada proveedor detectado en orden (Ollama → LM Studio → oMLX → OpenRouter). Antes de que comiencen las pruebas, solicita interactivamente por cada proveedor local:

Modelo de visión encontrado → "Test ollama with qwen2.5vl:3b? [Y/n]"
Sin modelo de visión (Ollama) → "Download qwen2.5vl:3b (~2.3 GB)? [y/N]"
Sin modelo de visión (LM Studio/oMLX) → instrucciones para cargar uno + mensaje de reintento

Cada proveedor se prueba de forma aislada con su propio directorio de salida (evita la contaminación de caché). Los modelos locales se descargan de la VRAM después de las pruebas de cada proveedor. Los resultados van en reports/smoke-TIMESTAMP.html con tarjetas de puntuación aprobado/fallido por proveedor.

make smoke                                  # auto-detect all providers
make smoke ARGS="--provider ollama"         # force single provider
make smoke ARGS="--provider openrouter"     # OpenRouter only (no local needed)

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para la configuración, estilo de código y pautas de PR.

Reporte de error: abre un problema — incluye proveedor, modelo, versión de macOS, error completo
Solicitud de característica: abre un problema describiendo el caso de uso
PR: haz una rama desde main, agrega pruebas, make test pasa, ruff check vidlizer/ limpio

❤️ Soporte

vidlizer es gratuito y de código abierto. Si te ahorra tiempo:

📝 Licencia

MIT — ver LICENSE.