openvidstudio

¿Qué hace openvidstudio?

Construye un video demo a partir de la aplicación real en ejecución de un proyecto. Cada pantalla proviene del producto real; nada se genera.

Antes de todo

Ejecuta preflight. Verifica node, ffmpeg, Chromium de Playwright, que la aplicación esté respondiendo, y que exista un motor de narración. Cada fallo nombra la solución. Omitirlo significa que una dependencia faltante aparece después de un render largo.

Si las herramientas no están registradas, el servidor no está instalado. Indica al usuario que lo agregue en su configuración MCP y luego reinicie el cliente:

{ "mcpServers": { "openvidstudio": { "command": "npx", "args": ["-y", "@openvidstudio/mcp-server"] } } }

El orden

preflight -> extract_brand -> plan_beats -> [escribir VO] -> validate_beats -> PUERTA DE APROBACIÓN
  -> write_beats_file -> capture_screenshot -> scaffold_scene -> validate_scenes
  -> [plan_sound_effects] -> generate_narration -> stitch_composition -> contact_sheet
  -> render_video -> qc_extract_frames

1. Recepción

Resuélvelo antes de preguntar. La solicitud habitual es "haz un video demo de este proyecto" y nada más. Ese es el resumen completo, y es suficiente.

Comienza leyendo el repositorio en lugar de entrevistar al usuario:

• README.md dice qué es el producto y a menudo qué es importante de él
• Los scripts de package.json dicen cómo iniciarlo, y el script de desarrollo suele indicar el puerto
• Las rutas o páginas indican qué hay que filmar

Luego inicia la aplicación tú mismo y confirma que responda. No le pidas al usuario una URL que tenga que buscar; encuentra el comando de desarrollo, ejecútalo y verifica. Pregunta solo si iniciarlo necesita algo que no puedas saber, como un .env faltante o una base de datos que no esté levantada.

Lo que realmente vale la pena preguntar, porque el repositorio no puede decirlo:

• cuánto debe durar el video
• qué dos o tres cosas debe mostrar, si el repo tiene muchas
• para quién es, un visitante de la página de inicio o alguien que ya está instalando

Una pregunta a la vez, y solo preguntas que el repositorio no pueda responder. Un muro de seis preguntas al inicio es la forma más rápida de hacer que esto parezca trabajo. docs/PLANNING.md tiene el árbol de decisión completo si un caso no está claro.

Termina el trabajo mostrando el resultado: la ruta del mp4, su duración y un contact_sheet o algunas imágenes de qc_extract_frames. Un render que nadie mira no es un video entregado.

1b. Usa la marca del repositorio

extract_brand con sourceRepo configurado al repositorio que se está filmando. Lee bloques @theme de Tailwind v4 y propiedades personalizadas :root, elige fuentes de las importaciones de next/font, copia el mejor logo que encuentre, y escribe src/brand.ts.

Ejecútalo antes de scaffold_scene. Un video tematizado después del hecho significa volver a andamiar.

Revisa la lista unresolved que devuelve y completa manualmente cualquier cosa que sea importante. Reporta solo lo que realmente puede encontrar, sin inventar un color plausible, por lo que un token no resuelto es una brecha real, no un fallo.

Una regla que esto impone en las escenas escritas a mano: lee los tokens dentro del componente, no en el ámbito del módulo. applyBrand muta los objetos de token compartidos, por lo que const MONO = \"${font.mono}"`al inicio de un archivo captura el valor predeterminado y nunca ve la marca. UsamonoStack()yuiStack()` en su lugar.

2. Planificar los beats

plan_beats con la duración objetivo y las características. Devuelve un esqueleto contiguo con un método de captura y un presupuesto de palabras por beat.

Escribe la narración ajustándote a ese presupuesto. validate_beats exige de 2.3 a 2.9 palabras por segundo como un piso y techo estrictos por beat, por lo que una línea puede ser rechazada por ser demasiado escasa. Escribir con el número indicado evita el viaje de ida y vuelta.

Cada beat screenshot también necesita visual.url y visual.interactions (un array, posiblemente vacío). Ningún otro documento lo establece de antemano.

3. La puerta de aprobación

Muestra al usuario el archivo completo de beats, no un resumen, y espera un "sí" explícito. Nada se escribe en disco antes de eso. Esta es una regla del protocolo, no una sugerencia, y es el punto donde un video incorrecto cuesta una frase en lugar de una hora.

Luego write_beats_file.

4. Captura

capture_screenshot por cada beat de captura de pantalla. Compensa una desincronización de zoom de Chrome por origen que de otro modo produce capturas pequeñas, suaves o mal encuadradas.

Pasa una interacción wait si la página tiene animaciones de entrada, o la toma las captura a medio vuelo y se ve rota en lugar de claramente incorrecta.

5. Escenas

scaffold_scene por beat. Emite una escena que se renderiza tal cual, usando su propia copia y duración. Edita el contenido; no reconstruyas la estructura.

Luego validate_scenes. Detecta el fallo que se renderiza con éxito y simplemente está mal: el contenido dispuesto al ancho total del escenario se recorta una vez que la cámara se acerca, porque el área visible es el escenario dividido por la escala de la cámara. También señala cámaras estáticas, activos faltantes y beats sin narración.

Lee docs/API.md para las propiedades. No leas el código fuente de la biblioteca.

6. Narración

generate_narration. Escribe un clip por beat donde stitch_composition busca, y limita el estiramiento temporal a un rango que se mantenga natural en lugar de ajustar los clips a los beats a cualquier costo. Cuando dice que un beat no encaja, corrige el guion o la duración del beat; no estires más.

6b. Sonido, solo si los incorporados no lo cubren

El paquete sintetizado ya incluye clics, pulsaciones de teclas, una campana, un bip, un tono de éxito, un whoosh y una base musical, y no tiene derechos de terceros porque ffmpeg lo genera. Prefiérelo.

Si el video realmente necesita algo más, pregunta al usuario qué sonidos quiere, luego plan_sound_effects con una entrada por sonido. Te dice qué solicitudes ya cubren los incorporados y devuelve un enlace de búsqueda de Pixabay más una ruta exacta de guardado para el resto.

No descarga desde Pixabay, y tú tampoco deberías hacerlo. Los términos de Pixabay prohíben la recolección automatizada y dicen que la API es para solicitudes humanas reales, y no publican un endpoint de efectos de sonido. El usuario descarga; tú verificas. Vuelve a llamar a la herramienta con verify: true después para confirmar que cada archivo es audio real y normalizar los formatos.

provider: "freesound" obtiene automáticamente en su lugar, pero solo con el token API propio del usuario, y cada clip que toma se registra en ATTRIBUTION.md. Cualquier cosa en ese archivo debe llegar a la descripción del video o se viola la licencia.

La música es la excepción a todo eso. find_music_bed busca en dos catálogos de dominio público CC0 (~9,400 pistas) e import_music_bed recorta, desvanece y empareja el volumen de la pista que el usuario elija en public/audio/music-bed.mp3. Nada de eso necesita atribución. La habilidad bgmusic tiene el detalle; úsala cuando las bases musicales sintetizadas sean demasiado simples para un lanzamiento o pieza promocional.

7. Ensamblar y verificar

stitch_composition, luego contact_sheet antes de renderizar. La hoja de contacto son dos fotogramas por beat en una sola imagen y toma una fracción de un render completo, lo cual es importante porque un video de cinco minutos son 9000 fotogramas.

render_video con draft: true primero. Calidad completa solo una vez que el borrador se vea bien.

Luego qc_extract_frames y revisa la lista de verificación de docs/PIPELINE.md.

Reglas que fallan en QC

De docs/STYLE.md, reexpresadas porque son las que más a menudo se rompen:

• Sin easing lineal. Usa los ajustes preestablecidos E.*.
• Cada escena dentro de CinematicScene.
• El movimiento nunca se detiene. Un fotograma estático es un fallo.
• Sin guiones largos (em dash), ni en pantalla ni en la narración.
• Los subtítulos van en overlay, no en children, o se desvían de la pantalla mientras la cámara se mueve.
• Capturas de pantalla solo dentro de BrowserFrame. Las grabaciones y clips de IA no deben estarlo, o el metraje generado adquiere la firma visual de una captura real.

Qué no afirmar

La interfaz de usuario real del producto, ya sea renderizada por DOM, capturada en pantalla o grabada, es la verdad fundamental. Los clips generados por IA son solo atmósfera y nunca llevan texto del producto. Si la narración afirma algo, el visual debe mostrarlo; si no puede, reescribe la línea.