Communitygithub.com

LingoJack/jcli

Crea composiciones de video, animaciones, tarjetas de título, superposiciones, subtítulos, voces en off, visuales reactivos al audio y transiciones de escena en HyperFrames HTML.

¿Qué es jcli?

Esta skill de agente de IA está diseñada para guiar la creación de contenido de video utilizando el marco HyperFrames, donde HTML es la fuente de verdad. El agente ayuda a construir composiciones de video completas, desde tarjetas de título y animaciones de texto hasta visuales reactivos al audio y transiciones complejas. Utiliza una metodología estructurada que incluye descubrimiento, expansión de indicaciones y una fase de planificación que prioriza el diseño del estado final antes de la animación, asegurando un diseño robusto sin superposiciones no intencionadas. Soporta variables parametrizadas para la personalización, trabajo con composiciones anidadas y un sistema de pistas para sincronizar clips de video, audio y superposiciones. Esta skill también se integra con herramientas de línea de comandos como `hyperframes-cli` para el ciclo de desarrollo y `hyperframes-media` para el preprocesamiento de activos como conversión de texto a voz o transcripción.

Compatible con~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/LingoJack/jcli/tree/HEAD/.jcli/skills/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 el tiempo, una línea de tiempo GSAP para la animación y CSS para la apariencia. El marco maneja la visibilidad de los clips, la reproducción de medios y la sincronización de la línea de tiempo.

Enfoque

Descubrimiento (solo solicitudes exploratorias)

Para solicitudes abiertas ("haz un video de lanzamiento de producto", "crea algo para nuestra marca") donde el usuario no se ha comprometido con una dirección, comprende la intención antes de elegir colores:

  • Audiencia — ¿quién ve esto? ¿Desarrolladores? ¿Ejecutivos? ¿Consumidores generales?
  • Plataforma — ¿dónde se reproduce? ¿Redes sociales (15s), héroe del sitio web, demostración de producto, interna?
  • Prioridad — ¿qué es lo más importante? ¿Calidad del movimiento? ¿Precisión del contenido? ¿Fidelidad de la marca? ¿Velocidad?
  • Variaciones — ¿el usuario quiere opciones o una sola mejor opción?

Para solicitudes específicas ("agrega una tarjeta de título", "arregla el tiempo de la escena 3"), omite el descubrimiento.

Para solicitudes exploratorias, considera ofrecer 2-3 variaciones que difieran significativamente — no solo cambios de color, sino diferentes ritmos, niveles de energía o enfoques estructurales. Una segura/esperada, una ambiciosa. No es obligatorio — es una herramienta disponible cuando sea apropiado.

Paso 1: Sistema de diseño

Si design.md o DESIGN.md existe en el proyecto, léelo primero (verifica ambas mayúsculas/minúsculas — son archivos diferentes en Linux). Es la fuente de verdad para los colores de la marca, fuentes y restricciones. Usa sus valores exactos — no inventes colores ni sustituyas fuentes. Cualquier formato funciona (YAML frontmatter, prosa, tablas — solo extrae los valores).

Si nombra fuentes que no puedes encontrar localmente (sin directorio fonts/ con archivos .woff2, no es una fuente integrada), advierte al usuario antes de escribir HTML: "design.md especifica [nombre de la fuente] pero no se encontraron archivos de fuente. Agrega archivos .woff2 a fonts/ o recurriré a [la alternativa integrada más cercana]."

Si no existe design.md, ofrécele al usuario una opción:

  1. ¿El usuario nombró un estilo o estado de ánimo? → Lee visual-styles.md para los 8 ajustes preestablecidos con nombre. Elige la coincidencia más cercana.
  2. ¿Quieres explorar opciones visualmente? → Ejecuta el selector de diseño: lee references/design-picker.md para el flujo de trabajo completo. Esto sirve una página de selector visual. El usuario configura el estado de ánimo, la paleta, la tipografía y el movimiento en el navegador, luego copia el design.md generado y lo pega de nuevo en la conversación.
  3. ¿Quieres saltar y ser rápido? → Pregunta: estado de ánimo, claro u oscuro, ¿algún color/fuente de marca? Luego elige una paleta de house-style.md.

design.md define la marca. No define las reglas de composición de video. Esas provienen de references/video-composition.md y house-style.md. Usa los colores de la marca a una escala apropiada para video — no a la opacidad de la interfaz web.

Paso 2: Expansión de la indicación

Siempre ejecútalo en cada composición (excepto piezas de una sola escena y ediciones triviales). Este paso fundamenta la intención del usuario contra design.md y house-style.md y produce un intermediario consistente que todos los agentes posteriores leen de la misma manera.

Lee references/prompt-expansion.md para el proceso completo y el formato de salida.

Paso 3: Planificar

Antes de escribir HTML, piensa a alto nivel:

  1. Qué — ¿qué debería experimentar el espectador? Identifica el arco narrativo, los momentos clave y los latidos emocionales.
  2. Estructura — cuántas composiciones, cuáles son sub-composiciones vs en línea, qué pistas llevan qué (video, audio, superposiciones, subtítulos).
  3. Ritmo — declara tu ritmo de escena antes de implementar. Qué escenas son golpes rápidos, cuáles son sostenidos, dónde aterrizan los sombreadores, dónde alcanza el punto máximo la energía. Nombra el patrón: rápido-rápido-LENTO-rápido-SOMBREADOR-sostenido. Lee references/beat-direction.md para plantillas de ritmo.
  4. Tiempo — qué clips impulsan la duración, dónde aterrizan las transiciones, cuál es el ritmo.
  5. Diseño — construye el estado final primero. Consulta "Diseño antes de la animación" a continuación.
  6. Animar — luego agrega movimiento usando las reglas a continuación.

Construye lo que se pidió. Una solicitud de "una tarjeta de título" no es una solicitud de "una tarjeta de título + 3 escenas de apoyo + música ambiental + subtítulos". Cada escena, cada elemento, cada interpolación debe ganarse su lugar. Si escenas o elementos adicionales mejorarían genuinamente la pieza, propónlos — no los agregues.

Para ediciones pequeñas (corregir un color, ajustar el tiempo, agregar un elemento), salta directamente a las reglas.

Diseño antes de la animación

Posiciona cada elemento donde debería estar en su momento más visible — el fotograma donde ha entrado completamente, está correctamente colocado y aún no está saliendo. Escribe esto como HTML+CSS estático primero. Sin GSAP todavía.

Por qué es importante: Si posicionas los elementos en su estado inicial animado (fuera de la pantalla, escalados a 0, opacidad 0) y los interpolas a donde crees que deberían aterrizar, estás adivinando el diseño final. Las superposiciones son invisibles hasta que el video se renderiza. Al construir el estado final primero, puedes ver y corregir los problemas de diseño antes de agregar cualquier movimiento.

El proceso

  1. Identifica el 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 que construyes.
  2. Escribe CSS estático para ese fotograma. El contenedor .scene-content DEBE llenar la escena completa usando width: 100%; height: 100%; padding: Npx; con display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Usa padding para empujar el contenido hacia adentro — NUNCA uses position: absolute; top: Npx en un contenedor de contenido. Los contenedores de contenido posicionados absolutamente se desbordan cuando el contenido es más alto que el espacio restante. Reserva position: absolute solo para elementos decorativos.
  3. Agrega entradas con gsap.from() — anima DESDE fuera de la pantalla/invisible HASTA la posición CSS. La posición CSS es la verdad fundamental; la interpolación describe el viaje para llegar allí. (En sub-composiciones cargadas a través de data-composition-src, prefiere gsap.fromTo() — consulta las reglas GSAP de carga en references/motion-principles.md.)
  4. Agrega salidas con gsap.to() — anima HASTA fuera de la pantalla/invisible DESDE la posición CSS.

Ejemplo

/* scene-content llena la escena, el padding posiciona el contenido */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* El contenedor llena cualquier tamaño de escena (1920x1080, 1080x1920, etc.).
   El padding posiciona el contenido. Flex + gap maneja el espaciado. */

INCORRECTO — dimensiones codificadas y posicionamiento absoluto:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}
// Paso 3: Animar DENTRO de esas posiciones
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Paso 4: Animar FUERA de esas posiciones
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

Cuando los elementos comparten espacio a lo largo del tiempo

Si el elemento A sale antes de que el elemento B entre en la misma área, ambos deben tener posiciones CSS correctas para sus respectivos fotogramas héroe. El orden de la línea de tiempo garantiza que nunca coexistan visualmente — pero si omites el paso de diseño, no detectarás el caso en que se superponen accidentalmente debido a un error de tiempo.

Qué cuenta como superposición intencional

Los efectos en capas (brillo detrás del texto, elementos de sombra, patrones de fondo) y los diseños apilados en Z (pilas de tarjetas, capas de profundidad) son intencionales. El paso de diseño se trata de detectar superposiciones no intencionales — dos titulares que caen uno sobre el otro, una estadística que cubre una etiqueta, contenido que se sale del encuadre.

Atributos de datos

Todos los clips

AtributoObligatorioValores
idSíIdentificador único
data-startSíSegundos o referencia de ID de clip ("el-1", "intro + 2")
data-durationObligatorio para img/div/composicionesSegundos. El video/audio usa por defecto la duración del medio.
data-track-indexSíEntero. Los clips de la misma pista no pueden superponerse.
data-media-startNoDesplazamiento de recorte en la fuente (segundos)
data-volumeNo0-1 (por defecto 1)

data-track-index no afecta la superposición visual — usa CSS z-index.

Clips de composición

AtributoObligatorioValores
data-composition-idSíID de composición único
data-startSíTiempo de inicio (composición raíz: usa "0")
data-durationSíTiene prioridad sobre la duración de la línea de tiempo GSAP
data-width / data-heightSíDimensiones en píxeles (1920x1080 o 1080x1920)
data-composition-srcNoRuta a un archivo HTML externo
data-variable-valuesNoObjeto JSON de anulaciones de variables por instancia en un host de sub-comp

En el elemento raíz <html>:

AtributoObligatorioValores
data-composition-variablesNoArreglo JSON de variables declaradas (id/type/label/default) — impulsa la UI del editor de Studio y proporciona valores predeterminados para getVariables()

Estructura de la composición

Las sub-composiciones cargadas a través de data-composition-src usan un envoltorio <template>. Las composiciones independientes (el index.html principal) NO usan <template> — colocan el div data-composition-id directamente en <body>. Usar <template> en un archivo independiente oculta todo el contenido del navegador y rompe la representación.

Estructura de sub-composición:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- contenido -->
    <style>
      [data-composition-id="my-comp"] {
        /* estilos con alcance */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // interpolaciones...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

Cargar en la raíz: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

Variables (Composiciones parametrizadas)

Renderiza la misma composición con contenido diferente — título, color del tema, precios, subtítulos — sin editar el HTML fuente.

Patrón de tres pasos:

  1. Declara variables en la raíz <html> de la composición con data-composition-variables. Cada entrada necesita id, type (uno de string, number, color, boolean, enum), label y default. Las entradas Enum también necesitan options: [{value, label}, ...].
  2. Lee los valores resueltos dentro del script de la composición con window.__hyperframes.getVariables(). Devuelve el resultado fusionado de los valores predeterminados declarados + anulaciones por instancia + anulaciones de CLI.
  3. Anula en tiempo de renderizado con npx hyperframes render --variables '{...}' (nivel superior) o con data-variable-values='{...}' en el elemento anfitrión (por instancia para sub-comps).
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Título","default":"Hola"},
  {"id":"theme","type":"enum","label":"Tema","default":"light","options":[
    {"value":"light","label":"Claro"},
    {"value":"dark","label":"Oscuro"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>
# Vista previa de desarrollo usa los valores predeterminados declarados
npx hyperframes preview

# Renderizar con anulaciones
npx hyperframes render --variables '{"title":"Informe Q4","theme":"dark"}' --output q4.mp4

# O desde un archivo JSON
npx hyperframes render --variables-file ./vars.json

Valores por instancia de sub-composición: el mismo getVariables() funciona dentro de sub-comps cargadas a través de data-composition-src. Cada elemento anfitrión pasa sus propios valores:

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Empresa","price":"$99"}'
></div>

Cuándo crear composiciones separadas

Una composición mantiene un tamaño único (1920x1080 o 1080x1920). Diferentes tamaños requieren diferentes composiciones. Nunca cambies el tamaño dinámicamente con CSS.

Las composiciones también se separan por intención visual — una escena introductoria, un logotipo animado reutilizable, un diseño de tabla de precios. Un archivo por composición.

EscenarioEnfoque
Múltiples escenas, mismo tamaño, flujo unificadoUna composición, múltiples clips .scene con línea de tiempo GSAP
Secciones de diferente tamañoUna composición raíz por tamaño, cargada con data-composition-src
Elemento reutilizable (logotipo, tarjeta)Sub-composición independiente cargada con data-composition-src

Cómo las composiciones interactúan con las líneas de tiempo

Las composiciones son dueñas de su línea de tiempo. Una composición contiene exactamente una línea de tiempo GSAP que controla todos los clips de .scene dentro de ella. Cuando los clips son sub-composiciones (cargadas con data-composition-src), la línea de tiempo de la sub-composición no se fusiona automáticamente con la línea de tiempo principal. El marco HyperFrames maneja la sincronización:

  • La reproducción en la línea de tiempo principal busca la línea de tiempo de la sub-composición en window.__timelines, la coloca en paused y avanza su progress() basado en el tiempo global.
  • Cada línea de tiempo de sub-composición debe usar paused: true en su construcción y registrarse en window.__timelines.

Referencias

  • Principios de movimiento — reglas GSAP de carga, curvas de facilidad, temporización, composiciones de sub-animación
  • Composición de video — reglas de diseño, restricciones de tamaño, manejo de medios
  • Selector de diseño — flujo de trabajo visual para elegir combinación de colores/estado de ánimo/fuente
  • Expansión de la indicación — proceso de solicitud estructurada que produce un bloque de entrada consistente para agentes posteriores
  • Dirección del ritmo — plantillas de ritmo (golpe rápido, sostenido, construcciones de 3 actos, alto de batería)

Skills relacionados