jjietay/kaleidoscope

Video explicativo

Creas un video que ayuda al usuario a aprender un concepto. Tienes una gran ventaja sobre una herramienta nueva: conoces esta conversación y este proyecto. Usa ese conocimiento.

El motor está en ~/.claude/skills/kaleidoscope/engine/. En este archivo, make significa:

node ~/.claude/skills/kaleidoscope/engine/make.mjs <comando> <directorio-del-proyecto>

Paso 0: pregunta primero (cada vez que la habilidad se inicia)

Ya sea que el usuario haya escrito /kaleidoscope o haya pedido un video en palabras, lo primero que haces es hacer las siguientes preguntas con AskUserQuestion, con opciones cliqueables. Omite cada pregunta que el mensaje del usuario o esta conversación ya responda (por ejemplo, "como un noticiero" responde al estilo, y "con música lo-fi" responde a la música). Pon la opción recomendada primero y márcala como "(Recomendado)". Haz las cuatro preguntas en una sola llamada (la herramienta acepta hasta 4). Si el tema en sí no está claro y no se omite ninguna pregunta, pregunta primero sobre el tema, en su propia llamada.

Pregunta	Encabezado	Opciones (primera = predeterminada)
¿Qué estilo debe usar el video?	Estilo	Arcilla 3D: un estilo suave de arcilla, con la mascota silenciosa haciendo el trabajo · 2D clásico, mixto: un estilo 2D diferente para cada parte · 2D clásico, un estilo: el usuario lo nombra (noticiero, pizarra, ...)
¿Para quién es el video y de qué duración?	Espectador	Repaso de examen, estándar: la notación de la clase, números trabajados, trampas de examen, 5 a 6 min · Repaso de examen, profundo: lo mismo, 8 a 9 min, cada paso de la derivación · Principiante, corto: intuición primero, menos símbolos, 2 a 4 min · (Otro: el usuario nombra un espectador y una duración, por ejemplo "repaso para expertos, corto")
¿Cuándo debo consultarte?	Punto de control	De una sola vez: vuelve con el video terminado · Después del storyboard: muestra el plan y espera aprobación · Después del primer vistazo: muestra los primeros fotogramas y espera
¿Qué música?	Música	Tranquila (current): pad suave, sin ritmo · Lo-fi (lofi): ritmo ligero, más energía · Ninguna

Pon una opción recomendada primero cuando la conversación sugiera una (un examen la próxima semana: Repaso de examen, profundo). Si el mensaje responde solo a la mitad de la pregunta del espectador (por ejemplo "para mi examen"), mantén la pregunta y ofrece solo las opciones que coincidan con esa mitad. Los espectadores son repaso de examen, principiante y repaso para expertos (rápido y denso); las duraciones son corta (2 a 4 min), estándar (5 a 6 min) y profunda (8 a 9 min). Escribe las respuestas en video.json en el paso 4: "_look" (clay o classic), "_brief": { "viewer": ..., "length": ..., "checkpoint": ..., "style": ... } y "_render": { "music": "current" | "lofi" | false }. Cada paso posterior, y una reconstrucción, los lee allí y no vuelve a preguntar. Si el usuario descarta las preguntas, usa la primera opción de cada una.

De una sola vez, a menos que el usuario haya elegido un punto de control

Después del paso 0, haz cada paso siguiente sin detenerte, y vuelve solo con el video terminado y revisado. No preguntes "¿continuo?", no muestres borradores, no esperes entre pasos. Cada verificación a continuación es tuya para ejecutar y actuar. Las únicas paradas son el punto de control que el usuario eligió: "Después del storyboard" se detiene después del paso 7 (muestra el storyboard y el veredicto del agente de guion, luego espera), y "Después del primer vistazo" se detiene en el primer make look del paso 9 (muestra sus imágenes, luego espera).

El estilo que el usuario quiere (léelo antes del paso 6)

Arcilla para cosas que actúan, Manim para gráficos, y la mascota está en cada video. Lee styles/clay.md. El usuario eligió el estilo de arcilla sobre la mezcla de estilos antiguos para mantener consistencia entre videos. Los estilos 2D son un estilo clásico opcional; consulta la sección a continuación.

• No fuerces un gráfico en arcilla (el usuario lo pidió). Cuando una imagen 2D de Manim ayude al espectador a entender más que la arcilla (una curva, una distribución, un contorno, una proyección u otra geometría en un plano), haz esa parte como una parte de Manim, sobre el fondo oscuro de Manim (styles/math-manim.md). Nunca construyas un modelo de arcilla que copie una curva matemática: el usuario hizo eliminar esas. Los objetos que actúan, y el trabajo físico de la mascota, permanecen en arcilla. Un video puede pasar de una parte de arcilla a una parte de Manim y volver, con el mismo color para la misma cosa.

• Un estilo, muchas partes. El video se divide en partes de aproximadamente 15 a 40 s (gancho, cada idea, tu caso, cierre). Cada parte tiene su propio fondo, cámara y escenario. Una al lado de la otra, dos partes nunca comparten un fondo.

• La mascota hace el trabajo. Es silenciosa, sin sincronización de labios, y el narrador es una voz en off. Camina, tira, empuja, carga y apaga cosas con sus propias manos, por lo que una fuerza en el guion es algo que el espectador la ve hacer. El usuario pidió esto después de un video donde solo se quedó parada y observó. Por defecto mantiene una expresión inexpresiva, y make check ADVIERTE cuando se queda en un solo lugar.

• Las cosas deben conectarse. Un resorte llega a su pared, un alfiler toca su mapa, una mano toca lo que sostiene. El usuario encontró un resorte que no llegaba a su pared después de que todas las verificaciones hubieran pasado. make bake mide cada unión en models.js (JOINS), así que agrega nuevas uniones allí, y busca contacto en las imágenes fijas.

• Solo nuestros propios modelos. Usa el kit en styles/library/clay. Nunca descargues un modelo. Si un video necesita un nuevo objeto, agrégalo al kit con el mismo estilo.

• Cada parte es una toma continua. Dentro de una parte no hay cortes ni nuevas diapositivas: los objetos llegan, se mueven y se unen mientras la voz habla, y la cámara se mueve lentamente. Una parte termina en el estado en el que comienza la siguiente, o con un fundido en el fondo de la siguiente parte.

• La imagen explica; el texto solo nombra. El texto permanece plano y nítido, en HTML sobre el 3D. Por fotograma: un antetítulo (mayúsculas pequeñas, la parte y una fuente), un título de máximo 8 palabras, algunas etiquetas de 1 a 4 palabras cada una con líneas finas de conexión, y como máximo una línea de leyenda en la parte inferior. Nunca una columna de oraciones, nunca una lista con viñetas, nunca una leyenda de lo que significan los colores. Máximo unas 15 palabras en pantalla.

• Las fórmulas representan la voz (el usuario lo pidió). Una fórmula fija no es mejor que leer notas. Construye cada una con eqn(): los términos llegan cuando se dicen, se mueven cuando la voz los mueve, golpean y estallan cuando dice cancelar, y rebotan solo cuando nombra algo importante. make look da una falla para una fórmula que permanece quieta, y para una oración de "cancela" sin cancelación en pantalla. Consulta styles/clay.md.

• Movimiento físico. Las cosas se mueven como objetos: un brazo se extiende, una pelota cae y rebota, un bloque cae y se asienta, un pulso viaja. Sin acumulación de cajas estáticas.

• El mismo objeto mantiene su color en cada video (el robot siempre es naranja, el mapa siempre amarillo).

Si un storyboard rompe una de estas reglas, cambia el storyboard antes de escribir código.

Reglas estrictas

• Haz el pensamiento aquí, en la conversación principal. Escribes el guion, el storyboard y las escenas tú mismo, porque el contexto está aquí. Nunca delegues esos pasos a un subagente: un subagente comienza sin contexto. El agente de guion en el paso 7 es la única excepción, y comienza frío a propósito.
• Nunca apresures la explicación central. El usuario aprende de estos videos. Sigue las reglas de ritmo en reference/script.md y corrige cada ADVERTENCIA de ritmo.
• Nunca inventes un hecho. Cada número, fórmula y afirmación proviene de una fuente que verificaste: el código del usuario, una hoja de datos, una especificación, un artículo, la documentación. Lístalos en storyboard.md. Informa cualquier cosa que no hayas podido verificar.
• "Tu caso" es opcional. Agrégalo solo cuando esta conversación o proyecto realmente tenga un ejemplo que coincida (un error que el usuario encontró, una corrección, un número medido). Nunca inventes uno.
• Sin superposiciones. Ningún visual puede cubrir a otro: texto sobre texto, texto sobre un gráfico, o un gráfico que oculta otro gráfico. Cada etiqueta, fórmula, flecha y objeto tiene su propio espacio. check ADVIERTE sobre textos superpuestos, y review escribe cada superposición medida en overlaps.md. La saturación es a criterio del usuario, así que búscala en los fotogramas a tamaño completo. La pasada de ID ayuda: make look agrega una imagen de los espacios más ajustados, y ADVIERTE sobre texto a menos de 12 px de otra cosa, texto sobre un dibujo, bajo contraste de texto y un modelo que otros ocultan. Corrige cada superposición antes de make final.
• Los subtítulos tienen una línea. Cada señal tiene como máximo 42 caracteres y no hay dos señales que se muestren al mismo tiempo, por lo que un reproductor nunca muestra dos líneas. El motor hace esto; verify informa una señal que rompe la regla. No cambies SUB_MAX en make.mjs para que quepa una señal.
• El bucle cerrado (el usuario lo pidió, y el motor lo impone). Después de cada edición: make look, lee cada imagen que enumera, corrige lo que ves, y mira de nuevo. Solo entonces construye. Nunca edites y construyas a ciegas, porque una construcción es larga y una mirada toma segundos. Cada imagen tiene un dígito de VERIFICACIÓN en su esquina superior derecha, y las puertas se abren solo con los dígitos de todas las imágenes, en orden:
  1. Edita. Si cambiaste script.md, ejecuta make voice. Si el video tiene partes de Manim y cambiaste manim_scenes.py o la voz, ejecuta make manim: make look dibuja los fotogramas de Manim, no los crea.
  2. make look <dir>: mide cada escena cambiada en cada fotograma, y dibuja sus fotogramas cercanos y sus partes móviles. Léelos todos. Luego make look <dir> --ok <dígitos>. make build se detiene sin esto.
  3. make build <dir>. Se detiene ante cualquier colisión.
  4. Lee cada tira en build/review/moving.md. Luego make look <dir> --moving-ok <dígitos>.
  5. make final <dir>. Se detiene si la fuente cambió después de la mirada o la construcción, o si hay una colisión o superposición abierta. Ejecuta cada paso como su propio comando, detente en el primer fallo, y confirma que se aplicó una edición.
• Cada lector revisa fotogramas cercanos y partes móviles. Cualquier agente o sesión que juzgue un video lee los fotogramas cercanos de cada parte editada, y todos los fotogramas de cada cosa que se mueve: la mascota y los objetos, durante todo su movimiento. Una muestra del video no cuenta: una mano atravesó una mesa entre los fotogramas muestreados.
• Una nueva falla obtiene una barrera de protección. Cuando el usuario encuentre una falla, primero agrégala a reference/faults.md y a engine/test/selftest.mjs, y confirma que la prueba falla en ella. Luego corrige el video. No solo corrijas el video. Ejecuta make selftest después de cada cambio en una verificación.

Lo que el usuario pidió (mantén esto)

Cada uno fue solicitado o elegido auditivamente. El motor hace la mayoría automáticamente.

Tema	Qué	¿Automático?
Voz	Voz incorporada de Chatterbox, ralentizada a aproximadamente 160 palabras por minuto por engine/tts/slow-reference.wav; cada párrafo leído de una vez para que el tono se mantenga	sí
Pausas	cada punto exactamente 0.6 s, cada coma como máximo 0.3 s, establecidas desde la puntuación del guion	sí; voice ADVIERTE si no se pudo colocar una pausa
Tomas malas	una parte cuyas palabras difieren del guion (verificación de Whisper) se retoma con una nueva semilla, hasta 3 veces; se conserva la mejor toma	sí; ADVIERTE si aún está mal
Partes rápidas	una cláusula más de 1.3 veces el ritmo habitual del video (las palabras de símbolos cuentan doble) se retoma; el usuario encontró "lambda v es v, escalado por lambda" demasiado rápida	sí; ADVIERTE "rápido": dale su propia oración corta y un [pause]
Números negativos	lee "negativo", nunca "menos"	voice se detiene con un ERROR
Palabras repetidas	"uno uno" obtiene una coma ("uno, uno"), o la voz se desliza	sí
Escritura	párrafos conectados; [pause] solo donde termina una idea o se reproduce una animación. Rechazado: una pausa después de cada oración, oraciones entrecortadas, una voz rápida, una voz estirada (amortiguada), Kokoro	tú, consulta reference/script.md
Música	audible, constante, aproximadamente 13 dB por debajo de la voz (musicVolume 0.37; el usuario la subió 3 dB desde 0.26), atenuación suave; dos pistas aprobadas, current (predeterminada) y lofi. Rechazado: bombeo fuerte-suave, música demasiado suave para oír, otras 4 pistas	sí; tú eliges la pista, consulta SOUND.md
Efectos de sonido	el kit en engine/sfx.mjs, aprobado auditivamente; el whoosh de entrada 4 dB por debajo de los otros acentos (el usuario lo encontró un poco demasiado alto). Activado para videos nuevos (_render.sfx: true), desactivado para los antiguos	tú agregas s.sfx en las señales; el motor los mezcla
Audio	48 kHz estéreo	sí; verify lo verifica
Subtítulos	suaves, nunca incrustados; el mpv del usuario los muestra pequeños (sub-scale=0.7)	sí
Una línea de subtítulos	una línea por señal, máximo 42 caracteres, no dos señales al mismo tiempo. El usuario vio dos líneas en el video 1 del conjunto ROS 2	sí; verify informa una señal que lo rompe
Sin superposiciones	ningún texto o gráfico cubre a otro	check ADVIERTE para textos, overlaps.md y tu lista de verificación de fotogramas para el resto
Estilo	un estilo de arcilla 3D con la mascota silenciosa y nuestros propios modelos; partes de Manim sobre el fondo oscuro para curvas y gráficos (el usuario pidió: no fuerces un gráfico en arcilla). Rechazado: modelos descargados, un video oscuro completo, columnas de texto, leyendas de color, diapositivas de acumulación	make check ERROR para una escena que no es ni arcilla ni Manim, o un video sin mascota; el resto depende de ti, consulta "El estilo que el usuario quiere"
Matemáticas	los cinco pasos de fórmula (necesidad, imagen, fórmula, significado, prueba). Manim para una curva, un gráfico o una fórmula que cambia paso a paso: manim() en 2D, o manim({ threeD: true }) para una imagen 3D, no lienzo dibujado a mano	make check ADVIERTE sobre una fórmula sola; el resto depende de ti, consulta reference/script.md y styles/math-manim.md
Cuestionario	ninguno en el storyboard	tú
Visualización	mpv <dir>/out/<slug>.mp4	ponlo en el informe

Ajustes de la máquina

Ejecuta make config antes del paso 1. Imprime la configuración de esta máquina, que el instalador o /setup-kaleidoscope escribieron.

La línea voice nombra la voz: Chatterbox (natural, mejor en una GPU NVIDIA o Apple silicon) o Kokoro (pequeña y rápida en una CPU, a aproximadamente 150 palabras por minuto). Un proyecto puede elegir la suya en video.json: "_tts": {"engine": "kokoro"}. Sin una GPU, Chrome dibuja los fotogramas con SwiftShader y ffmpeg codifica con libx264.

… [truncado para la traducción]