Communitygithub.com

saigram0424/MindForge

Créez des compositions vidéo basées sur HTML, des cartes-titres animées, des superpositions sociales, des vidéos de tête parlante sous-titrées, des visuels réactifs à l'audio et des transitions shader en utilisant HyperFrames. HTML est la source de vérité pour la vidéo. Utilisez-le lorsque l'utilisateur souhaite un MP4/WebM rendu à partir d'une composition HTML, animer du texte/des logos/des graphiques sur des médias, avoir des légendes synchronisées avec l'audio, une narration TTS, ou convertir un site web en vidéo.

Qu'est-ce que MindForge ?

MindForge est une compétence pour agents IA qui exploite le framework HyperFrames, où HTML est la source de vérité pour la vidéo. Elle permet de créer des compositions vidéo complexes en écrivant des fichiers HTML enrichis d'attributs `data-*` pour le minutage et des animations GSAP. Le moteur capture la page image par image via un navigateur headless (Chrome ou Puppeteer) et encode le résultat en MP4 ou WebM avec FFmpeg. La compétence impose un workflow rigoureux en plusieurs étapes : d'abord la planification narrative et l'identité visuelle (via un fichier DESIGN.md), puis le scaffolding avec `npx hyperframes init`, l'écriture du layout statique (hero frame), l'ajout des animations GSAP, l'intégration des transitions entre scènes (shader ou CSS), et enfin la gestion audio/TTS, des légendes synchronisées et des visuels réactifs à l'audio. Elle inclut des vérifications obligatoires (lint, validation WCAG, inspection visuelle) avant le rendu final. MindForge est complémentaire de `manim-video` (pour les animations mathématiques/géométriques) et cible les graphiques animés, les vidéos de tête parlante, les visites de produits, les superpositions sociales et les transitions créatives. Elle fonctionne comme une compétence autonome installable via un script shell, nécessite Node.js >=22 et FFmpeg, et s'utilise en ligne de commande avec des outils de débogage comme `hyperframes doctor` et `hyperframes inspect`. L'agent doit suivre strictement les règles de non-répétition infinie, de timeline synchrone et de respect de l'identité visuelle.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sairam0424/MindForge/tree/HEAD/.agent/skills/hyperframes

Demander à votre IA préférée

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

Documentation

HyperFrames

HTML est la source de vérité pour la vidéo. Une composition est un fichier HTML avec des attributs data-* pour le minutage, une timeline GSAP pour l'animation, et du CSS pour l'apparence. Le moteur HyperFrames capture la page image par image et encode en MP4/WebM avec FFmpeg.

Complément à manim-video : Utilisez manim-video pour les explications mathématiques/géométriques (équations, style 3B1B). Utilisez hyperframes pour les graphiques animés, la tête parlante avec légendes, les visites de produits, les superpositions sociales, les transitions shader, et tout ce qui est piloté par des médias vidéo/audio réels.

Quand l'utiliser

  • L'utilisateur demande une vidéo rendue à partir d'un texte, d'un script ou d'un site web
  • Cartes-titres animées, tiers inférieurs ou intros typographiques
  • Vidéo de narration sous-titrée (TTS + légendes synchronisées sur la forme d'onde)
  • Visuels réactifs à l'audio (synchronisation au rythme, barres de spectre, lueur pulsante)
  • Transitions de scène à scène (fondu, volet, warp shader, flash-through-white)
  • Superpositions sociales (style Instagram/TikTok/YouTube)
  • Pipeline site-web-vers-vidéo (capturer une URL, produire une promotion)
  • Toute animation HTML/CSS/JS qui doit être rendue de manière déterministe en fichier vidéo

N'utilisez pas cette compétence pour :

  • Animation purement mathématique/équation (→ manim-video)
  • Génération d'images ou mèmes (→ meme-generation, modèles d'images)
  • Visioconférence ou diffusion en direct

Référence rapide

npx hyperframes init my-video               # créer un projet
cd my-video
npx hyperframes lint                        # valider avant prévisualisation/rendu
npx hyperframes preview                     # prévisualisation navigateur avec rechargement à chaud (port 3002)
npx hyperframes render --output final.mp4   # rendu en MP4
npx hyperframes doctor                      # diagnostiquer les problèmes d'environnement

Drapeaux de rendu : --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproductible) · --strict.

Référence complète de la CLI : references/cli.md.

Configuration (unique)

bash "$(dirname "$(find ~/.agent/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

Le script :

  1. Vérifie que Node.js >= 22 et FFmpeg sont installés (affiche les instructions de correction si ce n'est pas le cas).
  2. Installe la CLI hyperframes globalement (npm install -g hyperframes@>=0.4.2).
  3. Pré-met en cache chrome-headless-shell via Puppeteer — requis pour un rendu de meilleure qualité via le chemin de capture HeadlessExperimental.beginFrame de Chrome.
  4. Exécute npx hyperframes doctor et rapporte le résultat.

Voir references/troubleshooting.md si la configuration échoue.

Procédure

1. Planifier avant d'écrire le HTML

Avant de toucher au code, articulez à un haut niveau :

  • Quoi — arc narratif, moments clés, battements émotionnels
  • Structure — compositions, pistes (vidéo/audio/superpositions), durées
  • Identité visuelle — couleurs, polices, caractère du mouvement (explosif / cinématique / fluide / technique)
  • Hero frame — pour chaque scène, le moment où le plus d'éléments sont simultanément visibles. C'est la mise en page statique que vous allez construire en premier.

Porte d'identité visuelle (HARD-GATE). Avant d'écrire UNE composition HTML, une identité visuelle doit être définie. N'écrivez PAS de compositions avec des couleurs par défaut ou génériques (#333, #3b82f6, Roboto sont des signes que cette étape a été sautée). Vérifiez dans l'ordre :

  1. DESIGN.md à la racine du projet ? → Utilisez ses couleurs, polices, règles de mouvement et contraintes « Ce qu'il ne faut PAS faire » exactes.

  2. L'utilisateur a nommé un style (par exemple « Swiss Pulse », « dark and techy », « marque de luxe ») ? → Générez un DESIGN.md minimal avec ## Style Prompt, ## Colors (3-5 hex avec rôles), ## Typography (1-2 familles), ## What NOT to Do (3-5 anti-patrons).

  3. Rien de ce qui précède ? → Posez 3 questions avant d'écrire le HTML :

    • Ambiance ? (explosif / cinématique / fluide / technique / chaotique / chaleureux)
    • Toile claire ou sombre ?
    • Des couleurs de marque, polices ou références visuelles ?

    Générez ensuite un DESIGN.md à partir des réponses. Chaque composition doit faire remonter sa palette et sa typographie à DESIGN.md ou à une directive explicite de l'utilisateur.

2. Créer le squelette

npx hyperframes init my-video --non-interactive

Modèles : blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Passez --example <nom> pour en choisir un, --video clip.mp4 ou --audio track.mp3 pour ensemencer avec des médias.

3. Mise en page avant animation

Écrivez le HTML+CSS statique du hero frame d'abord — pas encore de GSAP. Le conteneur .scene-content doit remplir la scène (width:100%; height:100%; padding:Npx) avec display:flex + gap. Utilisez le padding pour pousser le contenu vers l'intérieur — jamais position: absolute; top: Npx sur un conteneur de contenu (le contenu déborde quand il est plus haut que l'espace restant).

Seulement après que le hero frame semble correct, ajoutez les entrées gsap.from() (animer vers la position CSS) et les sorties gsap.to() (animer depuis celle-ci).

Voir references/composition.md pour le schéma complet des attributs de données et les règles de composition.

4. Animer avec GSAP

Chaque composition doit :

  • Enregistrer sa timeline : window.__timelines["<composition-id>"] = tl
  • Démarrer en pause : gsap.timeline({ paused: true }) — le lecteur contrôle la lecture
  • Utiliser des valeurs repeat finies (pas de repeat: -1 — cela casse le moteur de capture). Calculez : repeat: Math.ceil(duration / cycleDuration) - 1.
  • Être déterministe — pas de Math.random(), Date.now() ou logique d'horloge murale. Utilisez un PRNG ensemencé si vous avez besoin de pseudo-aléatoire.
  • Être construite de manière synchrone — pas de async/await, setTimeout ou Promesses autour de la construction de la timeline.

Voir references/gsap.md pour l'API GSAP de base (tweens, easings, stagger, timelines).

5. Transitions entre les scènes

Les compositions multi-scènes nécessitent des transitions. Règles :

  1. Utilisez toujours une transition entre les scènes — pas de coupes franches.
  2. Utilisez toujours des animations d'entrée sur chaque élément de scène (gsap.from(...)).
  3. N'utilisez jamais d'animations de sortie sauf sur la dernière scène — la transition EST la sortie.
  4. La dernière scène peut s'estomper.

Utilisez npx hyperframes add <nom-transition> pour installer des transitions shader (flash-through-white, liquid-wipe, etc.). Liste complète : npx hyperframes add --list.

6. Audio, légendes, TTS, réactif à l'audio, surlignage

  • Audio : toujours un élément <audio> séparé (la vidéo est muted playsinline).
  • TTS : npx hyperframes tts "Texte du script" --voice af_nova --output narration.wav. Liste des voix avec --list. La première lettre de l'ID de la voix encode la langue (a/b=anglais, e=espagnol, f=français, j=japonais, z=mandarin, etc.) — la CLI déduit automatiquement les paramètres régionaux de phonémisation ; passez --lang uniquement pour remplacer. La phonémisation non-anglaise nécessite espeak-ng installé à l'échelle du système.
  • Légendes : npx hyperframes transcribe narration.wav → transcription au niveau du mot. Choisissez le style en fonction du ton de la transcription (hype / corporate / tutorial / storytelling / social — voir le tableau dans references/features.md). Règle de langue : n'utilisez jamais de modèles whisper .en sauf si l'audio est confirmé anglais — .en traduit l'audio non-anglais au lieu de le transcrire. Chaque groupe de légendes DOIT avoir un tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) de fin après son tween de sortie — sinon les groupes restent visibles dans les suivants.
  • Visuels réactifs à l'audio : pré-extrayez les bandes audio (basses / médiums / aigus) et échantillonnez par image dans la timeline avec une boucle for de tl.call(draw, [], f / fps) — un seul long tween ne réagit PAS à l'audio. Mappez les basses → scale (pulsation), les aigus → textShadow/boxShadow (lueur), l'amplitude globale → opacity/y/backgroundColor. Évitez les clichés d'égaliseur — laissez le contenu guider le visuel, l'audio piloter son comportement.
  • Surlignage de type marqueur : les effets de surlignage, cercle, burst, gribouillage, sketchout pour l'emphase du texte sont du CSS+GSAP déterministe — voir references/features.md#marker-highlighting. Entièrement navigable, aucun filtre SVG animé.
  • Transitions de scène : chaque composition multi-scènes DOIT utiliser des transitions (pas de coupes franches). Choisissez parmi les primitives CSS (push slide, blur crossfade, zoom through, staggered blocks) ou les transitions shader (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split, etc.) via npx hyperframes add. Les tableaux d'ambiance et d'énergie se trouvent dans references/features.md#transitions. Ne mélangez pas les transitions CSS et shader dans la même composition.

7. Lint, valider, inspecter, prévisualiser, rendre

npx hyperframes lint              # détecte les data-composition-id manquants, les pistes qui se chevauchent, les timelines non enregistrées
npx hyperframes validate          # audit de contraste WCAG à 5 horodatages
npx hyperframes inspect           # audit de mise en page visuelle — débordement, éléments hors cadre, texte occulté
npx hyperframes preview           # prévisualisation navigateur en direct
npx hyperframes render --quality draft --output draft.mp4    # itération rapide
npx hyperframes render --quality high --output final.mp4     # livraison finale

hyperframes validate échantillonne les pixels d'arrière-plan derrière chaque élément de texte et avertit pour les rapports de contraste inférieurs à 4.5:1 (ou 3:1 pour les grands textes). hyperframes inspect est le compagnon de mise en page — exécute la page à plusieurs horodatages et signale les problèmes qu'un lint statique ne peut pas voir (une légende qui dépasse la zone de sécurité seulement à 4.5s, une carte qui déborde lorsque son titre est la variante la plus longue, un élément qui se retrouve derrière un shader de transition). Exécutez inspect particulièrement sur les compositions avec des bulles de dialogue, des cartes, des légendes ou une typographie serrée.

8. Site-web-vers-vidéo (si l'utilisateur donne une URL)

Utilisez le workflow de capture-à-vidéo en 7 étapes dans references/website-to-video.md : capture → DESIGN.md → SCRIPT.md → storyboard → composition → rendu → livraison.

Pièges

  • HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ a supprimé ce protocole. Assurez-vous d'être sur hyperframes@>=0.4.2 (détection automatique et repli en mode capture d'écran). Échappatoire : export PRODUCER_FORCE_SCREENSHOT=true. Voir hyperframes#294 et references/troubleshooting.md.
  • Chrome système (pas chrome-headless-shell) — les rendus se bloquent pendant 120s puis expirent. Exécutez npx puppeteer browsers install chrome-headless-shell (setup.sh le fait). hyperframes doctor rapporte quel binaire sera utilisé.
  • repeat: -1 n'importe où — casse le moteur de capture. Calculez toujours un nombre de répétitions fini.
  • gsap.set() sur des éléments de clip qui entrent plus tard — l'élément n'existe pas au chargement de la page. Utilisez tl.set(selector, vars, timePosition) dans la timeline à la place, à ou après le data-start du clip.
  • <br> à l'intérieur du texte de contenu — les sauts de ligne forcés ne connaissent pas la largeur de police rendue, donc le retour à la ligne naturel + <br> double les sauts. Utilisez max-width pour laisser le texte se retourner. Exception : les titres d'affichage courts où chaque mot est délibérément sur sa propre ligne.
  • Animer visibility ou display — GSAP ne peut pas tween ces propriétés. Utilisez autoAlpha (gère à la fois la visibilité et l'opacité).
  • Appeler video.play() ou audio.play() — le framework possède la lecture. Ne les appelez jamais vous-même.
  • Construire des timelines de manière asynchrone — le moteur de capture lit window.__timelines de manière synchrone après le chargement de la page. N'enveloppez jamais la construction de timeline dans async, setTimeout ou une Promise.
  • index.html autonome enveloppé dans <template> — cache tout le contenu du navigateur. Seules les sous-compositions chargées via data-composition-src utilisent <template>.
  • Utiliser la vidéo pour l'audio — toujours <video> en sourdine + <audio> séparé.

Vérification

Avant et après le rendu :

  1. Lint + validation + inspection réussis : npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint détecte les problèmes structurels, validation détecte le contraste, inspection détecte la mise en page visuelle / les débordements — voir troubleshooting.md si des avertissements apparaissent).
  2. Chorégraphie d'animation — pour les nouvelles compositions ou les changements d'animation importants, exécutez la carte d'animation. npx hyperframes init copie les scripts de compétence dans le projet, donc le chemin est local au projet :
    node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
      --out <composition-dir>/.hyperframes/anim-map
    
    Produit un seul animation-map.json avec des résumés par tween, une timeline ASCII Gantt, une détection de stagger, des zones mortes (>1s sans animation), des cycles de vie d'éléments et des drapeaux (offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s). Parcourez les résumés et les drapeaux — corrigez ou justifiez chacun. Ignorez sur les petites modifications.
  3. Le fichier existe + non nul : ls -lh final.mp4.
  4. La durée correspond à data-duration : ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
  5. Vérification visuelle : extrayez une image au milieu de la composition : ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
  6. Audio présent si attendu : ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Si hyperframes render échoue, exécutez npx hyperframes doctor et joignez sa sortie lors du signalement.

Références

  • composition.md — attributs de données, contrat de timeline, règles non négociables, règles de typographie/actifs
  • cli.md — chaque commande CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
  • gsap.md — API GSAP de base pour HyperFrames (tweens, easings, stagger, timelines, matchMedia)
  • features.md — légendes, TTS, réactif à l'audio, surlignage de marqueur, transitions (chargement à la demande)
  • website-to-video.md — workflow de capture à vidéo en 7 étapes
  • troubleshooting.md — correction OpenClaw, variables d'environnement, erreurs de rendu courantes

Skills associés