Communitygithub.com

HyperFrames

Génère des vidéos MP4/WebM à partir de compositions HTML animées.

Qu'est-ce que HyperFrames ?

HyperFrames permet de créer des vidéos en utilisant HTML comme source de vérité. Une composition est un fichier HTML avec des attributs `data-*` pour la synchronisation, une timeline GSAP pour l'animation, et du CSS pour l'apparence. Le moteur capture la page image par image et l'encode en MP4 ou WebM via FFmpeg. Cet outil est idéal pour les graphiques animés, les vidéos avec voice-over et sous-titres, les transitions de scènes, et tout ce qui peut être réalisé avec du HTML/CSS/JS déterministe. Il est conçu pour être utilisé avec l'outil `manim-video` (pour les explications mathématiques) et ne doit pas être utilisé pour la génération d'images, les mèmes, ou le streaming en direct. HyperFrames fournit une CLI complète pour initialiser un projet, valider, prévisualiser en direct et rendre la vidéo finale. Il nécessite Node.js >= 22, FFmpeg, et un navigateur Chrome headless pour le rendu de haute qualité.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/hyperframes

Demander à votre IA préférée

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

Documentation

Que fait HyperFrames ?

HTML est la source de vérité pour la vidéo. Une composition est un fichier HTML avec des attributs data-* pour la synchronisation, une timeline GSAP pour l'animation, et du CSS pour l'apparence. Le moteur HyperFrames capture la page image par image et l'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, les plans avec intervenant et sous-titres, les présentations de produits, les superpositions pour réseaux sociaux, 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 de 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 (synthèse vocale + sous-titres synchronisés sur la forme d'onde)
  • Visuels réactifs à l'audio (synchronisation au rythme, barres de spectre, lueur pulsée)
  • Transitions entre scènes (fondu, volet, warp shader, flash vers le blanc)
  • Superpositions pour réseaux sociaux (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 pure de maths/équations (→ manim-video)
  • Génération d'images ou de mèmes (→ meme-generation, modèles d'image)
  • Vidéoconférence ou streaming 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 avec rechargement en direct (serveur longue durée, port 3002)
npx hyperframes render --output final.mp4   # rendu en MP4
npx hyperframes doctor                      # diagnostiquer l'environnement

preview est un serveur Next.js longue durée qui maintient les workers Chrome ouverts. Arrêtez-le toujours après usage (voir Nettoyage) — une prévisualisation oubliée maintient actifs des workers chrome-headless-shell inactifs qui, sur les hôtes sans GPU (WSL, conteneurs, CI), utilisent un cœur CPU chacun indéfiniment via WebGL logiciel (swiftshader).

Indicateurs 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 (une fois)

bash "$(dirname "$(find ~/.nastech/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.

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

Procédure

1. Planifier avant d'écrire le HTML

Avant de toucher au code, décrivez à un niveau général :

  • 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)
  • Image clé — 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 construirez en premier.

Barrière d'identité visuelle (BARRIÈRE OBLIGATOIRE). Avant d'écrire UNE QUELCONQUE 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".

  2. L'utilisateur a nommé un style (ex. "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. Aucun des cas ci-dessus ? → Posez 3 questions avant d'écrire du HTML :

    • Ambiance ? (explosive / cinématique / fluide / technique / chaotique / chaleureuse)
    • Toile claire ou foncée ?
    • 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 direction explicite de l'utilisateur.

2. Initialiser

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 l'amorcer avec des médias.

3. Mise en page avant l'animation

Écrivez le HTML+CSS statique pour l'image clé 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 — n'utilisez jamais position: absolute; top: Npx sur un conteneur de contenu (le contenu déborde lorsqu'il est plus haut que l'espace restant).

Ce n'est qu'après que l'image clé semble correcte que vous ajoutez les entrées gsap.from() (animer vers la position CSS) et les sorties gsap.to() (animer depuis celle-ci).

Consultez references/composition.md pour le schéma complet des attributs data-* 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. Utilisez un PRNG à graine si vous avez besoin de pseudo-aléatoire.
  • Se construire de manière synchrone — pas de async/await, setTimeout ou Promesses autour de la construction de la timeline.

Consultez references/gsap.md pour l'API GSAP principale (tweens, eased, 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 la scène (gsap.from(...)).
  3. N'utilisez jamais d'animations de sortie sauf sur la scène finale — la transition EST la sortie.
  4. La scène finale 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, sous-titres, synthèse vocale, réactivité audio, surlignage

  • Audio : toujours un élément <audio> séparé (la vidéo est muted playsinline).
  • Synthèse vocale : npx hyperframes tts "Texte du script" --voice af_nova --output narration.wav. Listez les voix avec --list. La première lettre de l'ID de 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 du phonémiseur ; passez --lang uniquement pour remplacer. La phonémisation non-anglaise nécessite espeak-ng installé au niveau système.
  • Sous-titres : npx hyperframes transcribe narration.wav → transcription au niveau du mot. Choisissez le style selon le ton de la transcription (hype / corporate / tutoriel / narration / 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é en anglais — .en traduit l'audio non-anglais au lieu de le transcrire. Chaque groupe de sous-titres DOIT avoir un tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) de coupure après son tween de sortie — sinon les groupes fuient visibles dans les suivants.
  • Visuels réactifs à l'audio : extrayez au préalable 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 de barres 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 : toute composition multi-scène DOIT utiliser des transitions (pas de coupes franches). Choisissez parmi les primitives CSS (glissement poussé, fondu flou, zoom traversant, blocs décalés) 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 timestamps
npx hyperframes inspect           # audit de mise en page visuelle — débordement, éléments hors trame, texte occulté
npx hyperframes preview           # prévisualisation dans le 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 côté mise en page — exécute la page à plusieurs timestamps et signale les problèmes qu'un lint statique ne peut pas voir (un sous-titre 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 en particulier sur les compositions avec des bulles de dialogue, des cartes, des sous-titres ou une typographie serrée.

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

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

Nettoyage

render est à usage unique (les workers se ferment à la fin). preview ne l'est pas — il exécute un serveur Next.js en arrière-plan qui maintient les workers Chrome résidents jusqu'à ce que vous l'arrêtiez. Ne le laissez jamais tourner : sur les hôtes sans GPU, chaque worker inactif et son processus swiftshader utilisent un cœur CPU, et une prévisualisation laissée ouverte pendant des jours en accumule plusieurs.

Arrêtez une prévisualisation lorsque l'utilisateur a fini de réviser (ou avant d'en démarrer une nouvelle) :

pkill -f "hyperframes.*preview"     # le serveur Studio (libère le port 3002)
pkill -f chrome-headless-shell      # ses workers de rendu ; sûr seulement si rien d'autre ne les utilise

En cas de doute sur l'utilisation de chrome-headless-shell par d'autres outils, vérifiez d'abord : pgrep -af chrome-headless-shell. Récupérez un hôte bloqué (plusieurs workers inactifs qui utilisent le CPU) de la même manière — voir references/troubleshooting.md.

Pièges

  • Laisser preview tourner — c'est un serveur longue durée qui maintient des workers Chrome ; sur WSL/conteneurs/CI, ces workers inactifs utilisent un cœur CPU chacun (WebGL logiciel). Arrêtez-le après usage — voir Nettoyage.

  • 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 sur le mode capture d'écran). Solution de contournement : export PRODUCER_FORCE_SCREENSHOT=true. Voir hyperframes#294 et references/troubleshooting.md.

  • Chrome système (pas chrome-headless-shell) — le rendu se bloque pendant 120s puis expire. Exécutez npx puppeteer browsers install chrome-headless-shell (setup.sh le fait). hyperframes doctor rapporte quel binaire sera utilisé.

  • repeat: -1 quelque part — 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, au moment ou après le data-start du clip.

  • <br> dans le texte du contenu — les sauts 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 renvoyer à la ligne. 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 visibility et opacity).

  • Appeler video.play() ou audio.play() — le framework contrôle 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 la timeline dans async, setTimeout ou une Promise.

  • index.html autonome enveloppé dans <template> — cache tout le contenu au navigateur. Seules les sous-compositions chargées via data-composition-src utilisent <template>.

  • Utiliser la vidéo pour l'audio — toujours <video> muette + <audio> séparée.

Vérification

Avant et après le rendu :

  1. Passage de lint + validation + inspection : 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 problèmes de débordement — 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, la détection de staggered, les zones mortes (>1s sans animation), les cycles de vie des éléments, et des indicateurs (offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s). Parcourez les résumés et les indicateurs — corrigez ou justifiez chacun. Sautez sur les petites modifications.
  3. Fichier existe + non nul : ls -lh final.mp4.
  4. La durée correspond à data-duration : ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 final.mp4

Skills associés