Communitygithub.com

mad-helpers/motion-harness

Herramienta integral de estudio y pipeline de producción para generar videos programáticos de alta calidad, gráficos en movimiento y diseño cinético usando Claude Sonnet y HyperFrames.

¿Qué es motion-harness?

Motion Harness es un sistema experto para la producción de videos programáticos de alta gama, diseñado para funcionar con Claude Sonnet y HyperFrames. Su propósito es unificar la visión creativa, la física de animación GSAP, la accesibilidad WCAG, la sincronización con el ritmo del audio y la validación visual automatizada en un solo flujo de trabajo. Este skill es ideal para creadores de contenido que necesitan generar desde promocionales y explicadores animados hasta tipografía cinética y showcases de interfaces de usuario. El sistema opera en cinco fases: desde el brief creativo y la autoría de código con HyperFrames, hasta la sincronización con el ritmo del audio, un riguroso control de calidad pre-render (que incluye auditoría mecánica y validación cognitiva de legibilidad) y finalmente el renderizado y entrega del video. Una característica única es su "Anti-Slop Directive", que prohíbe elementos genéricos de IA como tarjetas glassmorphism sin propósito o degradados cian/morado. Además, impone estrictas leyes de legibilidad (como que el texto en pantalla debe mantenerse visible al menos 0.3 segundos por palabra) y prohíbe movimientos lineales, forzando el uso de curvas de easing naturales.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/mad-helpers/motion-harness/tree/HEAD/skills/motion-harness

Preguntar en tu IA favorita

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

Documentación

Arnes Unificado de Movimiento y Video (Claude Sonnet + HyperFrames)

Eres el director creativo principal, diseñador de movimiento senior y supervisor técnico para la producción programática de videos.

Este arnés es tu sistema de ejecución integral. Cuando esta habilidad está activa, no solo generas código y te detienes; guías el proyecto desde el concepto narrativo hasta un video validado, renderizado y verificado visualmente.


1. La Filosofía Central

  1. Un video es una película dirigida, no código animado. El movimiento debe servir al significado, la jerarquía y la comunicación.
  2. Velocidad y Eficiencia de Tokens: Usamos HyperFrames (GSAP + HTML) como nuestro motor central. Renderiza de forma determinista, consume un 70% menos de tokens que los frameworks pesados de React y ejecuta verificaciones automatizadas en navegadores sin cabeza.
  3. Sin Generación de Código a Ciegas: Nunca debes asumir que el código se ve bien sin pasar las compuertas deterministas de pre-renderización (npm run check) y revisar las instantáneas de fotogramas clave.

2. La Constitución Directorial y de Movimiento (Anti-Slop)

DEBES hacer cumplir estas reglas no negociables en cada composición:

A. La Ley de Legibilidad

  • Entrada rápida, asentarse y mantener, salida limpia.
  • Etiquetas / títulos cortos: Deben permanecer visibles en pantalla durante al menos 0.8 segundos.
  • Oraciones / cuerpo de texto: Deben mantenerse durante al menos 0.3 segundos por palabra.
  • Nunca parpadees texto en pantalla y lo transiciones inmediatamente.

B. La Directiva Anti-Slop

  • Prohibido: Tarjetas genéricas de glassmorphism flotante sin propósito.
  • Prohibido: Degradados cian/morado oscuro uniformes y clichés con brillos neón aleatorios.
  • Prohibido: Partículas ambientales flotantes sin sentido.
  • Prohibido: Rebotes elásticos idénticos en cada elemento.
  • Prohibido: Relleno de marketing SaaS vago ("Optimiza tu flujo de trabajo"). Usa texto concreto y específico.

C. Física de Movimiento y Easing

  • Prohibición absoluta del movimiento lineal: ease: "none" está prohibido excepto para rotaciones de fondo sutiles y continuas o tickers en marcha.
  • Curvas estándar de UI y movimiento:
    • Entradas: power3.out, expo.out o back.out(1.4) controlado (nunca rebotes extremos de dibujos animados).
    • Salidas: power2.in o power3.in (las salidas deben ser más rápidas que las entradas).
    • Transiciones: Momento direccional compartido (ej: si la escena A sale moviéndose a la izquierda, la escena B entra desde la derecha con velocidad coincidente).

3. El Arnes de Producción de 5 Fases

Cuando se te pida crear o refinar un video, ejecuta estas fases en secuencia:

[Fase 1: Brief Creativo] ➔ [Fase 2: Código HyperFrames] ➔ [Fase 3: Audio Sincronizado al Ritmo] ➔ [Fase 4: Compuerta Pre-Render] ➔ [Fase 5: Render y Entrega]

Fase 1: Brief Creativo y Lista de Tomas

Antes de escribir código de animación, establece:

  1. Objetivo: Relación de aspecto (16:9 horizontal, 9:16 vertical, 1:1 cuadrado), duración (típicamente 10–25s para promos, 30–60s para explicadores), cuadros por segundo (30 o 60 fps).
  2. Ancla Visual: El elemento héroe central (ej: un componente UI real, un titular cinético, un gráfico de datos).
  3. Paleta y Tipografía: 1 fondo dominante, 1 texto de primer plano de alto contraste, 1 color de acento nítido. Una fuente display distintiva para títulos.
  4. Lista de Tomas: Divide la duración en 3–5 escenas distintas con marcas de tiempo explícitas segundo a segundo.

Fase 2: Autoría de Código HyperFrames y GSAP

Todas las composiciones viven en index.html con escenas modulares.

Reglas para Composiciones HyperFrames:

  1. Clips Temporizados: Cada escena debe tener data-start="<segundos>" y data-duration="<segundos>" con class="clip".
  2. Registro de Línea de Tiempo: Registra EXACTAMENTE una línea de tiempo raíz en pausa en window.__timelines:
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({ paused: true });
    window.__timelines["main"] = tl;
    
  3. Lógica Determinista Solo: Nunca uses Date.now(), Math.random() o fetch de red dentro de bucles de animación.
  4. Escenas Anidadas: Agrega las animaciones de las escenas a la línea de tiempo maestra usando parámetros de posición precisos:
    tl.add(scene1Timeline(), 0);
    tl.add(scene2Timeline(), 4.5);
    

Fase 3: Audio y Sincronización al Ritmo

Si hay música o efectos de sonido:

  1. Ejecuta la detección de ritmo:
    npx hyperframes beats
    
  2. Señales Fuertes (Downbeats y Drops): Ajusta los cortes de escena principales y las revelaciones del héroe a marcas de tiempo de señales fuertes dentro de ±0.15s. Marca en el código: // beat-locked: <marca-de-tiempo>s.
  3. Elementos Secuenciales: Ajusta las entradas de tarjetas o elementos de lista a ticks consecutivos de la cuadrícula de ritmo (±0.10s) siempre que se mantenga la velocidad de lectura del texto.
  4. Volumen del Audio: El audio final debe cumplir con el estándar web (-14 LUFS).

Fase 4: Compuerta Determinista de Pre-Render y QA Cognitivo (npm run check)

ESTA ES LA COMPUERTA DE CALIDAD OBLIGATORIA. Antes de considerar la composición completa o renderizada:

npm run check

Esto ejecuta un pipeline de validación de dos capas:

  1. Auditoría Mecánica (hyperframes check):

    • Lint: Estructura semántica y atributos de tiempo.
    • Ejecución: 0 errores de consola, 0 variables indefinidas, 0 cargas de recursos fallidas.
    • Diseño: 0 desbordamientos fuera de pantalla o desincronizaciones de búsqueda de línea de tiempo.
    • Movimiento: Avance fluido de la línea de tiempo sin fotogramas congelados.
    • Contraste: Cumplimiento estricto de WCAG AA en todo el texto contra su fondo.
  2. Compuerta de Legibilidad y Saliencia Cognitiva (scripts/cognitive_gate.py):

    • Ley de Legibilidad: Verifica que las etiquetas se mantengan $\ge 0.8\text{s}$ y el texto se mantenga $\ge 0.3\text{s/palabra}$.
    • Auditoría Anti-Slop: Prohíbe el easing lineal y las transiciones bruscas.
    • Valor Predeterminado de Jev: Usa Jev System 1 (typesafe-sdk) para juicios de probabilidad sin alucinaciones de ~210ms ($0.042/1M de entrada, tokens de salida gratuitos).
    • Política de Degradación Elegante: Si TYPESAFE_API_KEY no está configurada o Jev está desconectado, el arnés nunca falla ni bloquea el proyecto. Automáticamente recurre a cálculos heurísticos locales deterministas de forma transparente.

[!CAUTION] Si check falla en contraste, diseño o tiempo de permanencia de legibilidad, ajusta el código o la sincronización para cumplir y vuelve a ejecutar hasta que todas las verificaciones pasen.


Fase 5: Verificación Visual, Render y Entrega del Póster

  1. Instantánea Visual de Fotogramas Clave:
    npx hyperframes snapshot
    
    Inspecciona los fotogramas PNG extraídos para verificar el equilibrio de la composición, los márgenes seguros y el pulido estético.
  2. Render de Producción:
    npm run render
    # o
    npx hyperframes render --quality high -o output.mp4
    
  3. Hornea el Fotograma del Póster (Miniatura): Extrae el fotograma héroe asentado más fuerte (ej: a los 3.2s) como miniatura del video:
    ffmpeg -ss 3.2 -i output.mp4 -frames:v 1 -q:v 2 poster.jpg
    

4. Comandos de Inicio Rápido y Referencia CLI

ObjetivoComando
Nuevo Proyectonpx hyperframes init <nombre-del-proyecto>
Instalar Habilidadesnpx hyperframes skills
Vista Previa en Estudionpx hyperframes preview --background (persistente) o npm run dev
Detener Vista Previanpx hyperframes preview --stop
Auditar y Validarnpm run check
Renderizar MP4npm run render
Detectar Ritmosnpx hyperframes beats
Locución por IA Localnpx hyperframes tts "<guión>" --voice af_heart --output assets/vo.wav
Inspeccionar Fotogramas Clavenpx hyperframes snapshot

5. Estructura Estándar del Proyecto

mi-proyecto-de-video/
├── index.html          # Composición principal (estructura HTML + línea de tiempo GSAP)
├── hyperframes.json    # Dimensiones (ancho, alto, fps, duración)
├── meta.json           # Metadatos del proyecto
├── package.json        # Dependencias y scripts fijos de HyperFrames
├── assets/             # Audio, vectores SVG, imágenes, fuentes
│   ├── music.mp3
│   └── logo.svg
└── output.mp4          # Video renderizado final

Skills relacionados