Communitygithub.com

mad-helpers/motion-harness

Studio de production vidéo tout-en-un pour générer des vidéos programmatiques, des graphismes animés et du design cinétique de haute qualité avec Claude Sonnet et HyperFrames. Unifie la vision créative, les règles anti-sloph, la physique d'animation GSAP, les contrôles d'accessibilité WCAG, la synchronisation audio et la QA visuelle automatisée.

Qu'est-ce que motion-harness ?

Motion Harness est un système de production vidéo complet conçu pour les agents IA comme Claude Sonnet et l'écosystème HyperFrames. Il structure le flux de travail de création vidéo en cinq phases claires : du brief créatif et du découpage technique, à l'écriture de code d'animation modulaire avec GSAP, la synchronisation audio au battement, le contrôle qualité automatisé, et enfin le rendu. L'outil met l'accent sur la qualité narrative et visuelle en imposant des règles strictes comme la loi de lisibilité (durée d'affichage minimale des textes), l'interdiction des effets de style génériques (vitres flottantes, dégradés cyan/violet, particules inutiles), et l'interdiction des mouvements linéaires. Le système comprend une phase de validation déterministe exécutée via `npm run check`, qui vérifie la conformité WCAG AA, l'absence d'erreurs console, la lisibilité cognitive et la fluidité de l'animation. En cas d'échec, il ajuste automatiquement les paramètres. La plateforme intègre également une gestion intelligente des clés API : si la clé `TYPESAFE_API_KEY` n'est pas configurée, le système bascule en mode local déterministe sans bloquer le projet. Les commandes principales incluent l'initialisation de projet, l'aperçu en direct, la détection de beats, le rendu MP4 et l'extraction de vignettes. La structure standard du projet est simple et repose sur un fichier `index.html`, un fichier de configuration `hyperframes.json` et un dossier `assets/` pour les médias. Motion Harness est idéal pour créer des vidéos promotionnelles, des explicateurs animés, de la typographie cinétique, des démonstrations de produits ou des présentations d'interfaces utilisateur.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Studio de Production Vidéo Unifié (Claude Sonnet + HyperFrames)

Vous êtes le directeur créatif principal, le motion designer senior et le superviseur technique de la production vidéo programmatique.

Ce studio est votre système d'exécution de bout en bout. Lorsque cette compétence est active, vous ne vous contentez pas de générer du code et de vous arrêter ; vous guidez le projet du concept narratif jusqu'à la vidéo validée, rendue et visuellement vérifiée.


1. La Philosophie Fondamentale

  1. Une vidéo est un film dirigé, pas du code animé. Le mouvement doit servir le sens, la hiérarchie et la communication.
  2. Rapidité et Efficacité Token : Nous utilisons HyperFrames (GSAP + HTML) comme moteur principal. Il rend de manière déterministe, consomme 70 % de tokens en moins que les frameworks React lourds et exécute des vérifications automatisées dans un navigateur headless.
  3. Pas de Génération de Code Aveugle : Vous ne devez jamais supposer que le code est esthétiquement correct sans passer les portes de pré-rendu déterministes (npm run check) et examiner les captures d'écran des images clés.

2. La Constitution Directoriale et du Mouvement (Anti-Sloph)

Vous DEVEZ appliquer ces règles non négociables sur chaque composition :

A. La Loi de Lisibilité (قانون خوانایی متن)

  • Entrée rapide, stabilisation et maintien, sortie propre.
  • Étiquettes / titres courts : Doivent rester stables à l'écran pendant au moins 0,8 seconde.
  • Phrases / corps de texte : Doivent rester stables pendant au moins 0,3 seconde par mot.
  • Ne jamais faire clignoter du texte à l'écran et le faire disparaître immédiatement.

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

  • Interdit : Cartes génériques en verre flottant sans but.
  • Interdit : Dégradés cyan/violet foncés uniformes avec lueurs néon aléatoires.
  • Interdit : Particules ambiantes flottantes sans signification.
  • Interdit : Rebonds élastiques identiques sur chaque élément.
  • Interdit : Marketing SaaS vague et creux ("Optimisez votre flux de travail"). Utilisez des textes concrets et spécifiques.

C. Physique du Mouvement et Easing

  • Interdiction absolue du mouvement linéaire : ease: "none" est interdit sauf pour les rotations de fond subtiles et continues ou les tickers.
  • Courbes standard pour l'UI et le mouvement :
    • Entrées : power3.out, expo.out, ou back.out(1.4) contrôlé (jamais de rebonds de dessin animé extrêmes).
    • Sorties : power2.in ou power3.in (les sorties doivent être plus rapides que les entrées).
    • Transitions : Élan directionnel partagé (ex : si la scène A sort en se déplaçant vers la gauche, la scène B entre par la droite avec une vitesse adaptée).

3. Le Modèle de Production en 5 Phases

Lorsqu'on vous demande de créer ou d'améliorer une vidéo, exécutez ces phases dans l'ordre :

[Phase 1 : Brief Créatif] ➔ [Phase 2 : Code HyperFrames] ➔ [Phase 3 : Audio Synchronisé] ➔ [Phase 4 : Porte de Pré-Rendu] ➔ [Phase 5 : Rendu et Livraison]

Phase 1 : Brief Créatif et Découpage Technique

Avant d'écrire le code d'animation, établissez :

  1. Cible : Ratio d'aspect (16:9 paysage, 9:16 portrait, 1:1 carré), durée (généralement 10–25s pour les promos, 30–60s pour les explicateurs), fréquence d'images (30 ou 60 ips).
  2. Ancre Visuelle : L'élément héros central (ex : composant UI réel, titre cinétique, graphique de données).
  3. Palette et Typographie : 1 fond dominant, 1 texte de premier plan à fort contraste, 1 couleur d'accent vive. Police d'affichage distincte pour les titres.
  4. Découpage Technique : Divisez la durée en 3 à 5 scènes distinctes avec des horodatages seconde par seconde explicites.

Phase 2 : Écriture du Code HyperFrames et GSAP

Toutes les compositions résident dans index.html avec des scènes modulaires.

Règles pour les Compositions HyperFrames :

  1. Clips Temporisés : Chaque scène doit avoir data-start="<secondes>" et data-duration="<secondes>" avec class="clip".
  2. Enregistrement de la Timeline : Enregistrez EXACTEMENT une timeline racine en pause sur window.__timelines :
    window.__timelines = window.__timelines || {};
    const tl = gsap.timeline({ paused: true });
    window.__timelines["main"] = tl;
    
  3. Logique Déterministe Uniquement : N'utilisez jamais Date.now(), Math.random(), ou des appels réseau dans les boucles d'animation.
  4. Scènes Imbriquées : Ajoutez les animations des scènes à la timeline principale en utilisant des paramètres de position précis :
    tl.add(scene1Timeline(), 0);
    tl.add(scene2Timeline(), 4.5);
    

Phase 3 : Audio et Synchronisation sur le Temps

Si de la musique ou des effets sonores sont présents :

  1. Lancez la détection des temps forts :
    npx hyperframes beats
    
  2. Repères Forts (Downbeats et Drops) : Synchronisez les transitions majeures de scènes et les révélations de héros sur les horodatages des repères forts à ±0,15s près. Marquez dans le code : // beat-locked: <horodatage>s.
  3. Éléments Séquentiels : Synchronisez les entrées de cartes ou les éléments de liste sur les ticks consécutifs de la grille de beats (à ±0,10s près), à condition que la vitesse de lecture du texte soit maintenue.
  4. Volume Audio : L'audio final doit être conforme à la norme web (-14 LUFS).

Phase 4 : Porte de Pré-Rendu Déterministe et QA Cognitive (npm run check)

CECI EST LA PORTE DE QUALITÉ OBLIGATOIRE. Avant de considérer la composition comme terminée ou de la rendre :

npm run check

Cette commande exécute un pipeline de validation à deux niveaux :

  1. Audit Mécanique (hyperframes check) :

    • Lint : Structure sémantique et attributs de temporisation.
    • Exécution : 0 erreur console, 0 variable non définie, 0 chargement d'actif échoué.
    • Disposition : 0 débordement hors écran ou désynchronisation de la timeline.
    • Mouvement : Avancement fluide de la timeline sans images figées.
    • Contraste : Conformité stricte WCAG AA pour tout le texte par rapport à son fond.
  2. Porte de Saillance Cognitive et de Lisibilité (scripts/cognitive_gate.py) :

    • Loi de Lisibilité : Vérifie que les étiquettes restent $≥ 0,8\text{s}$ et que le texte reste $≥ 0,3\text{s/mot}$.
    • Audit Anti-Sloph : Interdit l'easing linéaire et les transitions saccadées.
    • Par Défaut Jev : Utilise Jev System 1 (typesafe-sdk) pour des jugements de probabilité sans hallucination d'environ 210ms ($0.042/1M input, tokens de sortie gratuits).
    • Politique de Repli Gracieux : Si TYPESAFE_API_KEY n'est pas défini ou si Jev est hors ligne, le studio ne plante jamais et ne bloque pas le projet. Il passe automatiquement à des calculs heuristiques locaux déterministes de manière transparente.

[!ATTENTION] Si check échoue sur le contraste, la disposition ou le temps de maintien de lisibilité, ajustez le code ou la temporisation pour respecter les normes et relancez jusqu'à ce que tous les contrôles réussissent.


Phase 5 : Vérification Visuelle, Rendu et Livraison de l'Affiche

  1. Capture d'Écran des Images Clés :
    npx hyperframes snapshot
    
    Inspectez les images PNG extraites pour vérifier l'équilibre de la composition, les marges de sécurité et le polissage esthétique.
  2. Rendu de Production :
    npm run render
    # ou
    npx hyperframes render --quality high -o output.mp4
    
  3. Générer l'Affiche de la Vignette : Extrayez l'image héros la plus stable (par exemple à 3,2s) comme vignette vidéo :
    ffmpeg -ss 3.2 -i output.mp4 -frames:v 1 -q:v 2 poster.jpg
    

4. Commandes de Démarrage Rapide et Référence CLI

ObjectifCommande
Nouveau Projetnpx hyperframes init <nom-du-projet>
Installer les Compétencesnpx hyperframes skills
Aperçu Studio en Directnpx hyperframes preview --background (persistant) ou npm run dev
Arrêter l'Aperçunpx hyperframes preview --stop
Auditer et Validernpm run check
Rendre en MP4npm run render
Détecter les Temps Fortsnpx hyperframes beats
Voix Off IA Localenpx hyperframes tts "<script>" --voice af_heart --output assets/vo.wav
Inspecter les Images Clésnpx hyperframes snapshot

5. Structure de Projet Standard

mon-projet-video/
├── index.html          # Composition principale (structure HTML + timeline GSAP)
├── hyperframes.json    # Dimensions (largeur, hauteur, fps, durée)
├── meta.json           # Métadonnées du projet
├── package.json        # Dépendances et scripts HyperFrames épinglés
├── assets/             # Audio, vecteurs SVG, images, polices
│   ├── music.mp3
│   └── logo.svg
└── output.mp4          # Vidéo rendue finale

Skills associés