BeaverMakerLab/code-to-video

Code-to-Video Explainer Studio (Motor Universal de Video Animado Basado en Código)

📘 Consulte el manual completo de uso detallado en: README.md (incluye verificación del entorno, guía de 6 estilos, soluciones de locución, montaje multiplataforma del agente y guía de solución de problemas común).

Esta habilidad convierte a cualquier Agente de IA de Codificación (como Claude Code, Codex, DeepSeek Harness, OpenHands/OpenClaw, Antigravity, Cursor, etc.) que tenga capacidades de lectura/escritura de archivos y ejecución de línea de comandos en un director de video profesional, animador programador y productor. Al impulsar el motor de renderizado de video local basado en código, transforma rápidamente cualquier texto, repositorio de código, documento académico o idea creativa en un video explicativo animado de alta definición en 1080p y 60fps con calidad de tinta sobre papel.

---

Tres Reglas de Oro (Todos los Agentes deben cumplirlas estrictamente)

1. Primero aprueba el storyboard, luego escribe el código (Human-in-the-Loop): Sin la confirmación explícita del usuario del storyboard.json, está estrictamente prohibido escribir código de página específico o ejecutar el renderizado final.
2. El tiempo es una función pura $Visual = f(t)$: El código de la página debe ser una función pura de la variable independiente tiempo $t$. Está estrictamente prohibido usar Math.random() (los números aleatorios deben usar PV.rng(seed)), Date.now(), ni transiciones CSS / requestAnimationFrame.
3. Zona de seguridad para subtítulos (Safe Zone): El tamaño del lienzo es 1920×1080. El área inferior $y > 900$ es la zona exclusiva para subtítulos, está estrictamente prohibido colocar cualquier gráfico o texto principal; el área principal de actividad del contenido debe mantenerse dentro de x: 140~1780, y: 180~880.

---

Línea de Producción (Flujo de Trabajo Estándar de Cinco Pasos)

Primer Paso: Digestión del Material y Diseño del Storyboard (Storyboard)

Cuando el usuario solicite la creación de un video (o proporcione material):

1. Establecer la metáfora central: Extraer 1 elemento concreto que recorra todo el video (por ejemplo, para explicar el mecanismo de atención usar un "foco", para explicar un caché usar "notas adhesivas en un escritorio", para explicar una ecuación de fluidos usar "un tanque de agua con tuberías").
2. Planificar la estructura narrativa:
   • Hook (Gancho en los primeros 3 segundos): Plantear una pregunta contraintuitiva o un punto central de dolor.
   • Intuition (Establecer la intuición): Introducir la metáfora central.
   • Mechanism (Análisis del principio): Desglosar la fórmula o pasos centrales.
   • Example & Numbers (Ejemplo y cálculos): Recorrer datos concretos.
   • Close (Cierre y elevación): Responder al gancho inicial, cerrando el círculo.
3. Generar la estructura del storyboard: Generar un esquema del storyboard con 4 a 8 páginas, cada una con id, section, say (resumen del guión) y 2 a 4 beats (puntos de acción específicos con object, action, text, camera).
4. Solicitar confirmación al usuario: Presentar el storyboard al usuario y preguntar: "El esquema del storyboard está listo. Por favor, revise la estructura de cada página y el ritmo narrativo. Confirmado, pasaremos a la fase de dibujo del código."

Consulte las especificaciones detalladas y la plantilla de estructura en: STORYBOARD_RULES.md

---

Segundo Paso: Generación del Guión y la Línea de Tiempo (Script & Narration)

Una vez confirmado el storyboard, establecer script.js:

1. Extraer el diálogo hablado específico de cada página y dividirlo en cues (frases cortas de subtítulos) de no más de 16 caracteres cada una.
2. Usar un motor de voz (puerto local CosyVoice 3 9880, Edge-TTS, o la variable de entorno VOLCENGINE_TTS_API_KEY / ELEVENLABS_API_KEY) para generar el audio de cada frase.
3. Extraer las marcas de tiempo reales de la lectura y asignar a cada cue un punto de tiempo físico (P.c(i) para el inicio, P.cw(i, 'palabra clave') para el momento de coincidencia a nivel de palabra).

---

Tercer Paso: Programación de Animación por Página (Page Drawing Code)

Cada página del video corresponde a un archivo pages/pNN.js, que utiliza la API declarativa del motor:

ENGINE.visual('p01', (P) => {
  P.title('① Intuición del principio central', { accent: 'orange' });
  // Vincular la primera frase del diálogo para desplegar la tarjeta principal
  P.card(200, 260, 700, 480, { title: 'Características de entrada', at: P.c(0) });
  // Al decir una palabra específica, activar flecha y resaltado
  P.arrow(920, 500, 1100, 500, { at: P.cw(1, 'transformación') });
  // Derivación paso a paso de la fórmula matemática
  P.mathDecompose(1140, 400, 600, {
    title: 'Puntaje de atención',
    terms: [
      { latex: 'Q K^T', name: 'Producto de consulta y clave', color: 'blue', at: P.c(2) },
      { latex: '\\sqrt{d_k}', name: 'Factor de escala', color: 'orange', at: P.c(3) }
    ]
  });
});

Consejo: En entornos de agente que admiten subagentes o tareas paralelas, se pueden enviar múltiples subagentes para escribir diferentes páginas de forma concurrente, lo que aumenta la velocidad de generación.
Consulte la sintaxis completa de la API y la lista de componentes en: API.md

---

Cuarto Paso: Bucle de Autocontrol Geométrico y Visual (Automated QA Loop)

Una vez escrito el código, es obligatorio ejecutar la autocontrol, está estrictamente prohibido saltarlo:

1. Ejecutar la herramienta de autocontrol en el directorio del proyecto:

   node engine/tools/check.mjs --only p01
   

2. Procesar la retroalimentación:
   • Si aparece Collision detected o Safe zone overlap:
   • Extraer Fix suggestion: ... de la salida y ajustar directamente las coordenadas en pages/pNN.js usando las sugerencias.
3. Repetir la autocontrol hasta que cada página aparezca en verde (Passed).

---

Quinto Paso: Renderizado sin Interfaz Gráfica Multinúcleo a 1080p (Render)

Una vez que todas las páginas pasen la autocontrol, ejecutar el comando de renderizado paralelo:

# Renderizado panorámico 16:9 a 1080p 60fps (con soporte de aceleración por hardware)
node engine/tools/render.mjs --fps 60 --workers 4 --hw

• La salida se encuentra en <directorio_del_proyecto>/out/:
  • <nombre_del_proyecto>-with-subtitles.mp4 (con subtítulos bilingües precisos)
  • <nombre_del_proyecto>-no-subtitles.mp4 (versión limpia sin subtítulos)
  • Texto de publicación y marcas de tiempo de cada capítulo.

---

Modo de Ejecución Rápida: Producción Automática de un Solo Clic (CLI Run)

Si el usuario desea producir un borrador de video completamente automatizado de extremo a extremo, también puede llamar a la CLI automatizada integrada directamente desde el directorio raíz del proyecto:

# Ejecución completamente automatizada de extremo a extremo (analiza documento -> genera storyboard -> genera páginas -> renderiza el video final)
node apps/cli/dist/cli.js run <ruta_del_archivo_fuente> --style warm-story --duration 60

O, cuando se necesite una vista previa de la línea de tiempo en tiempo real, iniciar el banco de trabajo web:

node apps/cli/dist/cli.js serve

---

Guía de Llamada Multiplataforma para Agentes Universal (Universal Compatibility)

Esta habilidad no está vinculada a ningún entorno de agente específico; solo necesita un entorno Node.js y capacidades de lectura/escritura de archivos:

• Claude Code: Haga referencia a este archivo en CLAUDE.md en el directorio raíz del proyecto para que sea efectivo globalmente, o úselo como un comando personalizado.
• OpenHands / OpenClaw: Coloque el directorio de esta habilidad dentro del proyecto y declárelo en AGENTS.md para que se monte automáticamente.
• DeepSeek Harness / Agentes Propios: Inyecte directamente como System Prompt o Skill Tool Context en el modelo grande.
• Cursor / Windsurf: Active en el diálogo usando @SKILL.md.