Communitygithub.com

scott-fryxell/brayness

Crear composiciones de video, animaciones, tarjetas de título, superposiciones, subtítulos, voces en off, visuales reactivas al audio y transiciones de escena en HyperFrames HTML. Úsalo para cualquier trabajo de video basado en HTML: crear composiciones, sincronizar subtítulos con audio, generar narración TTS, ejecutar el ciclo de desarrollo (init, lint, inspect, preview, render), preprocesar activos (tts, transcribir, quitar fondo) o instalar/contribuir bloques del registro.

¿Qué es brayness?

Brayness es una habilidad especializada para trabajar con el framework HyperFrames, que utiliza HTML como fuente de verdad para la creación de video. Convierte cualquier solicitud de video en composiciones HTML con atributos `data-*` para temporización, animaciones con GSAP y estilos CSS. El flujo de trabajo es estricto y paso a paso: primero define un sistema de diseño (usando un archivo `design.md` existente, eligiendo un estilo visual predefinido, o seleccionando colores/fuentes de la casa), luego expande el prompt para alinear la intención del usuario con el sistema de diseño, y finalmente planifica la narrativa, estructura, ritmo y temporización antes de escribir cualquier HTML. Un principio fundamental es "layout antes de animación": se construye primero el estado final estático de cada escena, y luego se anima desde fuera de la pantalla hacia esa posición, evitando adivinar la posición final. La habilidad impone reglas no negociables como: temporización determinista (sin `Math.random()`), solo animar propiedades visuales con GSAP, nunca usar bucles infinitos (`repeat: -1`), y construir timelines de forma síncrona. Para composiciones de múltiples escenas, requiere el uso obligatorio de transiciones entre cada escena, animar cada elemento al entrar, y solo usar animaciones de salida en la última escena. Incluye un checklist de calidad con comandos como `npx hyperframes lint` y `npx hyperframes inspect`. Está diseñada para agentes de IA como Claude Code, Cursor o Codex que trabajen con el ecosistema HyperFrames, proporcionando referencias detalladas para autoría, composición de video, tipografía, principios de movimiento, transiciones, y más. La habilidad también cubre la edición de composiciones existentes (leyendo los archivos reales, no adivinando) y el manejo de activos de medios como TTS, transcripción y eliminación de fondos.

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

API de atributos, estructura de composición/plantilla, variables y reglas de medios: references/authoring.md. Léelo antes de escribir tu primera composición HTML en una sesión.

Enfoque

Descubrimiento (solo para solicitudes exploratorias)

Para solicitudes abiertas ("hazme un video de lanzamiento de producto") donde el usuario no se ha comprometido con una dirección, entiende la intención antes de elegir colores: audiencia, plataforma, prioridad (calidad del movimiento vs precisión vs velocidad), y si quieren variaciones. Si hay variaciones, ofrece 2-3 que difieran en ritmo o estructura - una segura, una ambiciosa - no intercambios de color.

Para solicitudes específicas ("añade una tarjeta de título", "arregla la temporización de la escena 3"), omite el descubrimiento.

Paso 1: Sistema de diseño

Si existe design.md o DESIGN.md, léelo primero (ambas mayúsculas/minúsculas - son archivos diferentes en Linux). Es la fuente de verdad para colores de marca, fuentes y restricciones - usa sus valores exactos. Si nombra fuentes sin archivos .woff2 en fonts/ y sin coincidencia incorporada, advierte al usuario antes de escribir HTML.

Si no existe design.md, ofrece una opción:

  1. ¿El usuario nombró un estilo o estado de ánimo? Lee visual-styles.md (8 ajustes preestablecidos con nombre), elige el más cercano.
  2. ¿Navegar visualmente? Ejecuta el selector de diseño - references/design-picker.md.
  3. ¿Ir rápido? Pregunta estado de ánimo, claro/oscuro, colores/fuentes de marca; elige una paleta de house-style.md.

design.md define la marca, no las reglas de composición de video. Esas vienen de references/video-composition.md y house-style.md. Colores de marca a escala de video, no opacidad de interfaz web.

Paso 2: Expansión del prompt

Ejecutar en cada composición excepto piezas de una sola escena y ediciones triviales - fundamenta la intención contra design.md/house-style.md en un intermedio consistente. Proceso y formato: references/prompt-expansion.md.

Paso 3: Planificar

  1. Qué - arco narrativo, momentos clave, latidos emocionales.
  2. Estructura - cuántas composiciones, sub-comps vs en línea, qué pistas llevan qué.
  3. Ritmo - declara el ritmo de la escena antes de implementar (rápido-rápido-LENTO-rápido-SHADER-pausa). Plantillas: references/beat-direction.md.
  4. Temporización - qué clips impulsan la duración, dónde caen las transiciones.
  5. Diseño - construye primero el estado final (siguiente sección).
  6. Animar - luego añade movimiento.

Construye lo que se pidió. "Una tarjeta de título" no es "una tarjeta de título + 3 escenas de apoyo + música + subtítulos." Propón extras; no los añadas.

Para ediciones pequeñas, 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 - completamente entrado, colocado correctamente, sin haber salido aún. Escríbelo como HTML+CSS estático primero. Sin GSAP todavía.

Por qué: si posicionas los elementos en su estado de inicio animado (fuera de pantalla, opacidad 0) y haces una interpolación hacia donde crees que aterrizan, estás adivinando el diseño final, y las superposiciones permanecen invisibles hasta el render. Construye el estado final primero y los errores de diseño son visibles antes de que exista el movimiento.

  1. Identifica el fotograma héroe por escena - el momento en que la mayoría de los elementos están simultáneamente visibles. Construye ese diseño.
  2. Escribe CSS estático para él. .scene-content DEBE llenar la escena: width: 100%; height: 100%; padding: Npx; con display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. El padding empuja el contenido hacia adentro - NUNCA uses position: absolute; top: Npx en un contenedor de contenido (se desborda cuando el contenido crece). Reserva el posicionamiento absoluto para elementos decorativos.
  3. Entradas con gsap.from() - anima DESDE fuera de pantalla HASTA la posición CSS. CSS es la verdad fundamental; la interpolación es el viaje. (Sub-comps cargadas vía data-composition-src: prefiere gsap.fromTo() - consulta references/motion-principles.md.)
  4. Solo la última escena: salidas con gsap.to(). Todas las demás escenas terminan completamente visibles - la transición ES la salida (regla de transición 3 a continuación).

Si el elemento A sale antes de que el elemento B entre en la misma área, da a ambos posiciones CSS correctas para sus propios fotogramas héroes - la línea de tiempo evita que coexistan, y el paso de diseño detecta la superposición accidental de errores de temporización. La superposición intencional (brillo detrás del texto, pilas de tarjetas) está bien; el paso existe para detectar superposición no intencional - dos titulares chocando, una estadística cubriendo una etiqueta, contenido fuera del fotograma.

Contrato de Línea de Tiempo

  • Todas las líneas de tiempo comienzan { paused: true } - el reproductor controla la reproducción
  • Registra cada línea de tiempo: window.__timelines["<id-de-composición>"] = tl
  • El framework anida automáticamente las sub-líneas de tiempo - NO las añadas manualmente
  • La duración proviene de data-duration, no de la longitud de la línea de tiempo GSAP
  • Nunca crees interpolaciones vacías para establecer la duración

Reglas (No Negociables)

Determinista: sin Math.random(), Date.now(), o lógica basada en tiempo. PRNG con semilla (ej. mulberry32) para pseudoaleatoriedad.

GSAP: solo anima propiedades visuales (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transformaciones). Nunca animes visibility o display; nunca llames a video.play()/audio.play().

Conflictos de animación: nunca animes la misma propiedad en el mismo elemento desde múltiples líneas de tiempo simultáneamente.

Sin repeat: -1: las repeticiones infinitas rompen el motor de captura. Calcula repeat: Math.ceil(duracion / duracionCiclo) - 1.

Construcción síncrona de líneas de tiempo: nunca construyas líneas de tiempo dentro de async/await, setTimeout, o Promesas - el motor de captura lee window.__timelines síncronamente después de la carga. Las fuentes están incrustadas por el compilador; no esperes a la carga de fuentes.

Nunca hagas:

  1. Olvidar el registro de window.__timelines
  2. Usar video para audio - siempre video silenciado + <audio> separado
  3. Anidar video dentro de un div temporizado - usa un contenedor no temporizado
  4. Usar data-layer (usa data-track-index) o data-end (usa data-duration)
  5. Animar dimensiones del elemento de video - anima un div contenedor
  6. Llamar a play/pause/seek en los medios - el framework posee la reproducción
  7. Crear un contenedor de nivel superior sin data-composition-id
  8. Usar repeat: -1 en cualquier línea de tiempo o interpolación
  9. Construir líneas de tiempo asíncronamente
  10. Usar gsap.set() en elementos de clip de escenas posteriores - no existen en el DOM en la carga de la página. Usa tl.set(selector, vars, timePosition) en o después del data-start del clip.
  11. Usar <br> en el texto del contenido - se apila con el ajuste natural y causa superposición; usa max-width en su lugar. Excepción: títulos de visualización cortos deliberadamente una palabra por línea.

Transiciones de Escena (No Negociables)

Toda composición de múltiples escenas DEBE seguir las cuatro. Violar cualquiera es una composición rota.

  1. SIEMPRE usa transiciones entre escenas. Sin cortes bruscos.
  2. SIEMPRE anima CADA elemento ENTRANDO vía gsap.from(). Nada aparece completamente formado. Cinco elementos significan cinco interpolaciones de entrada.
  3. NUNCA uses animaciones de salida excepto en la última escena. Sin gsap.to() desvaneciendo opacidad, moviendo fuera de pantalla, o escalando a 0 antes de una transición - la transición ES la salida, y la escena saliente debe estar completamente visible cuando se active. Una interpolación de salida antes de una transición entrega a la transición un fotograma vacío.
  4. Solo la última escena puede desvanecer elementos.

Selección e implementación de transiciones: references/transitions.md.

Barreras de Protección de Animación

  • Desplaza la primera animación 0.1-0.3s (no t=0)
  • Varía las curvas de suavizado - al menos 3 curvas diferentes por escena, sin patrón de entrada repetido dentro de una escena
  • Evita gradientes lineales de pantalla completa sobre fondos oscuros (bandas H.264) - radial o sólido + brillo localizado
  • Titulares de 60px+, cuerpo de 20px+, etiquetas de datos de 16px+
  • font-variant-numeric: tabular-nums en columnas de números

Editar Composiciones Existentes

  • Lee los archivos reales, no adivines. La composición ES la especificación - extrae códigos hex exactos, fuentes y patrones de suavizado de la fuente, no de la memoria.
  • Solo cambia lo que se solicitó; conserva la temporización de clips no relacionados.

Lista de Verificación de Salida

Rápido (ejecutar inmediatamente, bloquear en resultados):

  • npx hyperframes lint y npx hyperframes validate pasan ambos
  • Adherencia al diseño verificada si existe design.md

Lento (ejecutar en paralelo mientras se presenta la vista previa):

  • npx hyperframes inspect pasa, o cada desbordamiento reportado está marcado intencionalmente
  • Advertencias de contraste abordadas
  • Coreografía de animación verificada (script de mapa de animación)

Cómo ejecutar y corregir cada verificación: references/quality-checks.md.

Índice de Referencias

Leer siempre para cualquier composición nueva:

ArchivoCubre
references/authoring.mdatributos data, estructura de plantilla, variables, video/audio, fuentes/activos
references/video-composition.mdreglas de medio de video - estas anulan los instintos web
references/typography.mdemparejamiento de fuentes, OpenType, ajustes de fondo oscuro
references/motion-principles.mddiseño de movimiento, movimiento de imagen, reglas GSAP de soporte de carga

Leer siempre también para composiciones de múltiples escenas:

ArchivoCubre
references/beat-direction.mdplantillas de ritmo, verbos de coreografía, capas de profundidad
references/transitions.mdselección de transiciones; catálogo enruta a implementaciones; las transiciones de shader viven en el paquete npm @hyperframes/shader-transitions (lee su fuente en node_modules)

Leer cuando la tarea lo requiera:

ArchivoLeer cuando
references/quality-checks.mdejecutando verificaciones de inspect/contraste/diseño/mapa de animación
references/cli.mdcualquier comando CLI; solución de problemas de compilación/renderizado
references/captions.mdcualquier texto sincronizado con la temporización de audio
references/transcript-guide.mdmanejo de transcripciones del lado de los subtítulos (la invocación CLI vive en media.md)
references/dynamic-techniques.mdanimación de subtítulos dinámicos (karaoke, slam, dispersión)
references/audio-reactive.mdvisuales que responden a música/voz
references/css-patterns.mdresaltado de marcadores (resaltado, círculo, explosión, garabato)
references/techniques.mdtécnicas de planificación por compás (11 patrones con código)
references/narration.mdritmo de voz en off/TTS y estructura del guión
references/media.mdTTS (Kokoro), transcripción (Whisper), eliminación de fondo
references/prompt-expansion.mdPaso 2 del enfoque
references/design-picker.mdcrear un design.md visualmente
references/from-website.mdconvertir un sitio web en un video
references/registry.mdinstalar/contribuir bloques del registro (hyperframes add)
visual-styles.mdel usuario nombra un estilo; generar design.md
house-style.mdvalores predeterminados estéticos cuando no hay design.md
patterns.mdPiP, tarjetas de título, presentaciones de diapositivas
data-in-motion.mddatos, estadísticas, infografías

Adaptadores de tiempo de ejecución (leer cuando la composición use ese tiempo de ejecución en lugar de GSAP): waapi, lottie, three, animejs, css-animations, typegpu.

Skills relacionados