HyperFrames
Présentation
HyperFrames est un framework open-source (Apache-2.0) de HeyGen qui transforme du HTML, CSS, des médias et des animations en vidéos MP4 déterministes — une entrée identique produit toujours une sortie identique. Il analyse des compositions HTML annotées avec des attributs de temporisation data-*, pilote Chrome headless pour chercher et capturer chaque image, puis encode le résultat avec FFmpeg. Il n'y a pas d'étape de build, pas d'exigence React, et pas de frais par rendu. Il est conçu pour être compatible avec les agents : la CLI est non interactive par défaut, donc elle s'intègre parfaitement dans des pipelines de contenu automatisés.
Utilisez cette compétence pour générer des projets, rédiger des compositions HTML, les prévisualiser avec rechargement en direct, et rendre des vidéos image par image — y compris des animations réalisées avec GSAP, CSS, Lottie, Three.js, Anime.js, ou l'API Web Animations.
Instructions
Prérequis
Confirmez l'environnement avant de commencer :
- Node.js 22+ (
node --version) - FFmpeg dans le PATH (
ffmpeg -version) - Chrome/Chromium headless est téléchargé par le moteur au premier lancement.
Génération d'un projet
npx hyperframes init my-video # génère un projet (crée index.html + package.json)
cd my-video
Pour une configuration gérée par agent dans un espace de travail AI-agent existant, la compétence peut être installée avec npx skills add heygen-com/hyperframes.
Création d'une composition
Les compositions sont des fichiers index.html simples. Un élément de scène racine déclare le canevas et l'identifiant de composition ; les éléments enfants déclarent quand ils apparaissent et combien de temps ils durent via des attributs data-*. Les valeurs temporelles sont en secondes.
| Attribut | Objectif |
|---|---|
data-composition-id | Nomme la composition (cible pour render/inspect) |
data-start | Quand l'élément entre dans la timeline (secondes) |
data-duration | Combien de temps l'élément reste sur la timeline (secondes) |
data-width / data-height | Dimensions du canevas en pixels (sur l'élément de scène) |
data-track-index | Ordre de piste/piste pour l'audio ou la vidéo superposée |
data-volume | Niveau audio, 0.0–1.0 |
Prévisualisation et rendu
npx hyperframes preview # prévisualisation dans le navigateur avec rechargement en direct pendant la création
npx hyperframes render # cherche chaque image dans Chrome headless, encode en MP4 via FFmpeg
npx hyperframes lint # valide la structure de la composition avant le rendu
npx hyperframes inspect # affiche les métadonnées de la composition (durée, pistes, dimensions)
La résolution provient de data-width/data-height sur la scène ; la fréquence d'images, le chemin de sortie et le codec sont des paramètres de rendu (consultez npx hyperframes render --help pour les indicateurs exacts dans votre version installée, car les noms des indicateurs évoluent). Comme la sortie est déterministe, un rendu ultérieur d'une entrée inchangée peut être mis en cache en toute sécurité.
Utilisation du catalogue de composants
Des blocs pré-construits (transitions, superpositions, légendes, graphiques animés, cartes, effets) s'installent dans le projet :
npx hyperframes add flash-through-white # une transition
npx hyperframes add data-chart # un bloc de graphique animé
npx hyperframes add instagram-follow # une superposition sociale
Parcourez le catalogue complet sur hyperframes.heygen.com/catalog, puis ajoutez des blocs par leur nom.
Animations
Toute animation cherchable et image par image fonctionne car le moteur cherche chaque position de la timeline de manière déterministe plutôt que d'enregistrer en temps réel. Adaptateurs pris en charge : GSAP, animations CSS, Lottie, Three.js, Anime.js, WAAPI, et adaptateurs d'image personnalisés. Évitez le caractère aléatoire basé sur le temps ou le mouvement Date.now()/horloge murale — liez la progression de l'animation à la timeline de la composition pour que les recherches soient reproductibles.
Pipelines agent / CI
La CLI est non interactive, donc un flux automatisé typique est : générer/modéliser le HTML → hyperframes lint → hyperframes render → collecter le MP4. Pour passer à l'échelle, le package @hyperframes/aws-lambda permet le rendu distribué sur Lambda.
Exemples
Exemple 1 : Rendre une composition pour le lancement d'un produit
index.html :
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">Lancement</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # confirme : launch, 6s, 1920x1080
npx hyperframes lint # valide avant de consacrer du temps de rendu
npx hyperframes render # produit un MP4 1080p
Exemple 2 : Une animation de titre GSAP cherchable
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">Résultats Q3</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// Lie la progression à la timeline (tween en pause que le moteur cherche), pas au temps réel.
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // le moteur appelle ceci par image
</script>
</div>
npx hyperframes preview # itérez en direct, puis :
npx hyperframes render
Directives
- Déterminisme d'abord. Liez tout mouvement à la timeline de la composition. Évitez
Math.random(),Date.now(), les boucles en temps réel ou les appels réseau pendant le rendu — ils brisent la reproductibilité. - Validez avant de rendre.
hyperframes lintdétecte les erreurs structurelles/de temporisation à moindre coût ; le rendu est l'étape coûteuse. - Définissez le canevas sur la scène.
data-width/data-heightse trouvent sur l'élément de composition racine ; la temporisation des enfants (data-start/data-duration) se trouve sur chaque élément, en secondes. - Vérifiez la chaîne d'outils. La plupart des échecs proviennent de l'absence de FFmpeg ou de Node < 22, ou d'un téléchargement de Chromium bloqué par un pare-feu.
- Utilisez
--helppour les indicateurs exacts. Les optionsrender/addvarient selon la version ; confirmez les indicateurs fps/sortie/codec par rapport à la CLI installée plutôt que de supposer. - Préférez les blocs du catalogue.
hyperframes addimporte des composants maintenus et cherchables plutôt que de créer manuellement des transitions et des graphiques. - Passez à l'échelle avec Lambda. Pour les lots/tâches volumineuses, effectuez le rendu via
@hyperframes/aws-lambdaplutôt qu'un long travail local. - Gardez les médias locaux et engagés. Référencez les ressources par des chemins stables ; les récupérations distantes pendant le rendu compromettent le déterminisme et la reproductibilité.