¿Qué hace REEL-FROM-SCRIPT · v7?
Una habilidad para crear un reel 9:16 con apariencia art-direction y que no pueda salir mal, a partir de un guion que no escribiste, una referencia que debes desmantelar y un chat nuevo sin memoria del anterior.
v5 entregó diseños (layouts) y codificó el diseño en ellos. v6 movió cada número a PARAMS.json y colocó un validador antes del renderizado. v7 es lo que dos reels reales le enseñaron a v6: el ciclo de seis colores de campo, el póster de portada, la animación de tarjeta por escena, los tramos de escena contiguos, los wipes adaptativos, las trampas de audio y un único ./build.sh + scripts/qc.py que se niega a entregar un producto defectuoso.
La promesa: el único archivo que un humano edita es
PARAMS.json. Lo único que puede decir no esprepare.py/qc.py. Todo lo demás se genera, y todo lo generado es reproducible desde un solo comando.
0 · Si eres nuevo aquí: los primeros 10 minutos
export PATH=/home/user/node22/bin:$PATH # Node >= 22
cd <project> && ./build.sh --from render # o sigue el §3 desde el principio
Luego lee, en este orden: §1 (cómo se construye el aspecto visual) → §3 (el pipeline) → §6 (manual de diseño) → §9 (catálogo de fallos). No inventes un diseño: el esqueleto es el diseño.
Nunca hagas estas cuatro cosas: escribir una duración (mide la VO), pegar un hex o un px en una composición (cambia PARAMS.json), escribir index.html a mano (generarlo), o enviar sin mirar la hoja de contactos.
1 · Por qué el resultado se ve diseñado (las siete leyes)
Estas son las decisiones reales detrás de cada buen fotograma de esta serie. Son reglas, no gustos.
1. Una cuadrícula de anclaje, fija en la parte inferior. Kicker → hero → cuerpo → chip → presentador. La mitad inferior nunca se mueve: el chip siempre está en la misma y, el presentador siempre está recortado por el fotograma en el mismo lugar. Solo la mitad superior se recompone. Es por eso que nueve escenas diferentes se leen como una sola película.
2. El héroe es una palabra, no una oración. 1–3 palabras, en una tipografía display condensada a ~17–25 % del ancho del fotograma, interlineado ajustado (0.88). La línea completa va en el chip (3–6 palabras, lo que un espectador con el volumen silenciado lee), el detalle va en la tarjeta. Si no puedes decirlo en 3 palabras, el beat son dos beats.
3. Cada beat tiene un fondo diferente. Seis campos (crema / granate / casi negro / salvia / azul marino / lavanda) ciclados para que no haya dos vecinos iguales. El cambio de color es la otra mitad de la transición. prepare.py falla el build si dos escenas consecutivas comparten un campo.
4. Prueba, no decoración. Una tarjeta existe para mostrar la cosa: una lista de archivos, un diff, un navegador, una subida, un medidor. Si un beat no tiene artefacto, es type-led y no tiene tarjeta. Una tarjeta con dos filas se ve rota; de cuatro a seis filas se ve deliberada (o un mockup que llena ≥ 55 % de la tarjeta).
5. El primer fotograma es un póster. La Escena 1 se compone en t=0 (data-cover="1"): kicker, héroe, tarjeta y personaje ya en pantalla, el chip aterrizando a los 0.65 s. Un reel que se abre en un campo vacío pierde el scroll.
6. El movimiento es solo transform, y aterriza temprano. Las entradas son de 0.24–0.34 s, power2/3/4.out, y terminan en la primera mitad del beat. Nunca animes contenido de texto, nunca interpoles un número, nunca dejes que una escena de 1.5 s gaste 0.6 s en un wipe. Un desplazamiento lento en el héroe mantiene vivo el último segundo.
7. El sonido es puntuación, no wallpaper. ≤ 1 señal por segundo: un pop en cada corte, ticks clave en la UI, un riser en los dos giros más grandes, un chime en la revelación, un notify/ping en el CTA. Cama a 0.15 por debajo de una VO a −16 LUFS; master −14 LUFS / ≤ −1 dBTP.
2 · El contrato: lo que está fijo, lo que es tuyo
Invariante — validado, no editable por sensaciones
| Invariante | Aplicado por |
|---|---|
| Cada par texto/fondo legible | WCAG ≥ 4.5:1 en 10 pares renderizados + 6 pares de campo |
| El héroe es un héroe y siempre encaja | ≥ 120 px, tamaño derivado, debe caber en --hero-lines dentro de --hero-band |
| El héroe no toca el kicker, nunca toca la tarjeta | banda derivada + --gap, fallo duro |
| Cuerpo de texto legible en un teléfono | ≥ 24 px y ≥ bodyMin |
| Nada se oculta bajo la UI de la plataforma | fondo del chip ≤ fondo de la zona segura, ≥ 55 % utilizable |
| El chip nunca puede chocar con la tarjeta | cardTop + cardHmax ≤ chipTop |
| El presentador recortado por el fotograma, nunca sobre el chip | presenterTop + h > 1.0, presenterTop ≥ chipBottom |
| Dos escenas consecutivas nunca comparten un campo | data-field leído de cada composición |
| El fotograma 0 es una portada | data-cover + un gate de snapshot |
| Una pose diferente en cada escena | un archivo de pose por escena, verificado en la revisión |
| El entregable se puede reproducir y es suficientemente fuerte | qc.py: resolución, fps, fotogramas, LUFS, pico verdadero, silencios |
Variable — genuinamente tuyo: valores de paleta (6 campos + 4 tonos de papel, dependiendo del contraste) · formato (9:16, 4:5, 1:1, 720p) · márgenes de zona segura · cada proporción de cuadrícula y tipo dentro del piso · arquetipo por escena · número de escenas · palabras · duración · conjunto de poses · hoja de señales · fuentes en disco.
Si quieres un diseño que el validador no pueda verificar, cambias el esqueleto y agregas la verificación. Ese es el precio de la libertad, y es por eso que el resultado no puede ser malo.
3 · El pipeline (el orden no es negociable)
| # | Paso | Comando | Por qué aquí |
|---|---|---|---|
| 0 | Desmantelar la referencia | §4 | no puedes igualar un aspecto que no has medido |
| 1 | Hechos | — | una afirmación que llega tarde obliga a una regrabación |
| 2 | Guion → secciones | assets/vo/sections.json | una idea por beat, 1.2–9 s |
| 3 | VO primero | python3 scripts/process_vo.py | timeline.json es el reloj; la imagen se corta a él |
| 4 | Aspecto | PARAMS.json | paleta, formato, cuadrícula, piso de tipo |
| 5 | Gate | python3 scripts/prepare.py | falla en contraste / tipo / colisión / ritmo de campo |
| 6 | Escenas | ./scenes.sh | una llamada new_scene.py por beat, tokens inyectados |
| 7 | Raíz | python3 scripts/build_index.py | tramos contiguos, wipes adaptativos, sin index.html escrito a mano |
| 8 | Lint | npx --yes [email protected] lint | 0 errores es un gate |
| 9 | Míralo | npx … snapshot --at "0,1.5,4,…" | el único paso que detecta "correcto pero feo" |
| 10 | Renderizar | npx … render --output renders/_raw.mp4 | ~1 m 45 s para 32 s a 1080×1920, software GL |
| 11 | Mezclar | python3 scripts/mix_audio.py | VO + cama + señales → renders/master.wav (−14 LUFS) |
| 12 | Mux + entregar | build.sh paso 6–7 | mp4 + .srt + thumbs, luego qc.py |
./build.sh ejecuta 3 → 12 de una sola vez. ./build.sh --from render se salta la VO cuando ya está medida.
Paso 3 en detalle — la VO es el reloj
# un clip por sección, llamado vo1.mp3 … voN.mp3 en assets/vo/
python3 scripts/process_vo.py
Recorta silencios, aplica atempo solo si script_target está configurado, normaliza la sonoridad de cada take a −16 LUFS, luego escribe assets/vo/timeline.json: inicio/duración/fin por sección + root_duration. A ningún paso posterior se le permite conocer una duración que no esté en este archivo.
Escribe say en devanagari con palabras técnicas en inglés en latín (resume, job description, ATS score, DM) — una voz hi-IN obtiene la prosodia correcta y aún dice las palabras en inglés. caption es lo que muestra el .srt.
Paso 7 en detalle — la raíz es mecánica
build_index.py encuentra compositions/s*.html en orden numérico, lee los tramos medidos, los hace contiguos (0 → corte → corte → … → raíz, para que no aparezca un agujero negro donde la VO tiene un espacio de 0.30 s), dispara un wipe 0.36 s antes de cada corte en el color de la escena que llega, y mantiene la última escena hasta la cola de audio. Un wipe se acorta al 34–62 % de la longitud de una escena corta — una escena de 1.4 s no puede contener un wipe de 0.62 s.
Paso 11 en detalle — las dos trampas de audio
alimitertienelevel=truepor defecto: vuelve a subir automáticamente al techo, por lo que tu "limitador" se convierte en un compresor + ganancia de maquillaje y la mezcla cae en −12.5 LUFS mientras apuntas a −14. Siemprelevel=false.loudnormen una sola pasada lineal sobrepasa. Mide conebur128, mueve exactamentetarget − measured, luego limita. La aritmética que puedes verificar supera a un filtro que adivina.
4 · Fase 0 — desmantelar un video de referencia
Cuando el brief es "mira esto y emparéjalo", mídela. Diez minutos, cinco comandos:
ffprobe -v error -show_entries format=duration:stream=width,height,r_frame_rate,codec_type -of default=nw=1 ref.mp4
ffmpeg -i ref.mp4 -vf "fps=1,scale=400:-1,tile=6x6" -frames:v 1 sheet.jpg # toda la película como una imagen
python3 - <<'P' # la paleta de campo, por segundo
from PIL import Image; import glob
for f in sorted(glob.glob("frames/f_*.jpg"))[::2]:
im = Image.open(f).convert("RGB"); w,h = im.size
print(f[-7:-4], im.getpixel((3,3)), im.getpixel((w-4,3)))
P
ffmpeg -i ref.mp4 -vn -ac 1 -ar 16000 -c:a pcm_s16le audio.wav # para el guion
Extrae de eso: duración y ritmo de corte (cuánto dura cada beat), la paleta de campo (muestrear esquinas, no el centro), comportamiento tipográfico (¿mayúsculas condensadas? ¿construcciones palabra por palabra? ¿cajas de resaltado?), diseño (dónde se sienta el personaje, dónde se sienta el bloque de texto), artefactos de UI (qué mockups), sonido (densidad de señales). Esos seis números son toda la dirección de arte.
Si el brief te dio una referencia pero ningún guion, la referencia es el guion: transcribe el audio (faster-whisper, int8, modelo base → ~7 s para 32 s de Hinglish) y lee el texto en pantalla de los fotogramas. No reescribas el texto — una serie tiene una voz.
Traduce, no copies. La referencia aquí era 1280×720; el entregable era 1080×1920. Misma paleta, mismo tipo, mismos mockups — pero la banda del héroe, el anclaje del chip y el recorte del presentador se redirigieron como proporciones. En 9:16 los bloques de 8–10 palabras de la referencia caen por debajo del piso del cuerpo de 24 px, por lo que el texto se divide de manera diferente: héroe 1–3 palabras, chip la línea, tarjeta el detalle.
5 · Archivos
PARAMS.json el único archivo de diseño
tokens.css recibo generado (no editar)
index.html generado por build_index.py (no editar)
SKILL.md · COMPONENTS.md · README.md
build.sh todo el pipeline
scenes.sh cada escena, de forma reproducible
components/ 7 cuerpos de tarjeta que puedes pasar con --card-body @…
compositions/
_scene-base.html.tmpl EL esqueleto — cero literal hex, cero literal px
wipe.html la única transición
sN-*.html generado por new_scene.py
_examples/ tres escenas trabajadas (no montadas: build_index solo lee compositions/s*.html)
scripts/
process_vo.py VO → timeline.json
prepare.py el gate: piso + inyección de tokens
new_scene.py plantilla base → una escena correcta
build_index.py timeline + escenas → raíz
mix_audio.py VO + cama + señales → master.wav
make_deliverables.py .srt + thumbs
qc.py un comando, PASS/FAIL en 10 gates
cutout.py · gen_sfx.py activos
assets/{fonts,presenter,vo,sfx,music}/
6 · Manual de diseño (qué elegir realmente)
Beat → arquetipo. Prueba → card-led. Un número → stat-led (odómetro, --digits). Una declaración, una transición, una tarjeta de marca → type-led. Hook y CTA son casi siempre card-led porque ambos necesitan un artefacto (la lista de archivos que prueba el problema; el hilo de comentarios que prueba el CTA).
Beat → campo. Alterna cálido y frío; nunca repitas. Un ciclo práctico para seis campos: acento → suelo → tinta → secundario → terciario → cuaternario. Los campos oscuros (tinta, terciario) hacen desaparecer al presentador, por lo que el halo va de 0.20 → 0.42 allí (el esqueleto hace esto desde data-field); úsalos para la revelación de la herramienta y el beat de "la IA hace el trabajo", donde el drama ayuda.
Beat → pose. Mismo personaje, mismo atuendo, una pose por escena, emparejada con la emoción de la línea: encogerse de hombros (una pregunta) · palmada en la cara (el problema) · presentar (la oferta) · barbilla (curioso) · memoria (recuerdo) · pulgares (la victoria) · señalar (un paso) · idea (el aha) · CTA (la petición). Genera una pose faltante a partir de la imagen base y haz mate con cutout.py; mantén la regla del suelo blanco y el recorte a medio muslo para que se recorten limpiamente.
Palabras en pantalla. Héroe: el verbo emocional o el número (¿EL MISMO CURRÍCULUM?, PERSONALIZA KARO, TAILOR, PUNTUACIÓN ATS). Chip: la oración que un espectador con el volumen silenciado necesita (¿estás enviando a todas las empresas?). Título de tarjeta: qué es el artefacto (solicitado / 12 empresas). Meta de tarjeta: un pequeño dato verdadero (esta semana, coincidió en 3 de 7).
Cuando un beat es demasiado corto para diseñar (1–2 s). Mantén la escena, elimina la segunda capa: héroe + chip + presentador, type-led, una sola revelación. No aprietes una tarjeta y una lista escalonada en 1.4 s — se lee como un fallo.
Cuando un beat es largo (8–9 s, normalmente el CTA). Escenifica tres revelaciones con 1.8–2 s de diferencia (comentario → DM → enlace) y deja que un desplazamiento lento lleve la cola. Un fotograma estático de 8 s es la causa única más común de "se ve barato".
Transiciones. Un wipe, 0.34–0.62 s, color = el campo de la escena que llega, dirección alternada. Ningún otro tipo de transición: la consistencia es lo que hace que ocho cortes se sientan autorales.
El último segundo. El fotograma final debe ser un fotograma diseñado con el handle y el sitio web — el espectador que pause allí debería poder actuar.
7 · Manual de audio
| Momento | Señal | Ganancia |
|---|---|---|
| cada corte | pop | 0.50 |
| los dos giros más grandes | riser 0.3 s antes del corte | 0.28–0.30 |
| un elemento de UI que aterriza | click, key | 0.38–0.45 |
| una lista que entra | key ×N, 0.12 de separación | 0.40 |
| una revelación / puntuación | chime | 0.36–0.42 |
| CTA | notify, luego ping 1.7 s después | 0.32–0.40 |
| incorrecto / rechazado | error (con moderación — se lee como comedia solo una vez) | 0.30 |
Los offsets de las señales son relativos a la sección en assets/sfx/cues.json ("vo7+1.68"), por lo que una VO regrabada no invalida el diseño. Nunca aterrices una señal en la primera sílaba de una palabra; un tick pertenece 20–60 ms después.