csm-kr/video-de-movimiento-con-referencia

Video de movimiento con referencia

La película es HTML, y su lista de señales es la partitura. Cada evento visible registra una señal junto a la constante que mueve la imagen; cada tramo de la película es una sección nombrada por su propósito. Una paleta convierte eso en música que golpea cada fotograma y representa la historia: sin ritmo mientras se plantea el problema, un groove cuando el producto funciona, un respiro antes del gran momento, batería fuera cuando el producto se detiene deliberadamente, un silencio total en el logo.

Ejemplos prácticos: examples/claude-code/ (películas de lanzamiento, explicador y demo ejecutables en un escenario compartido, cada una con una paleta diferente), examples/moments-v2.html (anuncio de 36 s de plano continuo), examples/ads/ (anuncios de Moments: batería, orquestal, violín). Las composiciones de Moments necesitan recursos del producto y ajustes de ruta; son referencias, no demos listas para renderizar.

Reglas que decidieron películas anteriores

1. Primero el encaje. La música debe coincidir con el estado de ánimo del producto y representar el flujo de la imagen. En una prueba A/B ciega (KIBO v4.5, 30 s, misma imagen, misma sonoridad) el propietario eligió la partitura compuesta para la imagen sobre una pista libre de electropop que estaba sincronizada al ritmo y era mejor en todas las métricas automáticas: "la segunda no encaja". Componer es la opción predeterminada; una pista de biblioteca solo cuando el usuario la elige (references/music.md).
2. Un sonido en cada señal, en su fotograma. Los cortes caen en el tiempo, las palabras resaltan en el contratiempo, la revelación más grande recibe el golpe más fuerte.
3. Solo metraje real y salida real. Los gráficos en movimiento enmarcan y explican; nunca falsifican una función. Etiqueta las aceleraciones y los cortes de espera en pantalla ("App real · 1×", "··· corte de espera", "▶▶ acelerado"), etiqueta las voces sintéticas, pon una fuente debajo de cada número.
4. Primero la voz. Cuando hay narración o diálogo, el fondo musical se aparta (references/music.md, "Mezcla").
5. Las puertas automáticas son necesarias, no suficientes. La sincronización, la sonoridad y el STT pueden pasar en música que no encaja. La persona decide mediante escucha ciega.
6. Pregunta, luego decide. Pregunta solo lo que la solicitud y el repositorio no pueden responder, con una respuesta recomendada primero; decide el resto y dilo.

Flujo de trabajo

0. Verificación de configuración (antes de cualquier otra cosa)

Informa cada línea como ok o falta, con la solución; nunca imprimas el valor de una clave.

• Google Chrome (el renderizador usa el Chrome instalado: el Chromium incluido no puede decodificar H.264), ffmpeg (con rubberband), Node ≥ 20 con npm ci --prefix engine --ignore-scripts desde el directorio del skill.
• Python 3.12 con numpy, scipy, soundfile, pytest (uv venv --python 3.12 .venv, luego uv pip install --python .venv/bin/python -r requirements.txt desde el directorio del skill).
• Muestras: ejecuta bash engine/fetch_samples.sh core (VSCO-2-CE CC0 percusión, metales, mazos; SFX con licencia Pixabay), luego bash engine/fetch_samples.sh piano para soft_pulse (Salamander Grand Piano, CC-BY 3.0; acredítalo cuando se use). Las paletas recurren a la síntesis cuando falta una muestra, pero el recurso de piano puede fallar en la comprobación de equilibrio de sección; usa ambos conjuntos para la suite de pruebas completa.
• Un proveedor de narración y sus credenciales solo si se solicita narración (references/voice.md). No se necesita clave API para las tres muestras ejecutables. Los clientes de narración, transcripción y captura de aplicación no están incluidos; utiliza las herramientas disponibles y verifica la documentación actual del proveedor elegido cuando sea necesario.
• Disco libre: los renders canalizan fotogramas (sin volcados PNG), pero las bibliotecas de muestras y las tomas necesitan unos pocos GB.

1. Entrevista inicial → resumen de una página (aprobado antes de planificar)

Pregunta solo por el contexto que la solicitud y el repositorio no proporcionan. Utiliza la herramienta de preguntas del entorno, o un chat simple si no hay ninguna; agrupa preguntas relacionadas, pon la opción recomendada primero y reutiliza respuestas ya dadas:

1. Propósito: qué tipo de película (lanzamiento, explicador conceptual, demo paso a paso, viñeta de caso de uso, manifiesto), quién la ve, dónde va (YouTube, un concurso, redes sociales), qué deben hacer después, la fecha límite y cualquier criterio de evaluación.
2. Mensaje y prueba: la única frase que recordar, tres pruebas con sus fuentes, lo que no se debe decir.
3. Forma y sonido: duración y formatos (16:9, 9:16, versiones reducidas), idiomas para pantalla, subtítulos y voz; enlaces de referencia musical o un estado de ánimo (ofrece las paletas de la tabla siguiente que encajen con el propósito, más "Tengo enlaces de referencia"); narración o no, y qué voz.
4. Fuentes y reglas: ¿se puede grabar la aplicación real? (URL, inicio de sesión, datos de demostración, dos dispositivos), ¿aparecerán personas?, recursos de marca, reglas del concurso, IP de terceros. Lee el resumen y obtén un sí. Escríbelo en video/BRIEF.md.

2. Género y referencias

Elige la plantilla de ritmo del género y los objetivos medidos en references/genres.md (16 referencias oficiales en cinco géneros, con duraciones de plano, palabras por tarjeta, ritmo de voz en off, cuándo aparecen el producto y el logo). Mira las referencias elegidas con /watch; mide su música con engine/ref-analyze.py. Para un anuncio de plano continuo, lee references/transitions.md y references/youtube-analysis.md.

3. Plan → video/PLAN.md (aprobado antes de construir)

Una hoja de ritmos en la cuadrícula de BPM (100 BPM = 0,6 s por pulso, 18 fotogramas a 30 fps; coloca el golpe en un tiempo fuerte): tiempo | compases | escena | texto en pantalla | metraje | tipo de sección | señales | voz. Nombra el objeto héroe (un elemento del producto que viaja a través de la película y aterriza en el logo), el marco persistente y cada afirmación con su archivo de evidencia.

4. Capturar pantallas reales

references/capture.md: cuando el producto lo necesita, tomas en vivo de dos dispositivos desde la aplicación real (fotogramas de screencast CDP con marcas de tiempo de pared, una voz de cliente sintética reproducida en el micrófono del teléfono, la respuesta de la IA copiada de la página), convertidas a MP4 de velocidad de fotogramas constante en un solo reloj, luego reproducidas en la película a través de un mapa de tiempo ([[t película, t toma], ...]: pasos iguales son 1×, una ejecución plana es una pausa, dos puntos separados por 1 ms son un corte). Usa la herramienta de navegador disponible en el entorno; references/aside-capture.md proporciona una implementación específica de Aside. Salida de terminal o herramienta: re-tipografia la salida real (las muestras de Claude Code), nunca la inventes.

5. Narración (opcional)

references/voice.md: usa el proveedor de TTS elegido o las grabaciones proporcionadas, audiciona tomas, elige por precisión de palabras y ritmo (155-170 palabras por minuto es un punto de partida para una demo en inglés), y ajusta la redacción o las pausas antes de estirar el habla. Limpia en la fuente y escribe cada línea a un presupuesto de palabras para su espacio.

6. Construir la composición

• Un #stage fijo de 1920×1080; todo el movimiento de UNA línea de tiempo GSAP pausada; la escritura, los contadores, el punto héroe y los vídeos tomados se evalúan solo a partir del tiempo en __seek(t). Nunca animaciones CSS, setTimeout o requestAnimationFrame para movimiento. fromTo necesita immediateRender: false.
• Contrato para el motor: window.__duration, __seek(t), __ready, __cues, __sections, __bpm, __T. Comienza desde examples/claude-code/stage.js (señales, secciones, pops de palabras, escritura, contadores, tarjetas de terminal, el punto héroe) o examples/moments-v2.html (cámara virtual sobre pantallas reales).
• Registra una señal junto a cada constante que hace visible algo; marca cada tramo con una sección por propósito (tabla siguiente).
• Subtítulos: reserva un espacio legible para las líneas habladas y mantén otro contenido libre de él; identifica los hablantes sintéticos y su proveedor, agrega traducciones cuando el resumen lo requiera y escribe el .srt desde la misma lista de subtítulos.
• Comprueba imágenes fijas antes de cualquier render completo: node engine/stills.mjs index.html out/stills 1.7 3.6 ....

7. Música: componer para la imagen

node engine/cues.mjs > cues.json                      # duración, bpm, T, señales, secciones
python engine/compose.py cues.json score.wav --palette bright_demo [--narr narr.js --narr-root .]

compose.py escribe la partitura, mezcla las voces primero, masteriza a -14 LUFS (pico verdadero por debajo de -1 dBTP) y ejecuta la puerta de sincronización por sí mismo: una señal sin un inicio audible dentro de 33 ms obtiene el sonido de énfasis de la paleta y la mezcla se rehace (como máximo dos veces); el informe enumera lo que agregó. Audiciona antes de elegir: renderiza el mismo tramo de 15-30 s con dos o tres paletas que encajen y deja que la persona elija a ciegas. Detalles, reglas de mezcla y la ruta de pista de biblioteca: references/music.md.

8. Renderizar

node engine/render.mjs index.html out/film.mp4 --fps 30 --audio score.wav (fotogramas JPEG q95 canalizados a x264: aproximadamente 10 veces más rápido que PNG; banderas de YouTube: perfil alto, GOP de la mitad de la velocidad de fotogramas, etiquetas BT.709, AAC 48 kHz 384 kbps). Rangos cortos para borradores: --from 10 --to 16. Chrome carga aproximadamente 18 vídeos distintos en una página; usa imágenes fijas para tomas que no se mueven.

9. Puertas (todas en los archivos finales)

references/qa.md. Verifica la sincronización en el MP4 final (python engine/synccheck.py out/film.mp4 cues.json: cada señal dentro de 33 ms, leída con su línea base de probabilidad), sonoridad, pico verdadero, imágenes fijas, transiciones y el juicio de escucha de la persona. Aplica comprobaciones de voz, subtítulos, QR y revisión solo cuando esas características existan, utilizando las herramientas disponibles en el entorno; no informes comprobaciones no ejecutadas como aprobadas. Una prueba de comprensión en la nube es opcional y requiere la elección del usuario de enviar la película a ese servicio.

10. Entregar

Entrega la duración y el formato del resumen, normalmente H.264 MP4, un archivo .srt adjunto cuando haya subtítulos, y una miniatura o versiones reducidas si se solicita. El escenario y el renderizador integrados son 1920×1080; otra relación de aspecto requiere adaptación explícita, no una bandera del renderizador. Informa las comprobaciones realmente ejecutadas y su evidencia. La publicación es una acción separada a menos que el usuario ya la haya solicitado.

Secciones, por propósito

tipo	úsalo donde la imagen...	la música
intro	plantea el problema, antes de que el producto actúe	sin ritmo: solo un pad, los sonidos de señal
tease	despierta el producto, la primera pregunta	un groove escaso (sin contratiempo, percusión superior ni melodía)
build	está a punto de conseguir un resultado; el relleno antes de una reentrada	un crescendo hacia el final de la sección
groove	muestra el producto funcionando (e 0.5-1.2)	el groove completo a energía e
light	lleva una línea densa o una tarjeta llena de texto	el groove sin su figura melódica
muffled	plantea un hecho serio, una estadística, un problema	el groove con filtro paso bajo, abriéndose hacia la siguiente sección
breath	se mantiene un pulso antes del gran momento	casi silencio; solo suena el sonido del objeto héroe
stop	muestra el producto deliberadamente inactivo (una parada de seguridad, un límite)	batería fuera, un pad sostenido
end	es la tarjeta final	silencio
riser (superposición)	asciende hacia un aterrizaje	un ascensor que termina en el final de la sección

Tipos de señal que cada paleta responde: drop (el gran momento), reentry, final (el logo, luego un silencio total), break (comienza una parada), cut (big para un capítulo), tap, tapTouch, pop, word, chip, node, num, count, fill, bar, key (escritura), dot (el sonido propio del objeto héroe).

Paletas (engine/palettes/)

paleta	encaja	sonido	origen
bright_demo	demostraciones paso a paso, aplicaciones amigables de consumo o SaaS, con voz principal	Pop en Fa mayor a 100 BPM: bombo potente, palmada y chasquido, shaker y pandereta, marimba (muestras VSCO o sintetizadas), bajo punzante, pad aireado, sonido héroe de gota de agua	KIBO v4.5 (A2-bright), elección del propietario; ganó la prueba A/B ciega
drums_launch	películas de lanzamiento y anuncios, revelaciones de producto, con música principal	Batería en vivo en Re menor a 100 BPM: bombo VSCO, caja y fantasmas, hi-hats, congas, cencerro, bajo sincopado, rasgueo de guitarra apagada, stabs de trompeta y trompa	Anuncio de batería de 50 s de Moments (inspirado en la película MacBook Air M5 de Apple), estilo favorito del propietario
soft_pulse	explicadores conceptuales, diagramas, películas con mucha narración	Do mayor a 96 BPM: piano muestreado, sonidos de señal de marimba afinada, batería suave, bajo y pad; las capas entran con la energía y las notas de señal suben a medida que se construye un diagrama	para examples/claude-code/explainer

Todavía como scripts independientes, por portar a la interfaz de paleta: piano y campanas (engine/score.py, Moments v2), banda (engine/score_band.py, un promocional B2B), orquestal y violín solo (examples/ads/orch, examples/ads/violin). Para añadir una paleta, sigue engine/palettes/__init__.py y añade su nombre a tests/test_compose.py: las pruebas demuestran que representa la gramática de secciones (sin bombo en la intro, un respiro silencioso y tarjeta final, batería fuera en la parada, cada señal escuchada, -14 LUFS).

Archivos

• engine/: render.mjs, cues.mjs, stills.mjs, compose.py + palettes/, audio.py (buses, sampler, sala), synccheck.py, beatmap.py y bedmix.py (la ruta de pista de biblioteca), ref-analyze.py, music-analyze.py, fetch_samples.sh.
• references/: genres.md, music.md, voice.md, capture.md, qa.md, transitions.md, youtube-analysis.md, aside-capture.md, ads/.
• tests/: python -m pytest -q tests/ (mapa de ritmo, mezcla de biblioteca, puerta de sincronización, gramática de secciones en cada paleta).

Restricciones del resumen y la entrega

• Usa la duración, los idiomas, la relación de aspecto y el destino solicitados. Para un concurso, lee sus reglas reales y verifica la duración con ffprobe; no heredes los límites de un concurso anterior.
• Muestra metraje real del producto o salida real para las afirmaciones de funciones, y respeta los permisos de marca y activos del usuario. Identifica muestras no oficiales sobre otro producto, como hacen las muestras de Claude Code.
• Prepara primero los entregables locales. Sube solo cuando el usuario haya autorizado el destino y la visibilidad.