Communitygithub.com

mad-helpers/motion-harness

Un completo 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. Unifica visión directorial, reglas anti-slop, física de animación GSAP, accesibilidad WCAG, sincronización de audio y QA visual automatizado.

¿Qué es motion-harness?

El skill 'mad-helpers/motion-harness' es un sistema integral para la producción de videos programáticos y animaciones de alta calidad, diseñado para plataformas como Claude Code o Cursor. Su núcleo es HyperFrames (basado en GSAP y HTML), que consume un 70% menos de tokens que frameworks pesados como React y permite ejecuciones deterministas y verificables. El proceso se divide en cinco fases: desde el brief creativo y la autoría de código con GSAP, hasta la sincronización de latidos musicales, renderizado y entrega. Incluye una puerta de calidad obligatoria ('npm run check') que verifica mecánica, contraste WCAG AA, legibilidad (tiempos de visualización de texto) y evita elementos comunes de inteligencia artificial como transiciones lineales o partículas flotantes sin propósito. También incorpora un sistema de evaluación cognitiva con Jev System 1 para juicios probabilísticos sin alucinaciones, con una política de fallback que garantiza que el proyecto nunca se bloquee si el servicio externo no está disponible.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add mad-helpers/motion-harness

Preguntar en tu IA favorita

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

Documentación

Arnés Unificado de Movimiento y Video (Claude Sonnet + HyperFrames)

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

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 el 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 principal. Renderiza de manera determinista, consume un 70% menos de tokens que los frameworks pesados de React y ejecuta verificaciones automatizadas en navegador sin cabeza.
  3. Sin Generación de Código Ciega: Nunca debes asumir que el código se ve bien sin pasar las compuertas de pre-renderizado determinista (npm run check) y revisar las instantáneas de fotogramas clave.

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

DEBES aplicar estas reglas innegociables en cada composición:

A. La Ley de Legibilidad (قانون خوانایی متن)

  • Entrada rápida, asentarse y mantener, salida limpia.
  • Etiquetas/títulos cortos: Deben mantenerse visibles en pantalla por al menos 0,8 segundos.
  • Oraciones/texto del cuerpo: Deben mantenerse por al menos 0,3 segundos por palabra.
  • Nunca muestres texto en pantalla de forma intermitente y transiciones inmediatamente.

B. La Directiva Anti-Slop (پرهیز از کلیشه‌های هوش مصنوعی)

  • Prohibido: Tarjetas genéricas de vidrio flotante sin propósito.
  • Prohibido: Degradados cliché de púrpura/cian oscuro uniforme con brillos neón aleatorios.
  • Prohibido: Partículas ambientales flotantes sin sentido.
  • Prohibido: Rebotes de resorte 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 de movimiento lineal: ease: "none" está prohibido excepto para rotaciones de fondo sutiles continuas o tickers que marcan el tiempo.
  • Curvas estándar de UI y movimiento:
    • Entradas: power3.out, expo.out, o back.out(1.4) controlado (nunca rebotes de dibujos animados extremos).
    • Salidas: power2.in o power3.in (las salidas deben ser más rápidas que las entradas).
    • Transiciones: Momento direccional compartido (por ejemplo, si la escena A sale moviéndose a la izquierda, la escena B entra desde la derecha con velocidad coincidente).

3. El Arnés de Producción de 5 Fases

Cada vez que 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 con Ritmo] ➔ [Fase 4: Compuerta de Pre-Renderizado] ➔ [Fase 5: Renderizado 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 promociones, 30–60s para explicativos), velocidad de fotogramas (30 o 60 fps).
  2. Ancla Visual: El elemento héroe central (por ejemplo, componente UI real, titular cinético, 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. Fuente de visualización distinta 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 residen 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 pausada en window.__timelines:
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({ paused: true });
    window.__timelines["main"] = tl;
    
  3. Solo Lógica Determinista: Nunca uses Date.now(), Math.random() o búsquedas de red dentro de bucles de animación.
  4. Escenas Anidadas: Agrega tweens de escena 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 de Ritmo

Si hay música o efectos de sonido presentes:

  1. Ejecuta detección de ritmo:
    npx hyperframes beats
    
  2. Señales Fuertes (Tiempos Fuertes y Drops): Ajusta los cortes principales de escena y las revelaciones del héroe a marcas de tiempo de señales fuertes dentro de ±0,15s. Marca en código: // bloqueado-ritmo: <marca_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 de Audio: El audio final debe cumplir con el estándar web (-14 LUFS).

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

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

npm run check

Esto ejecuta un pipeline de validación de doble capa:

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

    • Linting: Estructura semántica y atributos de temporización.
    • Tiempo de Ejecución: 0 errores de consola, 0 variables indefinidas, 0 cargas de activos 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 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 discordantes.
    • Predeterminado Jev: Usa Jev Sistema 1 (typesafe-sdk) para juicios de probabilidad sin alucinaciones de ~210ms ($0.042/1M entrada, tokens de salida gratuitos).
    • Política de Degradación Elegante: Si TYPESAFE_API_KEY no está configurada o Jev está fuera de línea, el arnés nunca falla ni bloquea el proyecto. Automáticamente recurre a cálculos heurísticos locales deterministas sin problemas.

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


Fase 5: Verificación Visual, Renderizado 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 la pulcritud estética.
  2. Renderizado de Producción:
    npm run render
    # o
    npx hyperframes render --quality high -o output.mp4
    
  3. Hornear Fotograma de Póster (Miniatura): Extrae el fotograma héroe asentado más fuerte (por ejemplo, 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-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 IA Localnpx hyperframes tts "<guion>" --voice af_heart --output assets/vo.wav
Inspeccionar Fotogramas Clavenpx hyperframes snapshot

5. Estructura Estándar del Proyecto

mi-proyecto-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

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados