pranav7/video-explicadores

Video explicador

Crea un video explicativo narrado, estilo 3Blue1Brown, sobre cualquier tema. Los elementos visuales se generan con Manim (Community Edition). La narración usa Kokoro-82M, un modelo local de texto a voz sin necesidad de clave API. Cada línea de narración establece el tiempo de la animación que la acompaña.

El trabajo tiene dos partes:

1. Tú escribes script.md: cada línea de narración y lo que se muestra en pantalla mientras se reproduce. Tú tienes el contexto, así que escribes el guion.
2. Un subagente construye el video a partir de script.md. Escribe las escenas, las renderiza, verifica el diseño y genera el render final.

La construcción realiza aproximadamente 20 llamadas a herramientas, y cada llamada envía el contexto completo nuevamente. Un subagente nuevo tiene un contexto pequeño, por lo que la construcción es más económica y rápida allí. El subagente también se ejecuta en segundo plano, para que el usuario pueda seguir trabajando contigo.

El comando explainer hace el resto del trabajo. Debe estar en el PATH. Para la configuración, consulta https://github.com/pranav7/video-explainers. Ejecuta explainer -h para los comandos.

0. Configuración (una vez por máquina)

Ejecuta explainer doctor. Instala paquetes de Homebrew, fuentes, TinyTeX, un entorno Python y los iconos, luego prueba Kokoro y LaTeX. Es seguro ejecutarlo de nuevo. Ejecútalo si un comando falla por una dependencia faltante.

1. Planificación

• Dónde. Si la conversación trata sobre un proyecto que tiene su propia carpeta para documentos, coloca el video en una carpeta videos/<slug>/ dentro de ella. De lo contrario, usa ~/Movies/explainers/<slug>/.
• Audiencia y duración. Pregunta solo si la solicitud no los deja claros. Valor predeterminado: un adulto curioso sin conocimientos previos sobre el tema, de 2 a 4 minutos.
• Longitud del guion. Kokoro habla aproximadamente 170 palabras por minuto, por lo que un video de 3 minutos tiene aproximadamente 500 palabras de narración. Escribe un capítulo por cada 30 a 45 segundos.

Elige la forma que se ajuste al tema.

Para un concepto (un algoritmo, una idea en matemáticas o ciencias):

1. Comienza con una pregunta o acertijo concreto, no con una definición.
2. Construye intuición con un ejemplo específico que el espectador pueda ver.
3. Generaliza, y solo entonces muestra la fórmula. La fórmula nombra lo que ya vieron.
4. Termina con la idea clave en una sola imagen.

Para una situación (una ejecución que falló, un incidente, un diseño, una puesta al día):

1. Comienza con lo que sucedió, con los números reales.
2. Muestra el mecanismo que lo causó, paso a paso.
3. Muestra lo que cambia: la solución, la decisión o el siguiente paso.
4. Termina con una imagen de todo el sistema con el cambio implementado.

2. Escribir script.md

Escribe script.md en el directorio del video, con este formato:

# Por qué la página de pedidos es lenta

Para ingenieros del equipo. Aproximadamente 3 minutos.

## Paleta

| Concepto | Color |
| --- | --- |
| El servidor API | CIELO |
| La base de datos | VIOLETA |
| Trabajo lento y perdido | CORAL |
| La solución | MENTA |

## 1. Gancho: Cincuenta pedidos, cincuenta consultas

- "La página de pedidos tarda cuatro segundos en cargar cincuenta pedidos."
  - Una tarjeta de navegador con "4.1 s" en coral, y una lista de 50 etiquetas de pedidos.
- "El servidor pregunta a la base de datos una vez por cada pedido."
  - Una tarjeta de servidor API y una tarjeta de base de datos. Paquetes viajan entre ellas, uno por pedido.

Cada encabezado de capítulo es ## <número>. <NombreEscena>: <título del capítulo>. El constructor crea una clase de escena para cada capítulo. Los títulos de los capítulos se convierten en marcadores de capítulo en el video.

El constructor no puede ver esta conversación. Coloca todos los nombres, números, etiquetas y valores que aparecen en pantalla en el guion.

La narración se lee en voz alta exactamente como está escrita:

• Escribe la forma hablada: "x al cuadrado", "dos pi erre", "número de orden", "v dos". No pongas LaTeX, símbolos ni código en la narración.
• Escribe una oración por línea, como máximo dos. Cada línea es un cambio visual.
• Si Kokoro pronuncia mal una palabra, da sus fonemas en línea: [Kokoro](/kˈOkəɹO/).
• La voz predeterminada es af_heart. Si al usuario le importa la voz, ejecuta explainer voices y déjalo escuchar (afplay voice-samples/<name>.wav).

Debajo de cada línea, describe la imagen, no una diapositiva. Nombra los objetos, qué muestran y qué se mueve. Dale a cada concepto un color de la paleta.

Toma los colores de la paleta de los acentos del kit: CIELO, MENTA, ÁMBAR, CORAL, VIOLETA, AGUA, ROSA, MELOCOTÓN, LIMA. El kit también tiene neutros para cosas que no son un concepto: SUTIL, TENUE, TINTA. El kit tiene tarjetas, etiquetas, tablas, ventanas de código, tuberías, diagramas de secuencia, líneas de tiempo, árboles, llamadas, gráficos, números grandes e iconos de Lucide. Describe imágenes que los usen.

Muestra cada número tal como es. No pidas un número que cuente desde cero.

3. Transferir la construcción

Inicia el constructor como un subagente. Si tus instrucciones nombran un tipo de agente o un modelo para el trabajo de construcción, úsalos. Dale este mensaje:

Construye el video explicativo para <directorio>/script.md. Ejecuta `explainer guide` y
síguelo. Informa la ruta del video, su duración y cada advertencia de diseño que
hayas dejado, con el motivo.

Si el usuario solicitó subtítulos, agrega "Renderiza con --captions." al mensaje.

Informa al usuario que el video está en progreso y luego continúa con otro trabajo. Si no puedes iniciar un subagente, ejecuta explainer guide y realiza sus pasos tú mismo.

4. Entrega

Cuando el constructor informe, abre <directorio>/video.mp4 (en macOS, open). Dile al usuario:

• La ruta del archivo y la duración.
• El video tiene marcadores de capítulo.
• Cualquier problema que el constructor haya dejado abierto.

Pregunta qué cambiar. Para hacer un cambio, envíalo al mismo constructor si tus herramientas pueden enviarle un mensaje, porque el constructor mantiene su contexto. De lo contrario, inicia un nuevo constructor con el cambio. Si el cambio afecta la narración, edita primero script.md.