Communitygithub.com

zengbaocheng/hermes-tech-hub

Crea composiciones de video basadas en HTML, tarjetas de título animadas, superposiciones para redes sociales, videos con subtítulos sincronizados, visuales reactivas al audio y transiciones con shaders usando HyperFrames. El HTML es la fuente de verdad para el video.

¿Qué es hermes-tech-hub?

HyperFrames es un sistema de composición de video donde el HTML actúa como la fuente de verdad, permitiendo crear videos MP4/WebM renderizados a partir de animaciones HTML/CSS/JS. Es especialmente útil para productores de contenido, desarrolladores y creadores que necesitan automatizar la generación de videos con animaciones complejas, subtítulos sincronizados con audio, narración TTS, y transiciones entre escenas utilizando shaders. La habilidad se integra con el ecosistema de HyperFrames, ofreciendo un CLI completo (init, lint, preview, render) y soporte para múltiples plataformas (Instragram, TikTok, YouTube). El flujo de trabajo incluye planificación del diseño visual (con generación automática de DESIGN.md), scaffolding de proyectos, animación con GSAP (sin repeticiones infinitas), y renderizado final con FFmpeg. Complementa a `manim-video` para animaciones matemáticas, mientras que HyperFrames se enfoca en motion graphics, superposiciones sociales y transiciones con shaders.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/zengbaocheng/hermes-tech-hub/tree/HEAD/creative/hyperframes

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

HyperFrames

HTML es la fuente de verdad para el video. Una composición es un archivo HTML con atributos data-* para la temporización, una línea de tiempo GSAP para la animación y CSS para la apariencia. El motor de HyperFrames captura la página fotograma a fotograma y la codifica a MP4/WebM con FFmpeg.

Complemento de manim-video: Usa manim-video para explicaciones matemáticas/geométricas (ecuaciones, estilo 3B1B). Usa hyperframes para gráficos en movimiento, videos con Creador y subtítulos, recorridos de productos, superposiciones para redes sociales, transiciones con shaders y cualquier cosa impulsada por medios de video/audio reales.

Cuándo Usar

  • El usuario solicita un video renderizado a partir de texto, un guion o un sitio web
  • Tarjetas de título animadas, tercios inferiores o intros tipográficas
  • Video de narración con subtítulos (TTS + subtítulos sincronizados con la forma de onda)
  • Visuales reactivos al audio (sincronización de ritmo, barras de espectro, brillo pulsante)
  • Transiciones de escena a escena (fundido cruzado, barrido, deformación con shader, fundido a blanco)
  • Superposiciones para redes sociales (estilo Instagram/TikTok/YouTube)
  • Pipeline de sitio web a video (capturar una URL, producir un promocional)
  • Cualquier animación HTML/CSS/JS que deba renderizarse de forma determinista a un archivo de video

No uses esta habilidad para:

  • Animación pura de matemáticas/ecuaciones (→ manim-video)
  • Generación de imágenes o memes (→ meme-generation, modelos de imagen)
  • Videoconferencias o streaming en vivo

Referencia Rápida

npx hyperframes init mi-video               # crear un proyecto
cd mi-video
npx hyperframes lint                        # validar antes de previsualizar o renderizar
npx hyperframes preview                     # previsualización en vivo en el navegador (puerto 3002)
npx hyperframes render --output final.mp4   # renderizar a MP4
npx hyperframes doctor                      # diagnosticar problemas del entorno

Banderas de renderizado: --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproducible) · --strict.

Referencia completa del CLI: references/cli.md.

Configuración (única vez)

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

El script:

  1. Verifica que Node.js >= 22 y FFmpeg estén instalados (muestra instrucciones de corrección si no).
  2. Instala el CLI hyperframes globalmente (npm install -g hyperframes@>=0.4.2).
  3. Precarga chrome-headless-shell a través de Puppeteer — requerido para renderizado de mejor calidad mediante la ruta de captura HeadlessExperimental.beginFrame de Chrome.
  4. Ejecuta npx hyperframes doctor e informa el resultado.

Consulta references/troubleshooting.md si la configuración falla.

Procedimiento

1. Planificar antes de escribir HTML

Antes de tocar código, articula a alto nivel:

  • Qué — arco narrativo, momentos clave, ritmos emocionales
  • Estructura — composiciones, pistas (video/audio/superposiciones), duraciones
  • Identidad visual — colores, fuentes, carácter del movimiento (explosivo / cinematográfico / fluido / técnico)
  • Fotograma héroe — para cada escena, el momento en que la mayoría de los elementos son visibles simultáneamente. Este es el diseño estático que construirás primero.

Puerta de Identidad Visual (PUERTA DURA). Antes de escribir CUALQUIER HTML de composición, se debe definir una identidad visual. NO escribas composiciones con colores predeterminados o genéricos (#333, #3b82f6, Roboto son indicios de que se saltó este paso). Verifica en orden:

  1. ¿DESIGN.md en la raíz del proyecto? → Usa sus colores, fuentes, reglas de movimiento exactas y restricciones "Qué NO Hacer".

  2. ¿El usuario nombró un estilo? (ej. "Pulso Suizo", "oscuro y tecnológico", "marca de lujo") → Genera un DESIGN.md mínimo con ## Prompt de Estilo, ## Colores (3-5 hex con roles), ## Tipografía (1-2 familias), ## Qué NO Hacer (3-5 anti-patrones).

  3. ¿Nada de lo anterior? → Haz 3 preguntas antes de escribir cualquier HTML:

    • ¿Estado de ánimo? (explosivo / cinematográfico / fluido / técnico / caótico / cálido)
    • ¿Lienzo claro u oscuro?
    • ¿Algún color de marca, fuente o referencia visual?

    Luego genera un DESIGN.md a partir de las respuestas. Cada composición debe rastrear su paleta y tipografía hasta DESIGN.md o una dirección explícita del usuario.

2. Crear el proyecto

npx hyperframes init mi-video --non-interactive

Plantillas: blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Usa --example <nombre> para elegir una, --video clip.mp4 o --audio track.mp3 para inicializar con medios.

3. Diseño antes de animación

Escribe el HTML+CSS estático para el fotograma héroe primero — aún sin GSAP. El contenedor .scene-content debe llenar la escena (width:100%; height:100%; padding:Npx) con display:flex + gap. Usa padding para empujar el contenido hacia adentro — nunca uses position: absolute; top: Npx en un contenedor de contenido (el contenido se desborda cuando es más alto que el espacio restante).

Solo después de que el fotograma héroe se vea bien, agrega entradas gsap.from() (anima hasta la posición CSS) y salidas gsap.to() (anima desde ella).

Consulta references/composition.md para el esquema completo de atributos de datos y reglas de composición.

4. Animar con GSAP

Cada composición debe:

  • Registrar su línea de tiempo: window.__timelines["<id-composición>"] = tl
  • Iniciar en pausa: gsap.timeline({ paused: true }) — el reproductor controla la reproducción
  • Usar valores de repetición finitos (sin repeat: -1 — rompe el motor de captura). Calcula: repeat: Math.ceil(duración / duraciónCiclo) - 1.
  • Ser determinista — sin Math.random(), Date.now() o lógica de reloj real. Usa un PRNG con semilla si necesitas pseudoaleatoriedad.
  • Construirse sincrónicamente — sin async/await, setTimeout o Promesas alrededor de la construcción de la línea de tiempo.

Consulta references/gsap.md para la API central de GSAP (tweens, eases, escalonamiento, líneas de tiempo).

5. Transiciones entre escenas

Las composiciones de múltiples escenas requieren transiciones. Reglas:

  1. Usa siempre una transición entre escenas — sin cortes directos.
  2. Usa siempre animaciones de entrada en cada elemento de la escena (gsap.from(...)).
  3. Nunca uses animaciones de salida excepto en la escena final — la transición ES la salida.
  4. La escena final puede desaparecer gradualmente.

Usa npx hyperframes add <nombre-transición> para instalar transiciones con shaders (flash-through-white, liquid-wipe, etc.). Lista completa: npx hyperframes add --list.

6. Audio, subtítulos, TTS, reactividad al audio, resaltado

  • Audio: siempre un elemento <audio> separado (el video es muted playsinline).
  • TTS: npx hyperframes tts "Texto del guion" --voice af_nova --output narración.wav. Lista voces con --list. La primera letra del ID de voz codifica el idioma (a/b=inglés, e=español, f=francés, j=japonés, z=mandarín, etc.) — el CLI infiere automáticamente la configuración regional del fonemizador; pasa --lang solo para anular. La fonemización en idiomas distintos al inglés requiere espeak-ng instalado en todo el sistema.
  • Subtítulos: npx hyperframes transcribe narración.wav → transcripción a nivel de palabra. Elige un estilo según el tono de la transcripción (hype / corporativo / tutorial / narrativa / social — consulta la tabla en references/features.md). Regla de idioma: nunca uses modelos whisper .en a menos que el audio esté confirmado como inglés — .en traduce audio no inglés en lugar de transcribirlo. Cada grupo de subtítulos DEBE tener un tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) de eliminación dura después de su tween de salida — de lo contrario, los grupos se filtran visibles hacia los posteriores.
  • Visuales reactivos al audio: extrae previamente las bandas de audio (bajo / medio / agudo) y muestra por fotograma dentro de la línea de tiempo con un bucle for de tl.call(draw, [], f / fps) — un único tween largo NO reacciona al audio. Asigna bajo → scale (pulso), agudo → textShadow/boxShadow (brillo), amplitud general → opacity/y/backgroundColor. Evita clichés de ecualizador de barras — deja que el contenido guíe lo visual y que el audio conduzca su comportamiento.
  • Resaltado estilo marcador: los efectos de resaltado, círculo, explosión, garabato, subrayado para énfasis de texto son CSS+GSAP deterministas — consulta references/features.md#resaltado-marcador. Totalmente buscables, sin filtros SVG animados.
  • Transiciones de escena: cada composición de múltiples escenas DEBE usar transiciones (sin cortes directos). Elige entre primitivas CSS (deslizamiento, fundido cruzado borroso, zoom a través, bloques escalonados) o transiciones con shaders (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split, etc.) mediante npx hyperframes add. Las tablas de estado de ánimo y energía se encuentran en references/features.md#transiciones. No mezcles transiciones CSS y de shader en la misma composición.

7. Linter, validación, inspección, previsualización, renderizado

npx hyperframes lint              # detecta data-composition-id faltantes, pistas superpuestas, líneas de tiempo no registradas
npx hyperframes validate          # auditoría de contraste WCAG en 5 marcas de tiempo
npx hyperframes inspect           # auditoría visual de diseño — desbordamiento, elementos fuera del fotograma, texto oculto
npx hyperframes preview           # previsualización en vivo en el navegador
npx hyperframes render --quality draft --output draft.mp4    # iteración rápida
npx hyperframes render --quality high --output final.mp4     # entrega final

hyperframes validate muestra los píxeles de fondo detrás de cada elemento de texto y advierte sobre relaciones de contraste por debajo de 4.5:1 (o 3:1 para texto grande). hyperframes inspect es el acompañante del diseño: ejecuta la página en múltiples marcas de tiempo y señala problemas que un linter estático no puede ver (un subtítulo que se envuelve más allá del área segura solo a los 4.5s, una tarjeta que se desborda cuando su título es la variante más larga, un elemento que termina detrás de un shader de transición). Ejecuta inspect especialmente en composiciones con bocadillos, tarjetas, subtítulos o tipografía ajustada.

8. Sitio web a video (si el usuario proporciona una URL)

Usa el flujo de trabajo de captura a video de 7 pasos en references/website-to-video.md: captura → DESIGN.md → SCRIPT.md → storyboard → composición → renderizar → entregar.

Errores Comunes

  • HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ eliminó este protocolo. Asegúrate de estar en hyperframes@>=0.4.2 (detecta automáticamente y recurre al modo de captura de pantalla). Válvula de escape: export PRODUCER_FORCE_SCREENSHOT=true. Consulta hyperframes#294 y references/troubleshooting.md.
  • Chrome del sistema (no chrome-headless-shell) — los renderizados se cuelgan durante 120s y luego expiran. Ejecuta npx puppeteer browsers install chrome-headless-shell (setup.sh lo hace). hyperframes doctor informa qué binario se usará.
  • repeat: -1 en cualquier lugar — rompe el motor de captura. Siempre calcula un recuento de repeticiones finito.
  • gsap.set() en elementos de clip que entran más tarde — el elemento no existe al cargar la página. Usa tl.set(selector, vars, timePosition) dentro de la línea de tiempo, en o después del data-start del clip.
  • <br> dentro del texto de contenido — los saltos forzados no conocen el ancho de fuente renderizado, por lo que el salto natural + <br> causa doble salto. Usa max-width para que el texto se envuelva naturalmente. Excepción: títulos cortos donde cada palabra está deliberadamente en su propia línea.
  • Animar visibility o display — GSAP no puede animar estas propiedades. Usa autoAlpha (maneja tanto visibilidad como opacidad).
  • Llamar a video.play() o audio.play() — el marco de trabajo controla la reproducción. Nunca llames a estos por tu cuenta.
  • Construir líneas de tiempo asincrónicamente — el motor de captura lee window.__timelines sincrónicamente después de cargar la página. Nunca envuelvas la construcción de la línea de tiempo en async, setTimeout o una Promise.
  • index.html independiente envuelto en <template> — oculta todo el contenido del navegador. Solo las sub-composiciones cargadas mediante data-composition-src usan <template>.
  • Usar video para audio — siempre <video> silenciado + <audio> separado.

Verificación

Antes y después del renderizado:

  1. Pasar linter + validación + inspección: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint detecta problemas estructurales, validate detecta contraste, inspect detecta problemas visuales de diseño/desbordamiento — consulta troubleshooting.md si aparecen advertencias).
  2. Coreografía de animación — para composiciones nuevas o cambios significativos de animación, ejecuta el mapa de animación. npx hyperframes init copia los scripts de habilidad en el proyecto, por lo que la ruta es local al proyecto:
    node skills/hyperframes/scripts/animation-map.mjs <dir-composición> \
      --out <dir-composición>/.hyperframes/anim-map
    
    Genera un único animation-map.json con resúmenes por tween, línea de tiempo ASCII Gantt, detección de escalonamiento, zonas muertas (>1s sin animación), ciclos de vida de elementos y banderas (offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s). Escanea resúmenes y banderas — corrige o justifica cada una. Omite en ediciones pequeñas.
  3. Archivo existe + no tiene tamaño cero: ls -lh final.mp4.
  4. La duración coincide con data-duration: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
  5. Verificación visual: extrae un fotograma de la mitad de la composición: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. Audio presente si se espera: ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Si hyperframes render falla, ejecuta npx hyperframes doctor y adjunta su salida al informar.

Referencias

  • composition.md — atributos de datos, contrato de línea de tiempo, reglas no negociables, reglas de tipografía/activos
  • cli.md — todos los comandos CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
  • gsap.md — API central de GSAP para HyperFrames (tweens, eases, escalonamiento, líneas de tiempo, matchMedia)
  • features.md — subtítulos, TTS, reactividad al audio, resaltado con marcador, transiciones (carga bajo demanda)
  • website-to-video.md — flujo de trabajo de captura a video de 7 pasos
  • troubleshooting.md — corrección de OpenClaw, variables de entorno, errores comunes de renderizado

Skills relacionados