Video Agent Runtime

Edición de vídeo nativa para agentes, construida sobre planes duraderos, versiones revisables y renderizado determinista.

Edita vídeo como datos estructurados, no como comandos de shell opacos.

Inicio rápido · Agente y MCP · Voz y habla · Móvil · Documentación · Benchmarks

¿Qué es?

Video Agent Runtime es un motor de edición sin interfaz gráfica para agentes como Claude Code, Codex o cualquier cliente compatible con MCP.

En lugar de permitir que un modelo genere directamente comandos de FFmpeg, convierte el material multimedia en datos de proyecto duraderos:

Transcript → EditingStrategy → EditPlan / EditPatch → Timeline → Version → Preview → Approval → Export

El modelo decide qué debería cambiar. El runtime valida si ese cambio está permitido, lo aplica de forma transaccional, renderiza el resultado y mantiene cada mutación revisable y reversible.

Está diseñado principalmente para vídeos de persona hablando, entrevistas, podcasts, conferencias, grabaciones de pantalla y flujos de formato largo a formato corto.

[!NOTE] Esto no es un NLE de escritorio y no intenta reproducir Premiere o CapCut. La interfaz principal es un agente, CLI, cliente MCP o host móvil orientado a la revisión.

Related MCP server: video-editor

Cómo funciona

flowchart LR
    A[Source video] --> B[ASR + visual evidence]
    B --> C[Transcript / Timeline context]
    C --> D[LLM proposes EditingStrategy]
    D --> E{User approves?}
    E -- no --> D
    E -- yes --> F[Structured EditPlan]
    F --> G[Validate + Diff + Apply]
    G --> H[Immutable Version]
    H --> I[Preview render]
    I --> J{Review}
    J -- feedback --> K[EditPatch or Replan]
    K --> G
    J -- approve --> L[Final export]

Una interacción típica se ve así:

Import interview.mp4
↓
"剪成一分钟，开头抓人，删掉废话"
↓
Agent proposes a hook-first strategy
↓
User approves
↓
Runtime validates and applies an EditPlan
↓
Preview
↓
"前 20 秒还是太慢"
↓
Minimal EditPatch → new Version → new preview
↓
Final approval → export

Capacidades principales

Voz y habla

El habla es un subsistema de edición de primera clase, no un complemento de subtítulos. ASR produce el timeline semántico utilizado por el editor; las salidas de TTS y VoiceProfile se convierten en activos explícitos del proyecto y clips del timeline.

ASR

TTS e identidad de voz

La clonación de voz nunca es automática. Un VoiceProfile clonado requiere evidencia de autorización explícita, una referencia verificada por calidad y—donde el proveedor lo admita—un rango de referencia exacto respaldado por transcripción. El material multimedia con varios hablantes no se adivina en silencio.

El código de los modelos, los pesos, los activos de voz y las API alojadas pueden tener licencias o términos comerciales diferentes. Consulta investigación de modelos de voz e identidad de voz antes de implementar una configuración de proveedor.

Agente y MCP

Todas las superficies públicas son adaptadores delgados sobre el mismo VideoAgentCore; no mantienen modelos de proyecto o timeline separados.

Conectar Claude Code / Codex

Compila el repositorio y luego apunta un cliente compatible con MCP al servidor stdio:

npm install
npm run build

mcp.example.json contiene una forma de configuración mínima. Los secretos del proveedor se leen del entorno o del almacenamiento seguro del host y nunca se escriben en el JSON del proyecto.

Inicio rápido

Requisitos

• Node.js 22+

• FFmpeg / FFprobe para renderizado de medios reales

• Entorno Python opcional para modelos de voz locales

Instalar y verificar

npm install
npm run typecheck
npm test
npm run build
npm run smoke:mcp
npm run demo

npm run demo crea material fuente sintético localmente y ejecuta el flujo de trabajo real del proyecto a través de transcripción → estrategia → versiones → vistas previas → parche de retroalimentación → narración → exportación final con FFmpeg.

Comprueba la máquina actual sin hacer una llamada de modelo de pago:

npm run cli -- doctor

Configurar proveedores

Copia los valores relevantes de .env.example a tu entorno.

# Workspace
VIDEO_AGENT_WORKSPACE=./video-projects

# Planner
VIDEO_AGENT_PLANNER=openai
OPENAI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=...

# Local ASR example
VIDEO_AGENT_ASR=qwen3-asr
VIDEO_AGENT_ASR_MODEL=Qwen/Qwen3-ASR-0.6B

# Local TTS / voice example
VIDEO_AGENT_TTS=qwen3-tts
VIDEO_AGENT_TTS_MODEL=Qwen/Qwen3-TTS-12Hz-0.6B-Base
VIDEO_AGENT_PYTHON=python

Otras opciones compatibles están documentadas directamente en .env.example.

Validación con proveedores reales

La CI normal no descarga intencionalmente modelos de voz grandes ni usa credenciales de pago. Los proveedores reales se verifican mediante un arnés de aceptación explícito:

VIDEO_AGENT_REAL_ACCEPTANCE=true \
VIDEO_AGENT_ASR=qwen3-asr \
VIDEO_AGENT_PLANNER=openai \
VIDEO_AGENT_TTS=qwen3-tts \
OPENAI_API_KEY=... \
npm run eval:speech-real

El arnés registra la latencia real de cada etapa, el factor de tiempo real de ASR/TTS, los metadatos del proveedor/modelo, el RSS del controlador Node y la memoria GPU aproximada cuando está disponible. La aceptación de clonación de voz autorizada debe habilitarse por separado y no puede ejecutarse silenciosamente contra un hablante arbitrario.

Después de varias ejecuciones, agrega resultados comparables con:

npm run benchmark:speech-summary

Consulta aceptación de voz real, benchmarks e investigación de modelos de voz.

Host móvil

El objetivo móvil está diseñado en torno a una arquitectura local-first, sin servidor de aplicaciones:

Mobile App
  ├── VideoAgentCore
  ├── durable ProjectRepository
  ├── Workflow / Job Queue
  ├── Timeline / EditPatch / Version
  ├── native media adapters
  └── direct BYOK provider access when configured

El material fuente permanece en el dispositivo por defecto; los proveedores remotos reciben solo el ContextPack/evidencia aprobados necesarios para la inferencia. Las credenciales de API se referencian a través del almacenamiento seguro del host en lugar del JSON del proyecto.

[!WARNING] La implementación actual de iOS/Android sigue siendo un prototipo de host nativo a nivel de código fuente. Los contratos de TypeScript/móvil se verifican en CI, pero las compilaciones nativas de Xcode/Gradle, la corrección de medios en dispositivos físicos, el comportamiento térmico y la fiabilidad de la exportación en segundo plano aún requieren la pasada de validación de dispositivos documentada.

Comienza en docs/mobile/README.md y estado del host nativo.

Arquitectura

                 Agent / CLI / MCP / Mobile
                          │
                          ▼
                    VideoAgentCore
                          │
        ┌─────────────────┼──────────────────┐
        ▼                 ▼                  ▼
     Workflow          ProjectStore       Job Queue
        │                 │                  │
        └──────────┬──────┴──────────┬──────┘
                   ▼                 ▼
              Edit / Timeline    Provider contracts
                   │                 │
             Version / Diff     ASR / LLM / TTS
                   │                 │
                   └────────┬────────┘
                            ▼
                         Renderer
                            │
                         Preview
                            │
                      Review / Export

El invariante principal es simple: el runtime posee el estado; los modelos proponen cambios estructurados.

Para los límites de paquetes, el diseño de persistencia y la semántica de recuperación, lee architecture.md.

Documentación y desarrollo

El README es el punto de entrada del producto. Los detalles técnicos viven en docs/.

Estado del proyecto

El runtime de Node es la ruta principal verificada: CLI, MCP, estado de proyecto duradero, renderizado con FFmpeg, trabajos, evaluación determinista, adaptadores de proveedores de voz y herramientas de aceptación con proveedores reales están implementados y cubiertos por CI donde no requieren pesos de modelos externos o credenciales de pago.

La calidad real del modelo local, la latencia, la VRAM y el comportamiento del modelo alojado deben medirse aún en la máquina de destino mediante el arnés de aceptación opcional; el CI no finge que esas ejecuciones ocurrieron.

El host móvil sigue siendo un prototipo a nivel de código fuente hasta que se completen la compilación nativa y la validación en dispositivos reales.

Principios de seguridad

• Los agentes nunca reciben ejecución arbitraria de shell a través de la API de edición.

• Las cadenas FFmpeg sin procesar no son estado de edición autoritativo.

• Las claves de API nunca se persisten en el JSON del proyecto, los registros de ProviderCall ni los informes de referencia.

• El material de origen permanece local a menos que un flujo de trabajo autorice explícitamente la evidencia remota.

• La clonación de voz requiere autorización explícita y procedencia.

• Las capacidades no compatibles del renderizador/proveedor fallan explícitamente en lugar de degradarse silenciosamente.

Consulte docs/security.md para conocer el límite completo.

Licencia

MIT. Consulte LICENSE.