Yari-tuber/math-rap-video

Video de Rima Explicativa (Rap Matemático)

Convierte un concepto en un video explicativo de aproximadamente 1 minuto. Es memorable porque superpone tres capas que siguen la misma pista de audio:

• Oído: ritmo fijo, una línea por compás, rima constante, fácil de recordar
• Lenguaje: rima de 8–10 caracteres, cantada 2–3 veces, fija en la parte superior
• Vista: cada carácter activa un paso gráfico, mostrando "por qué es correcto"

La narrativa es fija: Plantea problema → Tiende trampa (método torpe se enreda) → Da rima → Demuestra → Explica principio → Cierre.

División del trabajo: quién aporta qué

Parte	Quién lo hace	Notas
Rima, letra, storyboard	Tú (IA) escribes, usuario confirma	Reglas en references/lyrics.md
Audio (voz + música)	El usuario o cliente lo proporciona	Qué modelo usar, qué voz, lo deciden ellos. Entrégales la sección "Requisitos para el cliente" de references/audio.md. Este skill no elige plataforma por el usuario ni gasta dinero por defecto
Temporización de subtítulos	El script la calcula	Cualquier SRT exportado funciona, incluso con errores tipográficos
Fondos de pantalla	Se seleccionan automáticamente de la biblioteca	assets/backgrounds/, etiquetados por uso; se pueden añadir más
Gráficos, rimas, fórmulas, subtítulos	El script los dibuja fotograma a fotograma	Tú solo escribes storyboard.json y graphics.py para este tema

Entorno

La primera vez, ejecuta la autoverificación; te indicará paso a paso qué falta y cómo instalarlo:

python $SKILL/scripts/check_env.py

Se necesita: Python 3.10+ (pip install pillow numpy librosa pypinyin), ffmpeg / ffprobe, una fuente bold china (las del sistema se detectan automáticamente), y la biblioteca de fondos. La biblioteca se busca en este orden: variable de entorno MATH_RAP_LIBRARY → assets/backgrounds/ de este skill → ubicación compartida ~/.math-rap-video/backgrounds/. Si falta, ejecuta python $SKILL/scripts/install.py --library <archivo_biblioteca.zip>.

En adelante, $SKILL se refiere al directorio donde reside este skill (la carpeta que contiene este SKILL.md). No es una variable de entorno predefinida: al ejecutar comandos, reemplázala con la ruta real, o defínela una vez (bash: export SKILL="/ruta/math-rap-video"; PowerShell: $SKILL="C:\ruta\math-rap-video"). Si la ruta contiene espacios o caracteres chinos, usa comillas. Todos los scripts son programas CLI normales (todos soportan --help); cualquier IA o persona que pueda ejecutar comandos puede seguirlos, sin depender de una herramienta específica.

Flujo de trabajo

1 Escribir letra y storyboard ──→ 2 Usuario entrega audio ──→ 3 prepare_audio calcula tiempos y valida
                                        │
4 Escribir storyboard.json + graphics.py ←────┘
        │
5 check + vista previa (confirmar con imagen) ──→ 6 build_video produce video ──→ 7 Revisar y entregar

Después de cada paso, informa brevemente al usuario. Los pasos 1 y 5 requieren confirmación del usuario antes de continuar.

Cuando el usuario trae letra y audio ya hechos (letra finalizada, audio basado en ella): no cambiar ni una palabra de la letra, o las imágenes no coincidirán con el canto. El paso 1 solo hace tres cosas: crear nuevo proyecto, copiar la letra tal cual en lyrics.md, y añadir la tabla de storyboard al final; los resultados de check_lyrics.py son solo de referencia, no se modifica la letra. Luego se continúa directamente desde el paso 3.

1. Crear nuevo proyecto, escribir rima, letra y storyboard

python $SKILL/scripts/new_project.py <directorio_del_proyecto>          # Copia el ejemplo (contar segmentos) como punto de partida
python $SKILL/scripts/new_project.py <directorio_del_proyecto> --blank  # O desde plantilla vacía

Escribe lyrics.md siguiendo references/lyrics.md: una línea = un compás, cada línea de 11–15 caracteres (sección de principio 9–11 caracteres), rima constante; estructura: Verso 1 (14 líneas) + Estribillo (2 líneas, rima se canta sola) + Verso 2 (8 líneas).

La tabla de storyboard se escribe al final de lyrics.md en la sección ## Tabla de storyboard (una tabla: número de línea, acción visual, carácter que desencadena). Es para que el usuario la confirme y es la base para el paso 4; el script no la lee.

Después de escribir, ejecuta la verificación de letra y corrige todo lo "obligatorio"; revisa las "sugerencias" una por una:

python $SKILL/scripts/check_lyrics.py <directorio_del_proyecto>     # Estructura, caracteres por línea, rima, errores de audición

Verifica manualmente cada número del ejemplo (el script no puede verificar matemáticas). Luego entrega la rima, letra y storyboard al usuario para confirmación.

2. El usuario proporciona el audio

Entrega al usuario la letra confirmada y la sección "Requisitos para el cliente" de references/audio.md. Pueden usar cualquier método para el audio: plataformas AI de música, rap humano, TTS o locución real con acompañamiento. Lo que deben entregar:

• Uno o varios archivos de audio (mp3 / wav), con voz. Si es generado por AI, se recomienda pedir 2–3 versiones para elegir
• Preferiblemente un archivo de subtítulos (SRT). Si no tienen, usa cualquier herramienta de reconocimiento de voz para generar el SRT a partir del audio

Si el usuario te pide explícitamente que generes la canción y proporciona una API Key de ElevenLabs, puedes usar scripts/gen_music.py (instrucciones en references/audio.md). Esto es opcional; cada versión gasta el crédito del usuario, avísalo antes de generar.

3. Procesar audio: calcular tiempos y decidir si esta versión es usable

python $SKILL/scripts/prepare_audio.py <directorio_del_proyecto> --audio cancion.mp3 --srt reconocimiento.srt --bpm 90 --intro-bars 2

Este script alinea el resultado del reconocimiento con la letra (errores tipográficos, diferentes segmentaciones no importan), detecta velocidad y ritmo, escribe timing.json, y copia el audio al directorio del proyecto (el video lo leerá de ahí, así que es normal que aparezcan archivos de audio extra). La última línea da una conclusión:

• Usable: continuar. Si hay líneas con "baja tasa de coincidencia", anótalas y recuerda al usuario que las revise en la entrega.
• Recomendar cambiar de versión (código de salida 3): muestra las razones, comunes son: omitir una línea, voz que entra tarde, compresión general. Cambia a otra versión de audio, no fuerces su uso.

Cuando hay varias versiones, escríbelas en archivos separados, compáralas, y copia la seleccionada como timing.json:

python $SKILL/scripts/prepare_audio.py <directorio> --audio generada_01.mp3 --srt 01.srt --bpm 90 --intro-bars 2 --out timing_01.json
python $SKILL/scripts/prepare_audio.py <directorio> --audio generada_02.mp3 --srt 02.srt --bpm 90 --intro-bars 2 --out timing_02.json
cp <directorio>/timing_02.json <directorio>/timing.json

Cómo elegir: ver sección 3 de references/audio.md. Resumen: primero descarta las que "recomiendan cambiar", luego elige la que tenga la mayor tasa de coincidencia en las dos líneas del estribillo, y finalmente mira si el ritmo es uniforme. Cuando haya conflicto, la claridad del estribillo tiene prioridad sobre el ritmo uniforme: el público recuerda la rima.

Otros casos: locución explicativa pura, audio sin ritmo añadir --no-beat; si no hay SRT, la alternativa es --grid --entry <segundos_de_entrada_de_voz>, que estima un compás por línea; --intro-bars escribe el número de compases de introducción acordado con el cliente (en el ejemplo anterior, 2 es nuestro requisito por defecto), no lo escribas si no se ha acordado. En PowerShell de Windows, cp también funciona; en cmd, usa copy.

Para cambiar el audio solo hay que repetir este paso, no es necesario modificar el storyboard.

4. Escribir storyboard y gráficos del tema

Lee references/visuals.md, luego modifica dos archivos en el directorio del proyecto:

• storyboard.json: banner de rima, fórmulas, texto emergente, flechas, plan de cambio de fondo
• graphics.py: gráficos específicos de este tema, implementa setup(ctx) y draw(canvas, t, ctx)

La regla más importante: Todos los tiempos deben expresarse como expresiones relativas a la letra, nunca con segundos fijos.

Escritura	Significado
L(6) / E(6)	Inicio / Fin de la línea 6
W(9,'cuatro') / W(9,'cuatro',2)	Tiempo en que se canta el carácter 'cuatro' (el 2º 'cuatro') en la línea 9
B, L(6)+2*B	Un pulso; 2 pulsos después del inicio de la línea 6

Así las imágenes realmente sincronizan con el canto, y si el cliente cambia de audio, solo hay que repetir el paso 3 para obtener el video.

Los gráficos son el paso que más tiempo requiere. El motor ya proporciona métodos comunes (puntos, líneas, arcos, ángulos de sector, símbolos de ángulo recto, bloques numéricos, líneas de paréntesis, ecuaciones multicolor en una línea, rotación/traslación de bloques, movimiento a lo largo de una ruta, espaciado uniforme). Primero busca en la sección 4 de references/visuals.md métodos ya existentes, no reinventes la rueda. Escribe un fragmento y previsualiza (siguiente paso), no esperes a tener todo escrito.

Los dos errores más comunes observados, evítalos desde el principio:

• Gráficos demasiado pequeños o finos. Esto se ve en móviles: el gráfico principal debe ocupar más de la mitad del ancho de la pantalla (ancho ≥ 800 o alto ≥ 400), los elementos en una fila deben rellenar el ancho con ctx.spread(n), grosor de línea ≥ 9, tamaño de fuente ≥ 44. Referencias de tamaño en la sección 1 de references/visuals.md.
• Cada línea debe tener algo visual. Gráficos, texto emergente o fórmula: al menos uno debe estar en el centro de la pantalla; no dejes que una línea solo tenga fondo y subtítulos.

5. Verificar y previsualizar

python $SKILL/scripts/overlay_engine.py <directorio_del_proyecto> check          # Obligatorio: 0 problemas de storyboard, 0 errores de renderizado; revisar "avisos de diseño" uno por uno
python $SKILL/scripts/overlay_engine.py <directorio_del_proyecto> sheet          # storyboard_preview.jpg: resumen de cada línea en un cuadro
python $SKILL/scripts/overlay_engine.py <directorio_del_proyecto> sheet --pages  # Además, storyboard_preview_p1.jpg…: páginas grandes para ver superposiciones (el resumen también se actualiza)
python $SKILL/scripts/overlay_engine.py <directorio_del_proyecto> frames "L(18)" "L(19)" 0.2   # storyboard_frames.jpg: desglose fotograma a fotograma de una animación

Abre las imágenes tú mismo y compáralas con la tabla de storyboard:

• Resumen: ¿aparece lo que debería en cada línea? ¿hay algún cuadro vacío?
• Páginas grandes: ¿los textos se superponen? ¿topan con el banner de rima o los subtítulos? ¿los gráficos son lo suficientemente gruesos y grandes?
• Donde haya movimiento, rotación o entrada, usa frames para ver si chocan con otros elementos.
• Los "avisos de diseño" de check indican puntos temporales que hay que revisar uno por uno (reporta: topa con banner, presiona subtítulos, se superpone con fórmulas, toca bordes, gráfico pequeño, centro vacío, textos superpuestos).
• Lo que check no detecta: texto sobre líneas o bloques de color ilegible, número de gráficos incorrecto, colores poco llamativos. Solo se ven en las imágenes grandes.

Si hay problemas, vuelve al paso 4 y corrige. Cuando esté bien, entrega el resumen al usuario para confirmación, luego produce el video.

6. Producir el video

python $SKILL/scripts/build_video.py <directorio_del_proyecto> bg            # Selecciona fondos y los ensambla, imprime qué material se usó en cada segmento
python $SKILL/scripts/build_video.py <directorio_del_proyecto> final 20 30   # Opcional: primero un fragmento de 10 segundos para ver efecto
python $SKILL/scripts/build_video.py <directorio_del_proyecto> final         # Video completo, unos 6–12 minutos (según la velocidad del ordenador), ejecútalo en segundo plano
python $SKILL/scripts/build_video.py <directorio_del_proyecto> sheet         # video_final_resumen.jpg
python $SKILL/scripts/make_vertical.py <directorio_del_proyecto> --title "Título"   # Opcional: versión vertical (Douyin, Kuaishou, WeChat Video)

bg detecta automáticamente si cada segmento tiene gráficos del tema; de ser así, solo selecciona fragmentos "tranquilos" (sin primeros planos brillantes de personas) y lo indica en la lista impresa. Después de las previsualizaciones, también puedes usar build_video.py <directorio_del_proyecto> all para ejecutar check + bg + final + resumen en un solo comando. La versión vertical coloca el video apaisado terminado en el centro de un lienzo 1080×1920, añade título arriba, texto pequeño abajo, y rellena el fondo con el video ampliado y desenfocado; no reorganiza los gráficos en formato vertical. Si no se escribe --title, se lee vertical.title de storyboard.json; si tampoco existe, se usa el título del archivo de letra.

7. Revisar y entregar

Revisa video_final_resumen.jpg: ¿el fondo es lo suficientemente oscuro? ¿los gráficos y el texto son claros? ¿hay algún rostro brillante del fondo que se superponga con el texto emergente o las explicaciones? (si lo hay, añade :quiet o un fragmento específico a esa línea en el plan de fondos, y vuelve a ejecutar bg y final). Luego entrega video_final.mp4 al usuario e indícale:

• Las imágenes y tiempos han sido verificados por el script, pero el sonido necesita que una persona lo revise: presta especial atención a que la rima emergente y los resultados numéricos coincidan exactamente con el canto.
• Las líneas con baja tasa de coincidencia del paso 3, escúchalas específicamente.

Archivos de referencia

Archivo	Cuándo leerlo
references/lyrics.md	Antes de escribir rima, letra y storyboard
references/audio.md	Cuando el usuario pregunta "¿qué usar para la música/locución?"; cuando hay que enviar los requisitos de audio al cliente; al validar y seleccionar audio
references/visuals.md	Antes de escribir storyboard.json y graphics.py (diseño, campos, herramientas de dibujo, dibujos de tipos de problemas comunes)
references/library.md	Cuando se necesita añadir fragmentos a la biblioteca, generar nuevos fondos, o el fondo seleccionado no es adecuado
references/troubleshooting.md	Cuando cualquier paso da error o el resultado no es correcto
references/teaching.md	Cuando el usuario quiere entender los principios, enseñar a otros, o no quiere escribir código (método con CapCut)
references/compatibility.md	Cuando el usuario pregunta "¿puede hacerlo otra IA / otro modelo?"; cuando se va a compartir el skill con otros
examples/shuxianduan/	Ejemplo completo: letra, storyboard, gráficos. Léelo antes de escribir un nuevo tema

Lista de scripts

Script	Función
check_env.py	Autoverificación del entorno
new_project.py	Crear nuevo directorio de proyecto
check_lyrics.py	Verificación de letra
prepare_audio.py	Audio + subtítulos → timing.json, y conclusión usable / cambiar de versión
overlay_engine.py	Verificación, previsualización, renderizado de capas superpuestas
build_video.py	Seleccionar fondos, sintetizar video final, generar resumen
make_vertical.py	Video apaisado → versión vertical
library_tool.py	Gestionar biblioteca de fondos (añadir, eliminar, cambiar etiquetas, resumen)
gen_music.py	Opcional: generar canción con ElevenLabs
install.py	Instalar este skill en otras herramientas AI (Codex, Gemini CLI, opencode, etc.), colocar la biblioteca
chat_pack.py	Generar paquetes de indicaciones para AI solo de chat (escribir letra / escribir imágenes / modificar según resultados de verificación)