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 le timing, 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 de manim-video : Utilisez manim-video pour les explications mathématiques/géométriques (équations, style 3B1B). Utilisez hyperframes pour les graphiques animés, les présentateurs avec sous-titres, les visites guidées de produits, les superpositions sociales, les transitions shader, et tout ce qui est piloté par des médias vidéo/audio réels.
Quand utiliser
- L'utilisateur demande une vidéo rendue à partir de texte, d'un script ou d'un site web
- Cartes de titre animées, tiers inférieurs ou intros typographiques
- Vidéo de narration sous-titrée (TTS + sous-titres synchronisés avec la forme d'onde)
- Visuels réactifs à l'audio (synchronisation des battements, barres de spectre, lueur pulsante)
- Transitions de scène à scène (fondu enchaîné, wipe, déformation shader, flash vers le blanc)
- 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 ce skill pour :
- L'animation mathématique pure (→
manim-video) - La génération d'images ou les mèmes (→
meme-generation, modèles d'images) - Les visioconférences ou le streaming en direct
Référence rapide
npx hyperframes init my-video # créer un projet
cd my-video
npx hyperframes lint # valider avant l'aperçu/rendu
npx hyperframes preview # aperçu navigateur avec rechargement en direct (port 3002)
npx hyperframes render --output final.mp4 # rendu en MP4
npx hyperframes doctor # diagnostiquer les problèmes d'environnement
Indicateurs de rendu : --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproductible) · --strict.
Référence complète de l'interface CLI : references/cli.md.
Configuration (unique)
bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
Le script :
- Vérifie que Node.js >= 22 et FFmpeg sont installés (affiche les instructions de correction si ce n'est pas le cas).
- Installe l'interface CLI
hyperframesglobalement (npm install -g hyperframes@>=0.4.2). - Pré-met en cache
chrome-headless-shellvia Puppeteer — requis pour un rendu de meilleure qualité via le chemin de captureHeadlessExperimental.beginFramede Chrome. - Exécute
npx hyperframes doctoret 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, 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)
- Image clé — pour chaque scène, le moment où le plus d'éléments sont simultanément visibles. C'est la disposition statique que vous construirez en premier.
Porte de l'identité visuelle (HARD-GATE). 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é ignorée). Vérifiez dans l'ordre :
-
DESIGN.mdà la racine du projet ? → Utilisez ses couleurs, polices, règles de mouvement et contraintes "Ce qu'il NE FAUT PAS faire" exactes. -
L'utilisateur a nommé un style (par exemple "Swiss Pulse", "dark and techy", "marque de luxe") ? → Générez un
DESIGN.mdminimal avec## Style Prompt,## Colors(3-5 hex avec rôles),## Typography(1-2 familles),## What NOT to Do(3-5 anti-patrons). -
Aucun des cas ci-dessus ? → Posez 3 questions avant d'écrire un HTML :
- Ambiance ? (explosive / cinématique / fluide / technique / chaotique / chaleureuse)
- 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 retracer sa palette et sa typographie jusqu'àDESIGN.mdou une directive explicite de l'utilisateur.
2. Créer la structure
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 amorcer avec des médias.
3. Disposition avant animation
Écrivez le HTML+CSS statique pour l'image clé en premier — 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 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() (animez vers la position CSS) et les sorties gsap.to() (animez à partir de celle-ci).
Consultez 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["<id-de-la-composition>"] = tl - Démarrer en pause :
gsap.timeline({ paused: true })— le lecteur contrôle la lecture - Utiliser des valeurs
repeatfinies (pas derepeat: -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,setTimeoutou Promesses autour de la construction de la timeline.
Consultez references/gsap.md pour l'API GSAP de base (tweens, eases, stagger, timelines).
5. Transitions entre les scènes
Les compositions multi-scènes nécessitent des transitions. Règles :
- Utilisez toujours une transition entre les scènes — pas de coupes franches.
- Utilisez toujours des animations d'entrée sur chaque élément de la scène (
gsap.from(...)). - N'utilisez jamais d'animations de sortie sauf sur la scène finale — la transition EST la sortie.
- La scène finale peut disparaître en fondu.
Utilisez npx hyperframes add <nom-de-la-transition> pour installer des transitions shader (flash-through-white, liquid-wipe, etc.). Liste complète : npx hyperframes add --list.
6. Audio, sous-titres, TTS, réactivité audio, surlignage
- Audio : toujours un élément
<audio>séparé (la vidéo est enmuted playsinline). - TTS :
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 la voix code la langue (a/b=Anglais,e=Espagnol,f=Français,j=Japonais,z=Mandarin, etc.) — l'interface CLI déduit automatiquement la locale du phonémiseur ; passez--languniquement pour la remplacer. La phonémisation non-anglaise nécessiteespeak-nginstallé sur le système. - Sous-titres :
npx hyperframes transcribe narration.wav→ transcription mot par mot. Choisissez le style en fonction du ton de la transcription (hype / corporate / tutorial / storytelling / social — voir le tableau dansreferences/features.md). Règle de langue : n'utilisez jamais les modèles whisper.ensauf si l'audio est confirmé anglais —.entraduit l'audio non-anglais au lieu de le transcrire. Chaque groupe de sous-titres DOIT avoir untl.set(el, { opacity: 0, visibility: "hidden" }, group.end)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 à l'intérieur de la timeline avec une boucle
fordetl.call(draw, [], f / fps)— un seul long tween ne réagit PAS à l'audio. Mappez les basses →scale(impulsion), les aigus →textShadow/boxShadow(lueur), l'amplitude globale →opacity/y/backgroundColor. Évitez les clichés de barres d'égalisation — laissez le contenu guider le visuel, l'audio piloter son comportement. - Surlignage de style marqueur : les effets de surlignage, cercle, burst, gribouillage, esquisse pour l'accentuation du texte sont du CSS+GSAP déterministe — voir
references/features.md#marker-highlighting. Entièrement navigable, pas de filtres SVG animés. - Transitions de scène : chaque composition multi-scènes DOIT utiliser des transitions (pas de coupes franches). Choisissez parmi les primitives CSS (diapositive push, fondu enchaîné flou, zoom traversant, blocs décalés) ou les transitions shader (
flash-through-white,liquid-wipe,cross-warp-morph,chromatic-split, etc.) vianpx hyperframes add. Les tableaux d'ambiance et d'énergie se trouvent dansreferences/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 disposition visuelle — débordement, éléments hors cadre, texte occulté
npx hyperframes preview # aperçu 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é disposition — il 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 sécurisée seulement à 4,5 s, 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 légendes ou une typographie serrée.
8. Site-web-vers-vidéo (si l'utilisateur donne une URL)
Utilisez le workflow de capture 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 surhyperframes@>=0.4.2(détecte automatiquement et revient au mode capture d'écran). Issue de secours :export PRODUCER_FORCE_SCREENSHOT=true. Voir hyperframes#294 et references/troubleshooting.md.- Chrome système (pas
chrome-headless-shell) — les rendus se bloquent pendant 120 s puis expirent. Exécuteznpx puppeteer browsers install chrome-headless-shell(setup.sh le fait).hyperframes doctorsignale quel binaire sera utilisé. repeat: -1n'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. Utiliseztl.set(selector, vars, timePosition)dans la timeline à la place, à ou après ledata-startdu clip.<br>dans le 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. Utilisezmax-widthpour 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
visibilityoudisplay— GSAP ne peut pas faire de tween sur ces propriétés. UtilisezautoAlpha(gère à la fois la visibilité et l'opacité). - Appeler
video.play()ouaudio.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.__timelinesde manière synchrone après le chargement de la page. N'enveloppez jamais la construction de la timeline dansasync,setTimeoutou une Promesse. index.htmlautonome enveloppé dans<template>— cache tout le contenu au navigateur. Seules les sous-compositions chargées viadata-composition-srcutilisent<template>.- Utiliser la vidéo pour l'audio — toujours une
<video>en muet + un<audio>séparé.
Vérification
Avant et après le rendu :
- Passage lint + validation + inspection :
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(le lint détecte les problèmes structurels, la validation détecte le contraste, l'inspection détecte la disposition visuelle / les débordements — voir troubleshooting.md si des avertissements apparaissent). - Chorégraphie d'animation — pour les nouvelles compositions ou les changements d'animation importants, exécutez la carte d'animation.
npx hyperframes initcopie les scripts du skill dans le projet, donc le chemin est local au projet :
Génère un seulnode skills/hyperframes/scripts/animation-map.mjs <dossier-de-composition> \ --out <dossier-de-composition>/.hyperframes/anim-mapanimation-map.jsonavec des résumés par tween, une timeline Gantt ASCII, une détection de décalage, des zones mortes (>1 s sans animation), des cycles de vie d'éléments et des indicateurs (offscreen,collision,invisible,paced-fast<0.2 s,paced-slow>2 s). Parcourez les résumés et les indicateurs — corrigez ou justifiez chacun d'eux. Ignorez pour les petites modifications. - Le fichier existe et n'est pas nul :
ls -lh final.mp4. - La durée correspond à
data-duration:ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4. - Vérification visuelle : extrayez une image au milieu de la composition :
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png. - 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/ressources
- cli.md — toutes les commandes CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
- gsap.md — API GSAP de base pour HyperFrames (tweens, eases, stagger, timelines, matchMedia)
- features.md — sous-titres, TTS, réactivité audio, surlignage de marqueur, transitions (chargement à la demande)
- website-to-video.md — workflow de capture en 7 étapes
- troubleshooting.md — correction OpenClaw, variables d'environnement, erreurs de rendu courantes