Directora de Vídeo Musical Cinematográfico

¿Qué hace Directora de Vídeo Musical Cinematográfico?

Una habilidad de producción para crear un cortometraje visible cuya columna vertebral es una canción — no una plantilla de letra, no un pase de diapositivas, no un montón de clips generativos sin relación. Cada fotograma es dibujado por código y es reproducible a partir de un número entero de fotograma.

La habilidad es deliberadamente música-primero y evidencia-primero:

1. medir la canción antes de imaginar imágenes;
2. escribir una tesis y una puntuación de dirección antes de escribir una sola toma;
3. bloquear una edición cuadro a cuadro antes de renderizar;
4. probar el aspecto y el movimiento en un piloto de 10–20 s;
5. renderizar en unidades de toma reanudables;
6. verificar el archivo que realmente enviaste.

Regla estricta: nunca inventes una marca de tiempo, un BPM, una línea de letra, un resultado de renderizado o un pase de control de calidad. Si falta evidencia, marca el elemento como no_verificado y dilo en las notas de entrega.

---

Cuándo usar

Usar cuando el usuario solicite un vídeo musical, un cortometraje animado cortado con música, una secuencia de títulos o una tarea de "convierte mi canción en una película", y el renderizado local con código sea aceptable. La salida por defecto es 9:16, 1080×1920, 24 fps, H.264 + AAC, con un archivo de subtítulos auxiliar opcional.

No uses esta habilidad para descargar audio con derechos de autor, clonar la apariencia de un artista vivo o reproducir un MV existente toma por toma. Pide al usuario audio que tenga derecho a usar.

Requisitos previos (verificar, no asumir)

• Node 20+, ffmpeg/ffprobe, Google Chrome o Chromium.
• Python 3.10–3.13 con numpy scipy soundfile librosa (matplotlib opcional, Pillow para hojas).
• puppeteer-core, p5, p5.brush en los node_modules del proyecto.
• Suficiente espacio en disco para fotogramas: 1080×1920 JPEG q94 ≈ 0.2–0.5 MB/fotograma; una película de 4 minutos ≈ 1–3 GB.
• Para letras en chino, un LRC/SRT del usuario o un modelo Whisper local; nunca raspar y presentar el tiempo de un sitio de letras aleatorio como verificado.

Ejecuta scripts/doctor.sh (o los comandos equivalentes en references/render-recovery.md) y registra el resultado. Si falta un requisito previo, arréglalo o informa del bloqueo.

---

El bucle de producción

0. Recepción y derechos

Recopila: ruta de audio, texto de letra y cualquier archivo de tiempo, relación de aspecto/resolución/fps, fecha límite, idioma y el contexto de uso. Copia el audio como solo lectura en assets/; nunca sobrescribas el original. Indica la suposición de derechos en README.md (ej. "audio proporcionado por el usuario, solo para uso privado").

1. Master de música (puerta M)

python scripts/analyze_music.py assets/song.m4a \
  --out analysis --lrc assets/song.lrc --sections analysis/sections.json \
  --asr analysis/asr/whisper.json --fps 24

Produce analysis/audiomap.json, lyrics.json, lyrics.srt, analysis.md, analysis.png. El mapa contiene duración, una cuadrícula de tempo ajustada por fase, beats/downbeats, curvas de energía/espectral, ventanas candidatas de clímax, intervalos de secciones y tiempo de letra a nivel de línea con procedencia.

Aceptación:

• la duración y la frecuencia de muestreo coinciden con el archivo proporcionado;
• se informa la coherencia del tempo; si < 0.6, inspecciona de oído/espectrograma y considera un mapa de tempo;
• cada línea de letra tiene una fuente de tiempo (lrc_line, srt_line, cross_checked, sin_tiempo);
• la sonoridad no se trata como clímax emocional sin una verificación cruzada estructural.

Si el usuario no proporciona tiempo de letra, ejecuta scripts/align_lyrics.py con una transcripción ASR local y revísala. Mantén el tiempo de frase (marca de compás/frase, usado para cortes) separado del inicio vocal (usado para subtítulos). Nunca cambies silenciosamente toda la canción para que un corte se vea bien.

2. Tres conceptos, luego uno (puerta D1)

Escribe storyboard/concepts.md con tres películas genuinamente diferentes. Puntúa cada una en ajuste de letra/música, integridad de la historia, impacto emocional, originalidad visual, viabilidad del código y capacidad de visionado en formato largo. Selecciona una y escribe el motivo. No empieces el código de tomas hasta que esto exista.

Luego escribe storyboard/director_score.json: tesis, antítesis, curva emocional, capítulos visuales (mundo/paleta/espacio/cámara/gramática), mapa de contraste, motivos y recompensas, deseos/necesidades/arcos de los personajes, roles y traspasos de tomas, mapa sonido-visual.

Una toma que no pueda indicar su rol, traspaso de entrada y traspaso de salida no está lista.

3. Lenguaje visual y pruebas (puerta D2)

Escribe style-guide.md y una biblia de personajes/arte antes de animar. Define: paleta con valores hex y un guion de color; gramática de lente/composición para 9:16; reglas de línea y textura; proporciones de personajes, siluetas, continuidad de vestuario y rango de expresión; iluminación; vocabulario de transiciones; las cosas exactas que la película no hará (ej. "sin partículas flotantes sin causa narrativa").

Renderiza 1–3 fotogramas de estilo y una hoja de personajes. Júzguelos a resolución completa, no en miniaturas. Si el aspecto es débil, cambia el lenguaje ahora — no después de 40 tomas.

4. Edición cuadro a cuadro (puerta E)

Escribe storyboard/timeline.json con fps, total_frames, shots[] y, para cada toma: id, start_frame, end_frame, section, lyric_refs, size, composition, environment, action, expression, camera, transition_in/out, emotion, function, implementation, complexity. Las tomas deben ser contiguas y cubrir todo el audio.

python scripts/validate_timeline.py \
  --timeline storyboard/timeline.json --audiomap analysis/audiomap.json \
  --out analysis/timeline_validation.md

El validador es una puerta estricta: sin espacios, sin superposiciones, último fotograma ≥ ceil(duration×fps), cada línea de letra contabilizada, ningún corte absurdamente lejos de un beat/letra/sección sin una razón escrita.

5. Piloto (puerta P)

Renderiza 10–20 s que contengan al menos: un plano general de establecimiento, un plano medio de personaje, un primer plano, una acción rápida o impacto, y una transición. Construye una hoja de contactos y un clip visible con el audio real. Verifica:

• ¿Mantiene el estilo al 100%?
• ¿Son continuas las proporciones del personaje, el vestuario y la iluminación?
• ¿Está motivado el movimiento de cámara, o se desplaza sin razón?
• ¿Caen los cortes en eventos musicales?
• ¿Sobrevive el renderizador 300+ fotogramas sin una excepción?
• ¿Cuál es el ms/fotograma medido y el costo de disco?

Arregla el piloto antes del pase completo. Registra el rendimiento medido en LESSONS.md.

6. Renderizado completo (puerta R)

Usa un contrato de página determinista: window.renderAt(t) -> dataURL, sin Math.random, ruido con semilla, índices de fotograma enteros. Renderiza toma por toma o fotograma por fotograma con escrituras atómicas; mantén un manifiesto de unidades completadas y hashes para que una toma cambiada invalide solo a sí misma.

node scripts/render.mjs --project . --start 0 --end 232.6 --out renders/frames

Prefiere unidades por toma y una ruta --force/--shot en lugar de "borrar todo y empezar de nuevo". No renderices la misma toma aprobada dos veces. Nunca dejes que un fotograma fallido pase como completo: un fotograma debe existir, ser distinto de cero y decodificarse.

7. Ensamblaje (puerta A)

ffmpeg -y -framerate 24 -i renders/frames/f_%06d.jpg -i assets/song.m4a \
  -c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -profile:v high -level 4.2 \
  -c:a aac -b:a 256k -ar 44100 -shortest -movflags +faststart output/final.mp4

El audio maestro es inmutable. No desvanezcas, reajustes ni recodifiques la canción para que se ajuste a la imagen. La última toma debe cubrir la cola de audio; sin cola negra, sin acorde final truncado.

8. Control de calidad (puerta Q)

Ejecuta ambos y adjunta la evidencia:

python scripts/qc_video.py output/final.mp4 --audio assets/song.m4a \
  --expected-frames 5583 --timeline storyboard/timeline.json --out analysis/qc

Técnico: decodificación, duración vs audio (tolerancia ≤ 0.12 s), conteos de flujo, resolución, fps, pix_fmt, conteo de fotogramas, blackdetect, freezedetect, cobertura, fotogramas faltantes/placeholder. Visual: hojas de contacto a resolución completa, fotogramas clave por escena, tiras de fotogramas consecutivos en cortes, comprobaciones puntuales de sincronía A/V, inspección de continuidad de personajes, seguridad de títulos/subtítulos.

El control de calidad visual no se automatiza. Indica exactamente qué tomas viste, a qué resolución y qué encontraste. Un ffprobe limpio no es un pase visual.

9. Entrega

Envía: MP4 maestro, vista previa de baja resolución, storyboard.md, timeline.json, style-guide.md, qc-report.md, README.md, SRT opcional y la fuente reproducible. Mantén el audio y las letras locales a menos que el usuario tenga derechos para publicarlos. Añade una entrada fechada en LESSONS.md.

---

Contrato de archivos

project/
  assets/            # song.m4a, lyrics.lrc/srt, referencias proporcionadas por el usuario (no sobrescribir)
  analysis/          # audiomap.json, lyrics.json, sections.json, validación, QC
  storyboard/        # concepts.md, director_score.json, timeline.json, storyboard.md
  characters/        # biblia de arte, hojas de modelo
  src/               # código de dibujo determinista: lib/, custom_shots.js, shots.js
  studio.html        # contrato window.renderAt(t)
  renders/           # frames/ (secuencia global), pilot/, manifiestos
  previews/          # pilot.mp4, hojas de contacto, tablero de revisión
  output/            # MP4 final, vista previa, SRT, storyboard.md, timeline.json, style-guide.md, QC

Reglas de oficio no negociables

• La canción es la línea de tiempo maestra. La imagen se corta con la música; la música nunca se corta con la imagen.
• Una película, no una lista de reproducción de estilos. Los motivos regresan y cambian.
• Un coro repetido puede rimar visualmente; no puede reutilizar la misma composición sin cambios.
• Los personajes necesitan deseo, obstáculo, elección, consecuencia. Los rostros y las manos deben actuar.
• Los movimientos de cámara necesitan una motivación (revelar, presionar, liberar), no un Ken Burns por defecto.
• Cada toma debe contener al menos un elemento en movimiento que pertenezca al mundo de la historia.
• No escondas una historia faltante detrás de partículas, rampas de velocidad o bloom gratuito.
• Si el resultado honesto es estilizado y limitado, dilo en el informe de QC; no lo llames fotorrealista.

Fallo y recuperación

El renderizador está diseñado para fallar de forma ruidosa y reanudarse de forma económica:

• escrituras atómicas de fotogramas (*.tmp → renombrar), nunca un JPEG a medias contado como completo;
• un manifiesto por toma con hash de fuente, fotograma de inicio/fin y estado;
• --shot / --start/--end re-renderiza solo el rango afectado;
• mantén la última codificación buena conocida; nunca sobrescribas el maestro hasta que pase el QC.

Si el navegador o la GPU fallan, reintenta la unidad dos veces con una página/perfil nuevo. Si un fotograma falla tres veces, detente, aísla la toma e informa el número de fotograma y el error. No rellenes con un fotograma duplicado o un fotograma fijo.

Índice de referencias

• references/directing.md — selección de conceptos, puntuación de dirección, duración, ritmo, finales.
• references/visual-language.md — composición 9:16, cámaras, color, personaje, textura.
• references/audio-lyrics.md — medición, tempo ajustado por fase, secciones, alineación honesta.
• references/render-recovery.md — contrato determinista, manifiestos, codificación, reanudación.
• references/qc.md — puertas duras/blandas, hojas de contacto, lo que la automatización no puede ver.
• templates/ — puntuación de dirección, línea de tiempo, tarjeta de toma, guía de estilo, configuración del proyecto.
• tests/ — pruebas de analizador, cobertura y validador; ejecuta bash tests/run_tests.sh.
• LESSONS.md — qué se rompió en producciones reales y qué lo arregló.

Créditos y licencias

Los patrones del motor están informados por ClaudeAnimationBase (John Heibel) con licencia MIT y claude-music-video-skill (Sage Arbor). Los conceptos del flujo de trabajo se estudiaron de musical-mv-storyboard, que no tiene licencia; no se copia ningún código ni texto del mismo. Consulta THIRD_PARTY_LICENSES.md. p5 es LGPL-2.1, p5.brush MIT, puppeteer-core Apache-2.0, librosa ISC, ffmpeg GPL. La canción y las letras utilizadas en un proyecto no forman parte de esta habilidad.