Music Video: videoclip completo al ritmo, dibujado con código

music-video

Subcomandos (revísalos primero)

Invocación	Acción
/music-video help, /music-video sin canción, o "¿cómo uso esto?"	Imprime el bloque de Ayuda textualmente, luego verifica los requisitos previos (node -v, ffmpeg -version, uv --version, Chrome presente) e informa cada uno como ✅/❌ con el comando de instalación. Detente; no inicies un video.
/music-video lessons	Imprime LESSONS.md (la entrada más reciente completa, las entradas anteriores solo como encabezados).
/music-video <archivo de canción> [lyrics.srt] [flags] [notas]	Analiza las Banderas a continuación, di en una línea qué puertas están activadas y qué opciones ya están configuradas, luego ejecuta el proceso.

Ayuda

/music-video: convierte una canción en un videoclip sincronizado con el ritmo, dibujado enteramente en código,
             desde un dibujo animado pintado a mano hasta un diseño de movimiento elegante de estilo publicitario.

USO
  /music-video ~/Downloads/song.mp3                     Los archivos de Suno con letras incrustadas no necesitan nada más
  /music-video ~/Downloads/song.mp3 lyrics.srt          otras canciones: proporciona letras con sincronización (.srt)
  /music-video song.mp3 "estilo noir, gato detective"     dirección creativa opcional
  /music-video song.mp3 --auto --style=editorial --human=~/me.jpg --dir=~/musicVideos
                                                        totalmente automatizado: cada opción la establecen las banderas
  /music-video help | lessons

BANDERAS (por defecto: detenerse en storyboard Y piloto para tu aprobación)
  --skip=storyboard        no esperes el storyboard; aún espera el piloto
  --skip=pilot             espera el storyboard; no esperes el piloto
  --skip=all  (o --auto)   sin paradas: canción de entrada, MP4 terminado de salida, completamente agéntico
  --design                 MÁS planificación: añade una etapa de diseño (hojas de modelo de personaje,
                           muestras de paleta, un fotograma de estilo por capítulo)
                           y se detiene para que puedas iterar sobre el aspecto antes de cualquier animación.
                           Combínalo: --design --skip=pilot

OPCIONES (las no establecidas se preguntan en una breve entrevista; bajo --auto toman el valor predeterminado)
  --style=painted|editorial|keynote|geometric|hybrid
                           painted   = dibujo animado en acuarela pintado a mano (el aspecto original)
                           editorial = papel cálido, líneas finas precisas, serif, tranquilo
                           keynote   = casi negro, degradados brillantes, haces de luz, partículas
                           geometric = cuadrícula suiza, bloques de color, curvas paramétricas, sans-serif negrita
                           hybrid    = versos editorial, coros keynote
                           ask (default) = renderiza un fotograma de cada estilo y deja que elijas
                           valor predeterminado automático: editorial
  --lyrics=kinetic|bar|hooks|off   texto cinético / barra de subtítulos / solo líneas destacadas / ninguno
                           (predeterminado: kinetic para estilos vectoriales, bar para painted)
  --density=bold|every-line|abstract
                           bold (predeterminado) = una imagen fuerte por cada 2–4 líneas, chistes adicionales como
                           huevos de pascua de fondo; every-line = un chiste por línea de letra
  --human=FOTO|pip         quién interpreta "tú": caricatura a partir de una foto, o Pip estándar
  --dir=PADRE              dónde se guardan las carpetas de canciones (predeterminado ~/PROJECTS); PADRE/_shared/
                           mantiene cosas reutilizables (tu foto, tu personaje) entre videos
  --interview / --no-interview   fuerza u omite la entrevista inicial (G0)

  Las puertas omitidas no son trabajo omitido: el artefacto se sigue haciendo y revisando,
  y las decisiones que tomó se enumeran en DECISIONS.md para que puedas leerlas después.

QUÉ SUCEDE (aproximadamente 1.5–2 h con paradas; aproximadamente 45–60 min con --auto)
  1. Analiza la canción: tempo, caídas, secciones, sincronización de letras
  1b. Entrevista: fotogramas de estilo + cualquier opción no establecida, SE DETIENE      (a menos que --auto / todo esté configurado)
  2. Escribe STORYBOARD.md y SE DETIENE para tu aprobación                               (a menos que --skip)
  2b. Con --design: hojas de modelo + fotogramas de estilo, SE DETIENE para iterar
  3. Construye un clip piloto de 30 s y SE DETIENE para que puedas verlo                 (a menos que --skip)
  4. Construye el resto en paralelo (subagentes), verifica cada cambio de escena
  5. Renderiza out/<canción>_full.mp4 (1080p, H.264 + AAC), listo para YouTube

NECESITA   Node 20+, Google Chrome, ffmpeg, uv  (Mac: brew install node ffmpeg uv)
COSTO      sin gasto de API; usa tu plan de Claude (una canción completa es una parte considerable del uso)
SALIDA     una carpeta de proyecto (predeterminado ~/PROJECTS/<canción>-video/, o --dir), fuera de cualquier repositorio
DESPUÉS    "add today's lessons to the music-video skill" hace que el próximo video sea mejor

El ejemplo terminado es el video zoo2 ("Please Select Your Ending", 4:30): alrededor de 100 tomas, construido en aproximadamente 1 h 40 m de tiempo real. examples/zoo2/ tiene su storyboard, cada archivo de capítulo y el making-of con cronograma, tokens y costo. Lee LESSONS.md antes de comenzar: es el registro de mejoras y anula cualquier cosa aquí que contradiga.

Por qué código, no generación

Los modelos de imágenes (Deforum, SDXL-Turbo img2img, etc.) readivinan cada fotograma, lo que provoca parpadeo, caras derretidas y manos mal hechas. El intento 1 de zoo2 hizo eso durante la noche y fue rechazado. Los fotogramas dibujados con código son funciones puras del tiempo de la canción: suaves, dentro del modelo y exactamente en el compás. Los modelos de video en la nube (Kling, Seedance, Veo) son la otra ruta, a unos 70–300 dólares por canción.

Banderas y puertas

Analiza las banderas de los argumentos y de palabras simples: "sin paradas", "totalmente autónomo", "solo hazlo" significan --skip=all; "salta la aprobación del storyboard" significa --skip=storyboard; "déjame ver los personajes primero", "planifícalo más" significan --design. Los valores se combinan con comas (--skip=storyboard,design). Banderas desconocidas: dilo y detente.

Puerta	Predeterminado	Cuando se omite
G0 entrevista	DETENER cuando cualquier opción a continuación no esté establecida	Bajo --auto/--no-interview, las opciones no establecidas toman sus valores predeterminados y se registran en DECISIONS.md.
G1 storyboard	DETENER	Escríbelo, haz una pasada de autocrítica contra la hoja de letras (¿una idea por línea? ¿cada coro un remate? ¿el motivo regresa al final?), luego continúa.
G2 diseño (solo con --design)	DETENER, iterar hasta aprobación	--skip=design mantiene la etapa pero autocritica las hojas en lugar de esperar.
G3 piloto	DETENER	Aún construye el piloto (crea los SETS compartidos que los capítulos necesitan). Haz dos pasadas de revisión de hoja de contacto y corrige los errores típicos de la primera pasada antes de continuar.

Decisiones (--style, --lyrics, --density, --human, --dir; tabla en Ayuda). Las palabras simples también cuentan: "limpio", "corporativo", "marketing", "no infantil", "nítido" significan un estilo vectorial (pregunta cuál, o editorial bajo --auto); "como el video zoo", "pintado a mano" significa painted. Registra las decisiones finales al inicio de STORYBOARD.md y en src/config.js como PROJECT.style, PROJECT.lyrics, para que los subagentes las hereden.

Una puerta solo se omite cuando el usuario lo ha dicho; en caso de duda, detente. Una DETENCIÓN es real: termina el turno y espera. Para cada puerta omitida, añade a DIR/DECISIONS.md: la puerta, lo que se decidió, las alternativas que sopesaste y las rutas de las imágenes que revisaste. Enlaza DECISIONS.md en el informe final para que el usuario pueda auditarlo. Nunca omitas la comprobación final de ffprobe y la verificación puntual de letra/fotograma en el paso 8: esas son verificación, no aprobación.

Proceso (hazlos en orden; las DETENCIONES son reales a menos que una bandera las haya omitido)

1. Proyecto. Crea la carpeta del proyecto fuera de cualquier repositorio: PADRE/<slug-de-canción>/ donde PADRE es --dir (predeterminado ~/PROJECTS), y mueve la canción a su assets/. Pon una foto de referencia (--human) en PADRE/_shared/. bash ~/.claude/skills/music-video/scripts/setup_project.sh PADRE/<slug-de-canción> Esto clona ClaudeAnimationBase en UPSTREAM_PIN, añade src/cast.js (Pip, accesorios, karaoke) y conecta el karaoke. Necesita Node 20+, Chrome, ffmpeg, uv y git.
2. Analizar. uv run ~/.claude/skills/music-video/scripts/analyze_song.py CANCIÓN --project DIR [--srt LYRICS.srt] Esto escribe src/config.js (bpm ajustado por fase y offset), src/lyrics.js y analysis.json. Nunca confíes en el BPM de librosa. Usa el valor ajustado. Verifica energy_drops con los inicios de la sección [Chorus]. Las exportaciones de Suno incrustan una pista SRT con etiquetas [Section]; para otras canciones, obtén los tiempos primero (pregunta al usuario, o alinea con whisper). El BPM ajustado puede salir al doble del tempo percibido (baja coherencia, una línea de letra = dos "compases"): anota el tempo percibido en el storyboard y usa bt(2k) para los tiempos percibidos. 2b. Entrevista (G0). Omítela solo cuando cada opción esté configurada o se haya dado --auto/--no-interview. De lo contrario:
   • Estilo primero, como imágenes. Si --style no está configurado, renderiza los fotogramas de comparación: node design/style_tests.mjs (copiado por setup) dibuja el MISMO momento de la letra en editorial, keynote, geometric e hybrid (--line1/--line2/--stamp establecen las palabras), en out/design/style_test_*.jpg y style_tests_all.jpg. Envíalos, más un fotograma pintado del ejemplo zoo2 si el usuario no lo ha visto. La gente no puede elegir un estilo solo con palabras.
   • Luego pregunta las opciones restantes no establecidas en una ronda de AskUserQuestion (lyrics, density, human), más las decisiones específicas de la canción que un storyboard no puede tomar solo: qué tan literalmente mostrar marcas o productos reales, y cómo mostrar líneas de letra sensibles (violencia, escándalo, eventos reales).
   • Reutilizar antes de redibujar: si PADRE/_shared/cast/ ya tiene un personaje para esta persona (ej. <nombre>.js + <nombre>_body.js, aprobados en un video anterior), copia esos archivos en src/vec/, añade sus etiquetas <script> después de vec.js, y úsalos tal cual (controles de expresión y pose incluidos). Solo redibuja si el usuario pide cambios. Después de que una nueva persona sea aprobada, copia sus archivos en PADRE/_shared/cast/ (con una línea en _shared/README.md) para que el próximo video los reutilice.
   • Con una nueva foto --human, mírala y escribe los rasgos de la caricatura en STORYBOARD.md (forma de la cabeza, cabello o no, vello facial, cejas, ojos, ropa habitual). Dibuja a partir de los rasgos; nunca traces ni pegues la foto en el video. G0 — DETENER después de enviar los fotogramas y preguntas. Combina las respuestas en las opciones, luego continúa.
3. Lee DIR/ANIMATION_GUIDE.md (las reglas del kit), LESSONS.md y un capítulo de ejemplo (examples/zoo2/scenes/c01_pilot.js) antes de escribir nada. Para un estilo vectorial (cualquier cosa menos painted), las secciones del motor de la guía aún aplican (línea de tiempo, shots(), cámara, easing, compás, bucle de revisión), pero sus reglas de apariencia están invertidas: consulta Estilos vectoriales a continuación.
4. Storyboard. Escribe DIR/STORYBOARD.md (formato: examples/zoo2/STORYBOARD.md) con la línea argumental, el elenco, el arco de paleta, el motivo, una tabla de capítulos para toda la canción y el piloto toma por toma con "lecturas" temporizadas. La densidad de imagen sigue --density (bold: una imagen fuerte por cada 2–4 líneas, con el resto como huevos de pascua de fondo; every-line: uno por línea, interpretado por personajes). G1 — DETENER: muestra al usuario y espera aprobación (con --skip=storyboard/all: autocritica, registra en DECISIONS.md, continúa). 4b. Diseño (solo con --design). Antes de cualquier animación, establece el aspecto como imágenes fijas en out/design/:
   • cast_<nombre>.jpg hoja de modelo por personaje: frente, tres cuartos y perfil, 4 expresiones (neutral, alegría, miedo, determinación), 3 poses de acción del storyboard y una alineación de alturas de todo el elenco;
   • palette.jpg: tira de muestras por capítulo, mostrando el arco de paleta a lo largo de la canción;
   • style_<capítulo>.jpg: un fotograma clave terminado por capítulo en el momento héroe del storyboard, con la letra puesta. Dibújalos con un scenes/design.js desechable (un capítulo solo de hoja fuera del rango de tiempo de la canción) y node render.mjs --sheet=...; el código del personaje va en adiciones a src/cast.js que los capítulos reutilizarán, así que los diseños aprobados pasan directamente al video. G2 — DETENER: muestra las hojas; toma notas ("ojos más grandes", "paleta de coro más cálida"), vuelve a renderizar, repite hasta que el usuario apruebe. Luego actualiza STORYBOARD.md para que coincida.
5. Piloto. Elige unos 30 s que crucen un límite de sección hacia un coro. Constrúyelo como un archivo de capítulo con conjuntos compartidos exportados en window.SETS (ver el final de c01_pilot.js). Verifícalo con node render.mjs --sheet=... --out=out/check/x.jpg y --strip=a:b, y mira las imágenes. Los errores típicos de la primera pasada: personajes demasiado pequeños (empuja la cámara a 1.3–1.5×), formas de fondo no lo suficientemente anchas para movimientos panorámicos, accesorios ocultos bajo la barra de karaoke. Para un estilo vectorial, construye sobre src/scenes/sets.js (el setup copia una funcional: habitación, ventana, pasillo, desplazamiento, fusión de emociones; adáptalo). Renderiza node render.mjs --clip --range=a:b --out=out/pilot.mp4. G3 — DETENER: el usuario lo ve y aprueba o solicita cambios (con --skip=pilot/all: dos pasadas de revisión, registra en DECISIONS.md, continúa).
6. Capítulos en paralelo. Añade archivos stub y sus etiquetas <script> en studio.html para cada capítulo primero (un agente nunca debe editar un archivo compartido). Luego lanza un subagente por capítulo (tipo fork, para que herede este contexto). Dale a cada uno su rango de tiempo, sus líneas de letra, su resumen de capítulo del storyboard, "SOLO TU ARCHIVO", los SETS compartidos y los globales, y el contrato de costura:
   • entre capítulos, una transición con los MISMOS colores en ambos lados (pintado: brushWipe, salida p<.5 en los últimos 0.3 s, entrada .5+lt/.6; vectorial: V.wipe, ver CHAPTER_BRIEF.md