Video Frame Expedition for DaVinci Resolve

English · Français

Video Frame Expedition for DaVinci Resolve analiza tus rushes con un modelo de visión local, para que un asistente de IA pueda editar sabiendo qué contiene cada toma.

Análisis: metadatos, lugar, hora, sol y clima de la grabación; tomas, fotogramas clave y sujetos; sonidos, habla y texto en pantalla. En inglés y en francés.

Búsqueda semántica: tomas, fotogramas clave, habla y capítulos se convierten en pasajes cronometrados, encontrados por palabras clave y por significado (búsqueda híbrida: texto completo y vectores calculados localmente). Filtros por clima, luz, lugar, fechas, sujetos, encuadre o calidad; el modelo local responde preguntas sobre toda la biblioteca y cita sus fuentes.

Base de datos resiliente: cada video se reconoce por su contenido, no por su ruta: si se mueve o se renombra, conserva sus análisis sin volver a analizarse. Los archivos de análisis junto a los videos los restauran en otra computadora o tras perder la base de datos.

Para asistentes de IA (Claude, Cursor, VS Code, Codex): un servidor MCP con 25 herramientas. El asistente de IA lee la línea de tiempo abierta en Resolve, sabe qué contiene cada clip, busca en toda la biblioteca tomas, obtiene puntos de corte seguros y reencuadres, y construye la edición en una nueva línea de tiempo. Las tareas simples (describir fotogramas, responder sobre la biblioteca, localizar un sujeto) van al modelo local: el asistente de IA solo recibe los resultados y ahorra sus tokens.

Más allá del MCP de Resolve: cuatro herramientas controlan Resolve Studio 21.1 mediante scripts fijos y probados, en lugar de código reescrito para cada solicitud: leer la línea de tiempo con rangos de origen exactos, reencuadrar (9:16…) centrado en los sujetos, una nueva línea de tiempo construida y luego verificada valor por valor, y marcadores. Evitan los problemas conocidos de la API de Resolve 21.1, nunca modifican una línea de tiempo existente y también controlan un Resolve remoto, algo que el servidor MCP de Blackmagic aún no hace. El asistente de IA aún puede trabajar en la línea de tiempo abierta mediante el MCP de Resolve.

Con DaVinci Resolve, en ambos sentidos: los videos seleccionados se convierten en una línea de tiempo con subtítulos y marcadores; una línea de tiempo de Resolve entra en la biblioteca y sus videos se analizan.

Independiente: una interfaz web para explorar los análisis, buscar y consultar toda la biblioteca.

Versión para Windows. Este repositorio contiene la aplicación para Windows 11. Se desarrolló y probó con una tarjeta gráfica NVIDIA, que utiliza cuando el modelo de visión deja suficiente memoria (decodificación de video y, opcionalmente, reconocimiento de voz). Sin una, ese trabajo se ejecuta en el procesador, y el modelo de visión se ejecuta en lo que LM Studio admita en tu computadora; otras tarjetas gráficas no se han probado. Una versión para macOS está planificada como un repositorio separado.

Presentación en video, nueve minutos: youtu.be/G0WT96QsGsU; en francés: youtu.be/1EI36bRbdWo.

Esta es la nueva versión de Video Frame Expedition; reemplaza a la anterior.

Tus fotogramas y sonidos nunca salen de tu máquina, excepto, si lo eliges, para ir a LM Studio en otra de tus computadoras; el modelo de visión se ejecuta en tu tarjeta gráfica. Los análisis solo hacen dos llamadas de red (una posición aproximada y una fecha, para encontrar el lugar y el clima), y un interruptor en la página Sistema las desactiva; el mismo interruptor oculta el mapa de OpenStreetMap de la pestaña Contexto, que carga sus mosaicos desde internet. La página de ayuda carga sus fuentes desde Google Fonts y sus videos de presentación desde YouTube (youtube-nocookie.com, solo cuando te desplazas hasta ellos).

Principios

• Local primero: tus fotogramas y sonidos nunca salen de tu máquina. Los únicos datos enviados (coordenadas GPS y una fecha, para el lugar y el clima) se pueden desactivar en la página Sistema, junto con el mapa de la pestaña Contexto.
• Escalado entre modelos: las tareas simples van al modelo local, en tu máquina (analizar los videos, responder una pregunta sobre la biblioteca con ask_library, localizar un sujeto en un fotograma con plan_reframe), y el asistente solo recibe el resultado. El nivel complejo (entender una solicitud, elegir las tomas, editar) pertenece al modelo de frontera (Claude…), que cuesta más. Ya no tiene que mirar cientos de fotogramas ni escribir scripts para Resolve, por lo que usa muchos menos tokens.
• Tus rushes permanecen intactos: lo único que se escribe en tus carpetas de video es un pequeño archivo de análisis por video y por idioma (<name>_FR.txt, <name>_EN.txt; JSON, sin imágenes), que se puede desactivar en la página Sistema. Restaura los análisis sin rehacerlos (base de datos perdida, otra computadora); también contiene la posición GPS y lo que se dice, por lo que compartir la carpeta los comparte también. Cuando creas una línea de tiempo en DaVinci Resolve con subtítulos, cada video también recibe los suyos: <name>_EN.srt (lo que se dice, en el idioma hablado) y <name>_SHOTS_EN.srt (las tomas, en el idioma de la interfaz). Un archivo que la aplicación no escribió, o que cambiaste, nunca se reemplaza.
• El modelo de visión permanece en la GPU: la aplicación usa el modelo que cargaste en LM Studio y nunca lo recarga ni carga otro durante los análisis. Decodifica videos en la GPU solo cuando ese modelo deja suficiente memoria libre (con qwen/qwen3-vl-4b, por ejemplo).
• Elegir tu modelo de visión: la página "Banco de modelos" compara los modelos de LM Studio que marques, en fotogramas de tu biblioteca. Cada uno se carga solo, se consulta como lo hacen los análisis y luego se descarga; una tabla muestra la memoria gráfica usada, el tiempo por fotograma, las respuestas válidas, si las respuestas están en el idioma solicitado, el texto leído y las posiciones, y calificas las descripciones a ciegas. Una clasificación, perfiles y gráficos resumen estas medidas, y un historial guarda cada prueba: la clasificación general compara el último resultado de cada modelo en todas las pruebas. Este es el único lugar donde la aplicación carga un modelo, a tu solicitud; luego recarga el que estaba antes.
• LM Studio aquí o en otro lugar: por defecto, la aplicación habla con LM Studio en esta computadora. La tarjeta "LM Studio" de la página Sistema puede apuntar a otra computadora de tu red local o en Tailscale, una con una tarjeta gráfica más potente. La aplicación prueba esa computadora antes de cambiar y mantiene las conexiones pasadas a un clic. Los fotogramas de tus videos van entonces a esa computadora, y solo a esa.
• Dos idiomas: cada análisis existe en francés y en inglés. Los modelos escriben en un idioma (página Sistema), luego el paso "Traducción" traduce sus textos al otro, sin rehacer nada; la interfaz los muestra y los exporta (archivos, líneas de tiempo, subtítulos) en su propio idioma. Los nombres de archivo terminan con su idioma: _FR, _EN.
• Un análisis terminado se conserva: volver a ejecutar el análisis solo hace lo que falta. "Actualizar" y "Rehacer todo" son opciones explícitas.
• Sonidos, habla y texto en la CPU: YAMNet (sonidos e instrumentos) con una segunda opinión de CED-small ("sonidos escuchados": pájaros, ranas, insectos, lluvia, pasos… con sus marcas de tiempo), Whisper large-v3-turbo (transcripción, en un proceso separado) y PP-OCRv6 (texto en pantalla) se ejecutan en el procesador. Sus modelos se descargan una vez con el script de instalación. Como opción (página Sistema), Whisper puede tomar prestada la GPU cuando el modelo de visión deja suficiente memoria (vfe models cuda-runtime).
• Dónde están los sujetos: una caja alrededor de cada ser vivo (personas, animales, insectos) en los fotogramas clave, posiciones que se pueden reutilizar para reencuadrar (MCP get_object_locations). El modelo de visión ya cargado los encuentra todos, luego D-FINE y YuNet (en la CPU) ajustan las cajas y completan las multitudes. Solo posiciones: nadie es identificado.
• Qué sucede en cada toma: el modelo de visión describe qué sucede en cada toma desde varios de sus fotogramas, en orden (un insecto despegando, una mano agregando un ingrediente), con la hora de cada fotograma. Pestaña de tomas, franja de línea de tiempo y MCP get_shots.
• Encontrar todo de nuevo: la página Búsqueda examina toda la biblioteca por lo que se ve, se dice, se escucha o se lee, por palabras clave y por significado (EmbeddingGemma, en la CPU), con filtros (clima, luz, lugar, fechas, sujetos, encuadre…); un clic abre el video en el momento correcto. MCP search_memory y find_clips (tomas listas para Resolve).
• Hacer preguntas: la página Preguntas responde una pregunta sobre toda la biblioteca con el modelo cargado, citando sus fuentes (un clic abre el video en el momento correcto), con una verificación opcional contra los fotogramas. MCP ask_library.
• Exportar: pestaña Exportaciones de cada video (subtítulos SRT/VTT, tomas como CSV para Excel, capítulos de YouTube, EDL de marcadores, análisis JSON, hoja MANIFEST, script de Resolve) y una tabla CSV de los videos seleccionados. Nada se escribe junto a los videos.
• Crear una línea de tiempo: los videos marcados, de principio a fin, en orden de grabación (u otro orden), como un archivo para importar en DaVinci Resolve (Archivo › Importar › Línea de tiempo) o, cuando Resolve está abierto, directamente en el proyecto actual. Como elijas, la transcripción y las descripciones de tomas se convierten en subtítulos (una pista cada uno), las sugerencias en marcadores de duración y los capítulos en marcadores. La descarga es un ZIP: OTIO para Resolve, FCPXML para Final Cut Pro, archivos SRT y un README.txt. Cuando la línea de tiempo se crea directamente, los subtítulos se colocan en ella (una pista "Transcripción", una pista "Tomas") y también se escriben junto a cada video.

Requisitos

• Windows 11.
• uv, Node.js 24 LTS (la interfaz web se construye en el primer inicio), FFmpeg y ExifTool: scripts/bootstrap.ps1 los instala.
• LM Studio con el servidor local habilitado y un modelo de visión cargado (p. ej. qwen/qwen3-vl-8b), en esta computadora o en otra de tu red (página Sistema, tarjeta "LM Studio").
• DaVinci Resolve Studio 21.1 o posterior, para el enlace con Resolve.

Instalación

1. Obtén la aplicación: git clone https://github.com/VideoFrameExpedition/video-frame-expedition-resolve-windows.git, o el botón "Code › Download ZIP" de GitHub, luego descomprímela.

2. En PowerShell, desde la carpeta de la aplicación:

   powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1
   

   El script usa winget para instalar lo que falta (uv, Node.js, FFmpeg, ExifTool, LM Studio), luego los paquetes de Python de la aplicación y sus modelos (alrededor de 2 GB, descargados una vez; -SansModeles los omite). Acepta los avisos de Windows (UAC). Sus mensajes están en francés.

3. En LM Studio, descarga un modelo de visión (por ejemplo qwen/qwen3-vl-8b), cárgalo e inicia el servidor local.

4. Haz doble clic en run.bat. La primera vez, construye la interfaz web (uno o dos minutos), luego abre el navegador.

Línea de comandos. En esta página, vfe <command> representa el siguiente comando, escrito en PowerShell desde la carpeta de la aplicación:

uv run --frozen --no-dev --project backend python -m vfe_vision <command>

Por ejemplo, vfe doctor verifica FFmpeg, ExifTool, LM Studio y la GPU.

Inicio rápido

Día a día: haz doble clic en run.bat. Inicia la aplicación (interfaz, MCP y análisis) y abre el navegador en http://127.0.0.1:8765.. Si la aplicación ya está en ejecución, simplemente abre la interfaz. run.bat build reconstruye primero la interfaz web después de una actualización. Para detener la aplicación, cierra su ventana.

La página "Ayuda" en la barra lateral es la guía completa: doce partes, las siete pestañas de un video una por una, unas cincuenta capturas de pantalla de la interfaz francesa, con el texto en francés y en inglés. Es el archivo frontend/public/help/index.html, servido en http://127.0.0.1:8765/help/index.html;; la carpeta también se puede alojar en otro lugar tal como está.

El video de presentación (nueve minutos, diez capítulos) está en YouTube y en la página de ayuda; también su versión en francés (ocho minutos), en YouTube y en la página de ayuda en francés. Conexión de asistentes (Claude Code, Claude Desktop, Cursor, VS Code, Codex) y uso de la aplicación desde otros dispositivos mediante Tailscale: página "Conexiones" de la interfaz y guía.

Ajustes leídos al inicio (dirección y puerto, rutas de las herramientas, dirección de LM Studio): copie docs/env.example a un archivo .env junto a run.bat. Todo lo demás se configura en la interfaz.

Desarrollo

Las tareas de desarrollo se gestionan mediante just (winget install Casey.Just); cada receta del justfile también puede ejecutarse manualmente si Smart App Control bloquea just.exe.

just setup      # backend + frontend dependencies, pre-commit hook
just build      # builds the web interface
just serve      # starts the application on http://127.0.0.1:8765

Comando	Función
just dev-backend / just dev-frontend	servidores de desarrollo (API :8765, Vite :5173)
just check	lint, tipado estricto, contratos de arquitectura y pruebas (backend + frontend)
just test-live	pruebas que usan LM Studio, los modelos, la GPU o internet
just gen-client	regenera el esquema OpenAPI y el cliente TypeScript

Edición con Claude Code y DaVinci Resolve

El servidor vfe-vision tiene 25 herramientas. Cuatro de ellas controlan DaVinci Resolve Studio 21.1 en nombre del asistente cuando la casilla "Herramientas de Resolve para el asistente" de la página de Conexiones está marcada (desactivada por defecto). El enfoque:

1. read_timeline lee la línea de tiempo abierta y vincula cada clip con su vídeo analizado, con rangos correctos en segundos; match_clips indica qué contiene cada rango;
2. Claude elige las tomas (find_clips, get_synthesis, get_frames) y solicita get_cut_points puntos de entrada y salida seguros (nunca en medio de una palabra, con J-cuts y L-cuts);
3. plan_reframe prepara el reencuadre para otra relación de aspecto (9:16…): el trabajo de imagen se realiza localmente, mediante el modelo de visión cargado en LM Studio (las respuestas se guardan en caché), y Claude solo revisa las hojas de contacto de las tomas marcadas;
4. build_timeline crea una línea de tiempo nueva "… - vfe vN" con estas tomas y estos reencuadres, lee cada duración y cada valor de vuelta, y apply_markers coloca capítulos, destacados y metadatos. No se modifica ninguna línea de tiempo existente y el proyecto no se guarda: pulse Ctrl+S en Resolve si conserva la edición.

Sin la casilla, Claude escribe los mismos pasos como scripts para el servidor MCP de DaVinci Resolve Studio (match_clips, get_reframe y get_resolve_payload proporcionan los datos; el prompt plan_edit describe este enfoque y lo hace funcionar en una copia de la línea de tiempo), con cortes directos y fundidos encadenados únicamente.

Claude añade una nueva carpeta a la biblioteca (analyze_folder) solo si la página del Sistema lo permite. Todas las herramientas: docs/mcp-tools.md.

Documentación

• Arquitectura
• Herramientas, recursos y prompts del servidor MCP
• Guías de usuario
• Seguridad · Licencias de terceros
• El logotipo

La aplicación se desarrolló en francés. La interfaz, su página de ayuda, esta página y los documentos anteriores existen en ambos idiomas; los mensajes del lanzador y de la línea de comandos están en francés.

Licencia

Gratuita y de código abierto, bajo la Licencia Apache 2.0. Puede usarla, modificarla, integrarla y compartirla, incluso para trabajos remunerados, siempre que conserve el aviso de copyright y el archivo NOTICE. Se proporciona tal cual, sin garantía ni soporte.

Contribuciones

Este repositorio se publica para que la aplicación pueda instalarse y su código pueda leerse. No acepta contribuciones de código: las solicitudes de extracción no se fusionan. Para informar de un error, abra un issue: el formulario solicita la versión de Windows, la tarjeta gráfica, el modelo cargado en LM Studio y el mensaje de error. Para informar de una vulnerabilidad de seguridad, consulte SECURITY.md.