video-to-llm

Tu LLM no puede ver un curso de cuarenta horas. Subirlo es lento, a menudo caro y con frecuencia no está permitido. Extraer los fotogramas por tu cuenta cuesta millones de tokens y descarta el audio.

video-to-llm convierte cada vídeo en un documento cronológico — habla, silencios marcados, encabezados de sección y, opcionalmente, lo que aparecía en pantalla —, todo en el orden en que ocurrió y cada línea con una marca de tiempo que conduce al fotograma exacto del que procede.

Hazlo una vez. Haz todas las preguntas que quieras, a todos los modelos que quieras, mientras conserves la carpeta.

Inicio rápido

uvx video-to-llm process lecture.mp4 --transcribe-model tiny

Esa es la forma rápida de verlo funcionar: el modelo de voz tiny es una descarga de 75 MB, no de los 1.4 GB del modelo por defecto, así que obtienes un documento real en un minuto en lugar de esperar una descarga para saber si te gusta el resultado. Cuando lo hagas, elimina la flag:

uvx video-to-llm process lecture.mp4

Todavía no se puede instalar desde PyPI. El nombre está registrado, pero no hay nada en el índice que merezca instalarse: la única versión publicada, 1.0.0rc1, salió sin el módulo de colecciones y ha sido retirada. Hasta que llegue 1.0.0, clona el repositorio y ejecuta uv sync y después uv run video-to-llm process lecture.mp4 --transcribe-model tiny.

Necesitas FFmpeg en tu PATH — las versiones 4 a 9 funcionan bien. El modelo de voz se descarga una sola vez, en el primer uso, y a partir de ahí nada vuelve a tocar la red.

video-to-llm doctor          # check this machine is ready

tiny es rápido y notablemente menos preciso; medium es el predeterminado porque es el más pequeño del que merece la pena conservar una transcripción. --transcribe-model también acepta base, small y large-v3.

Related MCP server: video-reader-mcp

Lo que obtienes

Esta es la salida real — líneas reales de una grabación real de 49 minutos, en la configuración:

00:01:30  [nobody speaking · 11 seconds]
00:01:40  Yep, just so that you know, the first thing you'll do is you'll take everything out of
00:01:48  your chart.
00:01:49  When you're going to analyze the chart.
00:01:54  [nobody speaking · 4 seconds]
00:01:58  I think all of you know what trends are, right?
00:02:01  You're either going up or you're either coming down. Very simple, right?
00:02:05  But when you look at trends in terms of structure, what we are looking for is the basic.

Ese es todo el artefacto: texto plano, cronológico, con marcas de tiempo hasta la fuente y tuyo. Entréguelo a cualquier modelo. Ponlo en el revisor. Guárdaledurante diez años.

Comprueba cualquier línea

Cada marca de tiempo resuelve a la imagen que hay detrás:

video-to-llm show lecture 00:02:05

lecture.mp4 — 00:02:05
in job 'lecture'

  00:02:01  You're either going up or you're either coming down. Very simple, right?
> 00:02:05  But when you look at trends in terms of structure, what we are looking for is the basic.

Picture: ~/Documents/VideoToLLM/lecture/…/frames/000062_t000124.jpg

Una afirmación de tu modelo solo es evidencia si puedes verificarla. Así es como se hace.

Cómo se compara

Honesto en ambas direcciones — incluido donde esta es la herramienta equivocada.

Comprobado con la documentación propia de esos proyectos el 21 de agosto de 2026. Evolucionan; si alguna fila de aquí se ha quedado obsoleta, es un error que merece que lo ocurra.

Cómo usarlo

Desde la línea de comandos

video-to-llm process lecture.mp4                      # one video
video-to-llm process w1.mp4 w2.mp4 --name "Course"    # several, in your order
video-to-llm process talk.mp4 --interval 5            # fewer pictures, faster
video-to-llm process demo.mp4 --describe local        # add screen descriptions
video-to-llm process talk.mp4 --format jsonl          # also emit structured data
video-to-llm show "Course" 01:12:30                   # resolve a citation
video-to-llm export "Course" --format srt             # subtitles, no reprocessing
video-to-llm status                                   # what is done, what is running
video-to-llm run-next "Course"                        # jump the queue

Desde un agente

video-to-llm mcp        # MCP server on stdio; needs the [mcp] extra

Cuatro herramientas — process_video, list_videos, get_transcript, get_segment. process_video es idempotente: si se le pide un vídeo que ya ha procesado, devuelve el documento existente en lugar de hacer el trabajo de nuevo. Ese es el objetivo. Procesa un curso de cuarenta horas una sola vez; cada pregunta después es instantánea, offline y gratuita.

Un agente no puede elegir un servicio de descripción de pago a través de estas herramientas. Esa decisión corresponde a la pantalla de aplicación, donde están visibles la estimación y el límite de gasto.

También hay una skill (habilidad/que enseña a un agente a comprobar lo que ya está procesado antes de hacer algo caro:

npx skills add navdeep-h-singh/video-to-llm -g

Eso funciona en Codex, Cursor, Copilot, Gemini CLI y cualquier otra cosa que lea Agent Skills. Para Claude Code, el plugin registra la skill junto al servidor MCP:

/plugin marketplace add navdeep-h-singh/video-to-llm
/plugin install video-to-llm@video-to-llm

Desde el navegador

video-to-llm start

Una interfaz en 127.0.0.1 con progreso en vivo, un revisor de fotogramas, control de trabajos y el constructor de colecciones. Cerrar el navegador no detiene un trabajo.

Colecciones

Varios vídeos ya procesados, en un orden establecido explícitamente por ti, ensamblados en un único documento o en partes numeradas y dimensionadas para caber en la ventana de contexto. Crear una colección reutiliza el resultado existente — nunca reextrae un fotograma, ni vuelve a transcribir audio ni a ejecutar una descripción.

El orden nunca se deduce del nombre de archivo, la fecha o el contenido. Dos grabaciones de la misma mañana no tienen secuencia inherente; así que tú indicas cuál es.

Privacidad como mecanismo

No es una promisoria — es un conjunto de propiedades con tests que fallan cuando se degradan.

• La interfaz se enlaza a 127.0.0.1, verificado al crear la aplicación.

• Un middleware rechaza un Host ajeno y un origin ajeno en cada escritura.

• Ninguna página carga un recurso fuera de su propio origen. Sin CDN, sin fuente web, sin analítica.

• Tus vídeos fuente nunca se copian, ni se mueven, ni se suben.

• Las claves están en el llavero del sistema — macOS Keychain, Windows Credential Manager, Linux Secret Service. Nunca se crea un respaldo texto plano, y una clave almacenada no se te vuelve a mostrar, ni siquiera un prefijo.

• No hay cuentas, ni telemetría, ni nada en la que iniciar sesión.

• Las descripciones están desactivadas por defecto. Un trabajo que las deja desactivadas no ocasiona ninguna petición de red.

• El sistema local nunca recurre silenciosa a la nube.

Opcional: descripciones de pantalla

Desactivadas por defecto. Cuando las activas, eliges entre tu propio modelo de Ollama — los fotogramas permanecen en el dispositivo, sin coste — y marcador un servicio (Claude, Gemini, OpenAI o cualquier endpoint compatible con OpenAI o Anthropic), que recibe solo las imágenes fijas numeradas, nunca el vídeo y nunca el audio. Ves lo que se enviará y aproximadamente el coste antes de que salga nada, y el procesamiento se detiene en un límite que establezcas.

Requisitos

• Python 3.11, 3.12 o 3.13

• FFmpeg con ffprobe en tu PATH

• Espacio para el modelo de voz — 75 MB para tiny, 1,4 GB para el modelo medium por defecto — además de espacio para los los (un vídeo de 2 horas con un imagen cada 2 segundos supone unos 2 GB)

Una GPU es opcional en todos los lados. La transcripción funciona con CPU en todas las plataformas.

FFmpeg 9 no da problemas. Eliminó -vsync, que todos los FFmpeg anteriores a 5 necesitaban; la extracción lee la versión una vez y pide la flag que esa crea acepta, de modo que desde 4.x hasta 9.x funciona. video-to-llm doctor imprime la versión encontrada y la flag que se usará. Aquí se ha desarrollado contra 8.1.2; el resto está cubierto por tests sobre la lista de argumentos y la matriz de CI.

Otras formas de instalar

uv tool install video-to-llm            # or: pipx install video-to-llm
uv sync                                 # from a clone
docker build -t video-to-llm .          # command line only, see the Dockerfile

Limitaciones conocidas

Aquí están documentadas a propósito, en lugar de dejarte que las descubras tú.

• Las descripciones de pantalla están en beta y sus campos estructurados están pensados para un solo dominio. Funcionan — en una grabación de un gráfico de 49 minutos el modelo leyó el instrumento correcto, el marco temporal correcto y valores reales de la pantalla — pero cinco de los ocho campos (timeframe, currency_pair, indicators_and_states, exact_action, setup_type) describen gráficos de trading, y eso es una decisión deliberada, no un descuido. En cualquier otro tipo de vídeo esos cinco devuelven Unknown. El modelo se abstiene en lugar de inventar, así que el resultado es escueto en lugar de incorrecto, y visible_text, visual_description y confidence siguen aplicándose a cualquier cosa. La precisión no está medida en ninguno de los dos casos. Consulta docs/DESCRIPTION_QUALITY.md para ver el experimento que hay detrás de esta lectura.

  La transcripción, la línea temporal y las citas son las partes que funcionan en todos los vídeos. Evalúa la herramienta por esas partes.

• La precisión de la transcripción no está medida, y a veces Whisper escribe una línea sobre el silencio — una transcripción que empieza con «¡Gracias por ver el vídeo!» es invención del modelo, no de tu vídeo.

• Las descripciones locales son lentas: unos 31 s por imagen en un Mac con Apple Silicon, medido sobre 1488 imágenes. Usa un --interval más espaciado, o un servicio con un tope.

• Ningún proveedor de nube se ha probado contra un servicio en vivo. Cinco adaptadores están verificados contra los esquemas de petición y respuesta documentados; la instancia local de Ollama está verificada en vivo contra 0.32.6 con qwen2.5vl:7b.

• Nadie ha usado esto en Windows ni Linux, aunque la CI ya se ejecuta allí. El desarrollo fue enteramente en macOS (Apple Silicon). La suite completa pasa en los tres sistemas operativos y las tres versiones de Python; la wheel compilada se instala y se ejercita fuera del checkout en cada uno de ellos, el contenedor ejecuta el pipeline completo de principio a fin y sin red. Eso es un mínimo real, pero no es lo mismo que usarlo: una matriz en verde dice que los paths, los backends de keyring y los fallbacks de symlink funcionan en un runner limpio, no que funcionan en tu máquina con tus archivos. Los informes procedentes de ambos son lo más útil que este proyecto puede recibir.

• El contenedor incluye la línea de comandos, no la interfaz — la interfaz se enlaza a loopback, que dentro de un contenedor es inalcanzable desde el host.

• No se descarga ninguna URL. Solo archivos locales. Descárgalo tú primero.

• El registro de eventos crece sin límite.

Documentación

    |

| docs/IMPORT_EXPORT.md | Introducir trabajo previo y extraer resultados | | docs/LOCAL_SETUP.md | Configuración por plataforma | | docs/DECISIONS.md | Decisiones tomadas en el momento de la construcción, y por qué |

Contribuciones

Los informes de errores que vienen del uso real valen más que cualquier otra cosa ahora mismo, sobre todo en Windows y Linux. Consulta CONTRIBUTING.md.

Licencia

MIT. Consulta LICENSE.