Pipeline HTML a MP4 (Explicador 9:16, VO + SFX → MP4)
Alura probada. Cada paso tiene comandos listos para usar en assets/pipeline/.
Referencia de implementación completa: assets/pipeline/index.fc-reference.html (proyecto
Function Calling — copia y reemplaza el contenido, no escribas desde cero).
Por qué este pipeline
- Determinista: línea de tiempo GSAP
paused, se busca por frame → MP4 = vista previa. - VO propia del usuario (archivo ElevenLabs/mic), no TTS; el tempo se controla.
- Auditoría de layout automática detecta texto fuera del canvas y colisiones con elementos — debe pasar antes del renderizado completo (ahorra renderizar 1338 frames).
- Líneas de conexión limpias: ancladas en el borde del nodo, en la capa trasera (ver Error #1).
Principios fundamentales (esto es clave)
Lo visual sirve al guión y a la VO, no al revés.
- Todo lo que aparece en pantalla debe estar en el guión y ser mencionado en la VO. Elementos atractivos pero no narrados → elimínalos, por buenos que sean.
- Inversamente, cada idea/frase importante en el guión debe tener su propia imagen que aparezca cuando se dice esa frase. Frases que solo son texto estático = escenas "vacías" → añade visual.
- No importa tener muchas escenas — lo importante es que cada escena siga la VO y el guión.
- Cuantas más imágenes y animaciones, mejor (más dinámico). No seas tacaño al añadir imágenes; la riqueza visual es un valor añadido, no una debilidad.
- El orden y la sincronización visual = orden y sincronización de la mención en la VO (según los timestamps de la transcripción), no según tu propia lógica.
- La calidad de los detalles visuales también se cuida: los iconos se leen claramente, los elementos están equilibrados y no flotan.
Flujo (sigue el orden)
| # | Paso | Salida |
|---|---|---|
| 1 | Toma la VO del usuario + divídela por segmentos (pausas de respiración) | meta.json |
| 2 | Ajusta el tempo de la VO con ffmpeg atempo + inserta pausas; elige variante | vo.wav |
| 3 | Transcripción por palabra (faster-whisper, pip install faster-whisper) | assets/words.json |
| 4 | Construye index.html (8 escenas siguiendo la sincronización de la VO) + sfx_score.py | HTML + WAV de SFX |
| 5 | Mezcla VO + SFX → public/full_mix.mp3 | audio final |
| 6 | Auditoría de layout (audit2.mjs + audit_s2.mjs) — obligatorio 0 desbordamientos | informe |
| 7 | Renderiza frames (render_frames.mjs) → 1338 PNG | frames/ |
| 8 | Codifica (encode.sh) → MP4 | public/*.mp4 |
| 9 | Verifica visualmente el MP4 final — extrae frames del MP4, analiza con visión | confirmación limpia |
Configuración única
cd <proyecto>
npm init -y && npm install playwright-core gsap
pip install faster-whisper # para transcripción por palabra
# necesario: Google Chrome (/Applications/Google Chrome.app), ffmpeg
Scripts del pipeline
assets/pipeline/:
render_frames.mjs— busca la línea de tiempo por frame, captura 1080×1920 @30fps.snap.mjs— captura segundos específicos (node snap.mjs 1.0 6.5 17.5) para verificar visual.audit2.mjs— verifica TODAS las escenas: texto fuera del canvas / dentro de zona UI inferior (>1560px) / colisiones.audit_s2.mjs— audita 1 escena (sc2) en múltiples segundos (detecta revelaciones demasiado tempranas, bordes ajustados).audit_overlap.mjs— detecta texto que REALMENTE se superpone (texto×texto, texto×img, texto×botón). Distingue inteligentemente entre colisiones reales y las de diseño: etiquetas dentro de un contenedor svg, garabatos/tachados/líneas que atraviesan, subtítulos flexibles uno al lado del otro → no se reportan. Ejecutanode assets/pipeline/audit_overlap.mjs→ objetivoTOTAL superposiciones: 0.audit_center.mjs— detecta contenido "colgando arriba" (2/3 inferior vacío). Mide los límites del contenido de cada escena, calcula la desviación del punto central ideal (y≈960 para 1920px). Desviación > 250px = ⚠ COLGANDO. Ejecutanode assets/pipeline/audit_center.mjs.typing-prompt.js— receta de animación "typing prompt" (tema central coding/AI): el prompt se escribe letra por letra + cursor parpadeante, luego la app responde (cambia color → error → corrige → itera). Ejemplo completo: repo video09-vibe-coding/index.htmlescena SK4.encode.sh— ffmpeg → H.264 yuv420p CRF18 + AAC 192k ++faststart.sfx_score.py— puntuación de SFX procedural sincronizada con el tiempo de las palabras.index.fc-reference.html— implementación completa (copia y reemplaza el contenido).
Convenciones HTML (en index.fc-reference.html)
#stage1080×1920, fondo dot-grid;#world(cámara rig, escala suave por escena); escenas =.scene(visibility hidden, se muestran/ocultan mediante la línea de tiempo).- Subtítulos por palabra:
assets/words.json→ agrúpalos en fragmentos de ≤4 palabras, un fragmento = una.line(position:absolute, apilados para no expandir la caja), palabra activa.on, palabra clave.key(ámbar). Posición 390px desde abajo (seguro frente a la UI de Reels/TikTok que cubre ~360px inferiores). - Líneas de conexión: función
link(svg,idA,idB)calcula el anclaje en el BORDE del nodo (edge/edgeT) — la línea NO sale del centro del logo. SVG.wiresse coloca como primer hijo de.scene(z-index:0) para que esté detrás de las tarjetas (z-index:2). Curva suave (bow ≤26px), color gris#7A81888px; línea activa.hotámbar 15px. - Logo del agente:
OPENCLAW_SVGinline (langosta roja), se coloca automáticamente en cada.node.darkque contenga🤖. Cambia si deseas otra identidad. - GSAP determinista: línea de tiempo
paused, exponewindow.__tlywindow.__updateSub. Modo?t=<segundos>para captura estática (headless),?debugpara desplazamiento manual.
Activación (trigger)
El usuario menciona la frase "pipeline motion explainer", o pide "video motion
explainer 9:16", o dice "como el video de Function Calling de ayer" → carga este skill.
No es motion-format / bang-motion (otros skills). La VO del usuario siempre se envía como
archivo en cada sesión — este skill almacena el CÓMO FUNCIONA, no los activos de audio/contenido.
Errores comunes (no los repitas)
- Líneas que atraviesan el logo/texto → asegúrate de: (a) SVG wires sea el primer hijo de la escena,
(b)
z-index:0wires vsz-index:2tarjetas, (c) anclaje usandolink()en el borde. - Subtítulos que tapan tarjetas / entran en zona UI → una línea por pila (absolute), máximo 4 palabras/fragmento, bottom ≥390px.
window.tlundefined al renderizar → el nombre expuesto debe serwindow.__tl(con__), de lo contrario el 74% de los frames serán idénticos/estáticos. Verifica:md5 frames/* | uniq -c.- Renderizado de fondo reiniciado → asegúrate de que no haya
render_framesantiguo ejecutándose (pgrep -fl render_frames) antes de un nuevo render; eliminaframes/antes de empezar. - La auditoría DOM no sustituye a la verificación visual del MP4. La auditoría detecta desbordamientos y colisiones
de bounding-box, pero NO detecta líneas que atraviesan el logo / texto que tapa tarjetas —
eso solo se ve en los píxeles finales. Después de codificar, extrae fotogramas clave del MP4
(
ffmpeg -ss <t> -i out.mp4 -frames:v 1 f.png) y luego analiza con vision_analyze. - Contenido "colgando arriba" (2/3 inferior vacío). Esto suele pasar desapercibido porque
la auditoría normal solo verifica desbordamientos, no el equilibrio. Causa: todos los hijos de
.herousanposition:absolute→justify-content:centerde flexbox NO tiene efecto sobre ellos. Solución: convierte a los hijos de.heroen flujo normal (block/flex flow), solo los elementos superpuestos (badge/garabatos/marcadores) se quedan como absolute. ES OBLIGATORIO ejecutaraudit_center.mjs— desviación del centro > 250px = fallo. - Lo visual no sigue el guión (lo más destructivo). No asumas que una escena "está bien" solo porque su
animación funciona. Ejemplo real: gráficos de correlación y gráficos de edad aparecen en pantalla
aunque la VO nunca los menciona. Auditoría obligatoria del guión antes del render: (a) extrae
la transcripción de la VO + timestamp por palabra (
words.json), (b) mapea "¿esta frase aparece a qué hora en pantalla?", (c) elementos que aparecen pero no están en el guión → elimínalos; frases del guión que solo son texto estático → añade visual. El orden visual = orden de mención en la VO. - Renderizado OOM (Mac 8GB). Chromium acumula memoria al capturar cientos de screenshots → se cierra a mitad de camino ("Target page closed"). Solución: reinicia el navegador cada ±400 frames + reanudación automática (salta los frames que ya existen y tienen >20KB). No renderices 2500+ frames en una sola sesión del navegador.
- Frames antiguos mezclados después de una revisión. Si solo se revisan algunas escenas y solo se eliminan
los frames de ese rango,
frames/se vuelve una mezcla (ej. 2770 archivos cuando se necesitan 2574). Lo más seguro: elimina todoframes/antes del render completo. Si reanudas, verifica que el número de archivos = TOTAL de frames antes de codificar. - Emojis que escapan de la auditoría DOM. El usuario pide sin emojis — si no se verifica automáticamente, los emojis
pueden colarse porque la auditoría de bounding-box no mira el tipo de carácter. Antes del render, ejecuta
una regex de Python para buscar caracteres emoji; si encuentras → reemplázalos con SVG inline. Los iconos siempre son SVG.
re.findall(r'[\U0001F300-\U0001FAFF\u2600-\u27BF\u2B00-\u2BFF\uFE0F]', html)→ debe dar 0. - Los iconos y detalles visuales deben ser legibles en su TAMAÑO DE VISUALIZACIÓN — la auditoría DOM y la auditoría de layout no detectan "el icono no se entiende". Un SVG puede tener la forma correcta en el código pero en el tamaño renderizado (ej. icono de 180px en un diagrama) parece otra cosa: un icono de cerebro con contorno abierto se lee como nube/flor, no como cerebro. Solución: antes del render completo, extrae un frame del MP4 y amplía (recorta) los iconos/diagramas clave y evalúa con vision_analyze — "¿esto se lee claramente como X?". Si es ambiguo, simplifica la forma (silueta completa > contorno abierto) y aumenta su tamaño. La auditoría de bounding-box solo verifica la posición, no la legibilidad de la forma.
- Los elementos de comparación (barra/columna A-vs-B) deben estar en un solo grupo visual. Las barras que
"flotan" fuera de su tarjeta contenedora (posición absoluta separada) rompen el equilibrio y son
propensas a superponerse a otros elementos cuando el contenido cambia de altura. Caso real: barras de
músculo atrofiado/fuerte flotando fuera de la tarjeta de gimnasio, y luego chocan con la tarjeta.
Solución: mete cada barra DENTRO de su propia tarjeta/celda de columna; la diferencia de longitud
de las barras es intencionada (longitud = magnitud), pero el ancho de la tarjeta y la línea base deben
ser iguales. Verifica con
audit_overlapdespués de cada revisión de layout. - Texto superpuesto aunque parezca "solo un poco". No confíes en el ojo; usa
audit_overlap.mjsque mide los bounding-box reales. Un signo?gigante, números decorativos grandes, o títulos largos suelen cubrir otro texto sin que te des cuenta. - El tema coding/AI se siente muerto sin animación de escritura. El texto estático no transmite
cómo funciona vibe coding. Usa la receta
typing-prompt.js: el prompt se escribe letra por letra + cursor parpadeante + la app responde (cambia color → error → corrige → itera). - Logo/icono de la web: descarga el SVG oficial (CDN jsDelivr / repositorio GitHub de la marca), luego
ponlo inline como texto en el HTML — no uses
<img src>a un archivo externo, para que el render headless no dependa de la red. Elimina las animaciones SMIL para que la salida sea determinista.
Reglas de audio (usuario Hasbi)
- La VO de producción debe ser la propia voz del usuario (archivo ElevenLabs enviado), no TTS.
- SFX procedural a través del skill
procedural-sfx(sin crédito a ElevenLabs). - Elimina los frames en bruto y los archivos auxiliares (
frames/,shots/,*.wavpor segmento) después de que el MP4 se haya entregado — el almacenamiento del MacBook es limitado.