HyperFrames
HTML est la source de vérité pour la vidéo. Une composition est un fichier HTML avec des attributs data-* pour le chronométrage, une timeline GSAP pour l'animation et du CSS pour l'apparence. Le framework gère la visibilité des clips, la lecture multimédia et la synchronisation de la timeline.
Approche
Découverte (requêtes exploratoires uniquement)
Pour les demandes ouvertes (« fais-moi une vidéo de lancement de produit », « crée quelque chose pour notre marque ») où l'utilisateur ne s'est pas engagé sur une direction, comprenez l'intention avant de choisir les couleurs :
- Public — qui regarde cela ? Développeurs ? Cadres dirigeants ? Consommateurs grand public ?
- Plateforme — où sera-t-elle diffusée ? Réseaux sociaux (15s), site web hero, démo produit, interne ?
- Priorité — qu'est-ce qui compte le plus ? La qualité du mouvement ? La précision du contenu ? La fidélité à la marque ? La rapidité ?
- Variations — l'utilisateur souhaite-t-il des options ou une seule meilleure proposition ?
Pour les demandes spécifiques (« ajoute une carte-titre », « corrige le timing de la scène 3 »), sautez la découverte.
Pour les demandes exploratoires, envisagez de proposer 2 à 3 variations qui diffèrent significativement — pas seulement des changements de couleur, mais des rythmes, niveaux d'énergie ou approches structurelles différents. Une option sûre/prévue, une ambitieuse. Ne rendez pas cela obligatoire — c'est un outil disponible le cas échéant.
Étape 1 : Système de design
Si design.md ou DESIGN.md existe dans le projet, lisez-le d'abord (vérifiez les deux casses — ce sont des fichiers différents sous Linux). C'est la source de vérité pour les couleurs de la marque, les polices et les contraintes. Utilisez ses valeurs exactes — n'inventez pas de couleurs et ne remplacez pas les polices. Tout format fonctionne (frontmatter YAML, prose, tableaux — extrayez simplement les valeurs).
S'il nomme des polices introuvables localement (pas de répertoire fonts/ avec des fichiers .woff2, pas une police intégrée), prévenez l'utilisateur avant d'écrire le HTML : « design.md spécifie [nom de la police] mais aucun fichier de police trouvé. Veuillez ajouter des fichiers .woff2 dans fonts/ ou je reviendrai à [alternative intégrée la plus proche]. »
Si aucun design.md n'existe, proposez à l'utilisateur un choix :
- L'utilisateur a nommé un style ou une ambiance ? → Lisez visual-styles.md pour les 8 préréglages nommés. Choisissez la correspondance la plus proche.
- Vous voulez parcourir les options visuellement ? → Lancez le sélecteur de design : lisez references/design-picker.md pour le flux de travail complet. Cela sert une page de sélection visuelle. L'utilisateur configure l'ambiance, la palette, la typographie et le mouvement dans le navigateur, puis copie le design.md généré et le colle dans la conversation.
- Vous voulez passer outre et aller vite ? → Demandez : ambiance, clair ou sombre, des couleurs/polices de marque ? Ensuite choisissez une palette dans house-style.md.
design.md définit la marque. Il ne définit pas les règles de composition vidéo. Celles-ci proviennent de references/video-composition.md et house-style.md. Utilisez les couleurs de la marque à une échelle adaptée à la vidéo — pas à l'opacité d'une interface web.
Étape 2 : Expansion du prompt
Toujours exécuter sur chaque composition (sauf les scènes uniques et les modifications triviales). Cette étape ancre l'intention de l'utilisateur par rapport à design.md et house-style.md et produit un état intermédiaire cohérent que tout agent en aval lit de la même manière.
Lisez references/prompt-expansion.md pour le processus complet et le format de sortie.
Étape 3 : Planification
Avant d'écrire le HTML, réfléchissez à un niveau élevé :
- Quoi — que doit vivre le spectateur ? Identifiez l'arc narratif, les moments clés et les temps forts émotionnels.
- Structure — combien de compositions, lesquelles sont des sous-compositions ou en ligne, quelles pistes transportent quoi (vidéo, audio, incrustations, sous-titres).
- Rythme — déclarez votre rythme de scène avant de l'implémenter. Quelles scènes sont rapides, lesquelles sont des poses, où atterrissent les shaders, où l'énergie atteint son pic. Nommez le motif : rapide-rapide-LENT-rapide-SHADER-pause. Lisez references/beat-direction.md pour les modèles de rythme.
- Chronométrage — quels clips déterminent la durée, où se situent les transitions, quel est le rythme.
- Disposition — construisez d'abord l'état final. Voir « Disposition avant animation » ci-dessous.
- Animer — ajoutez ensuite du mouvement en utilisant les règles ci-dessous.
Construisez ce qui a été demandé. Une demande pour « une carte-titre » n'est pas une demande pour « une carte-titre + 3 scènes d'accompagnement + musique d'ambiance + sous-titres ». Chaque scène, chaque élément, chaque tween doit mériter sa place. Si des scènes ou éléments supplémentaires amélioraient véritablement la pièce, proposez-les — ne les ajoutez pas.
Pour les petites modifications (corriger une couleur, ajuster le timing, ajouter un élément), passez directement aux règles.
Disposition avant animation
Positionnez chaque élément là où il doit être à son moment le plus visible — l'image où il est complètement entré, correctement placé et pas encore en train de sortir. Écrivez cela d'abord en HTML+CSS statique. Pas encore de GSAP.
Pourquoi c'est important : Si vous positionnez les éléments à leur état de départ animé (hors écran, mis à l'échelle à 0, opacité 0) et que vous les animez vers l'endroit où vous pensez qu'ils doivent atterrir, vous devinez la disposition finale. Les chevauchements sont invisibles jusqu'à ce que la vidéo soit rendue. En construisant l'état final en premier, vous pouvez voir et corriger les problèmes de disposition avant d'ajouter du mouvement.
Le processus
- Identifiez l'image héroïque pour chaque scène — le moment où le plus d'éléments sont simultanément visibles. C'est la disposition que vous construisez.
- Écrivez le CSS statique pour cette image. Le conteneur
.scene-contentDOIT remplir toute la scène en utilisantwidth: 100%; height: 100%; padding: Npx;avecdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Utilisez le padding pour pousser le contenu vers l'intérieur — JAMAISposition: absolute; top: Npxsur un conteneur de contenu. Les conteneurs de contenu positionnés en absolu débordent lorsque le contenu est plus haut que l'espace restant. Réservezposition: absoluteuniquement pour les éléments décoratifs. - Ajoutez les entrées avec
gsap.from()— animez DEPUIS hors écran/invisible VERS la position CSS. La position CSS est la vérité de référence ; le tween décrit le voyage pour y arriver. (Dans les sous-compositions chargées viadata-composition-src, préférezgsap.fromTo()— voir les règles GSAP importantes dans references/motion-principles.md.) - Ajoutez les sorties avec
gsap.to()— animez VERS hors écran/invisible DEPUIS la position CSS.
Exemple
/* scene-content remplit la scène, le padding positionne le contenu */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* Le conteneur remplit n'importe quelle taille de scène (1920x1080, 1080x1920, etc.).
Le padding positionne le contenu. Flex + gap gère l'espacement. */
MAUVAIS — dimensions codées en dur et positionnement absolu :
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Étape 3 : Animer VERS ces positions
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Étape 4 : Animer DEPUIS ces positions
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Quand des éléments partagent l'espace dans le temps
Si l'élément A sort avant que l'élément B n'entre dans la même zone, les deux doivent avoir des positions CSS correctes pour leurs images héroïques respectives. L'ordre de la timeline garantit qu'ils ne coexistent jamais visuellement — mais si vous sautez l'étape de disposition, vous ne détecterez pas le cas où ils se chevauchent accidentellement en raison d'une erreur de timing.
Ce qui compte comme chevauchement intentionnel
Les effets superposés (lueur derrière le texte, éléments d'ombre, motifs d'arrière-plan) et les designs empilés en z (piles de cartes, couches de profondeur) sont intentionnels. L'étape de disposition consiste à détecter les chevauchements non intentionnels — deux titres atterrissant l'un sur l'autre, une statistique couvrant une étiquette, un contenu débordant du cadre.
Attributs de données
Tous les clips
| Attribut | Requis | Valeurs |
|---|---|---|
id | Oui | Identifiant unique |
data-start | Oui | Secondes ou référence d'ID de clip ("el-1", "intro + 2") |
data-duration | Requis pour img/div/compositions | Secondes. La vidéo/audio par défaut suit la durée du média. |
data-track-index | Oui | Entier. Les clips d'une même piste ne peuvent pas se chevaucher. |
data-media-start | Non | Décalage de coupe dans la source (secondes) |
data-volume | Non | 0-1 (par défaut 1) |
data-track-index n'affecte pas la superposition visuelle — utilisez CSS z-index.
Clips de composition
| Attribut | Requis | Valeurs |
|---|---|---|
data-composition-id | Oui | ID unique de composition |
data-start | Oui | Heure de début (composition racine : utilisez "0") |
data-duration | Oui | Prime sur la durée de la timeline GSAP |
data-width / data-height | Oui | Dimensions en pixels (1920x1080 ou 1080x1920) |
data-composition-src | Non | Chemin vers un fichier HTML externe |
data-variable-values | Non | Objet JSON de remplacements de variables par instance sur un hôte de sous-comp |
Sur l'élément racine <html> :
| Attribut | Requis | Valeurs |
|---|---|---|
data-composition-variables | Non | Tableau JSON de variables déclarées (id/type/label/default) — pilote l'UI d'édition Studio et fournit les valeurs par défaut pour getVariables() |
Structure de composition
Les sous-compositions chargées via data-composition-src utilisent un wrapper <template>. Les compositions autonomes (le fichier index.html principal) n'utilisent PAS <template> — elles placent le div data-composition-id directement dans <body>. L'utilisation de <template> sur un fichier autonome cache tout le contenu au navigateur et casse le rendu.
Structure d'une sous-composition :
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- contenu -->
<style>
[data-composition-id="my-comp"] {
/* styles limités */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Chargement dans la racine : <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Variables (Compositions paramétrées)
Rendez la même composition avec un contenu différent — titre, couleur de thème, prix, sous-titres — sans modifier le HTML source.
Modèle en trois étapes :
- Déclarez les variables sur la racine
<html>de la composition avecdata-composition-variables. Chaque entrée nécessiteid,type(parmistring,number,color,boolean,enum),labeletdefault. Les entrées Enum nécessitent égalementoptions: [{value, label}, ...]. - Lisez les valeurs résolues dans le script de la composition avec
window.__hyperframes.getVariables(). Retourne le résultat fusionné des valeurs par défaut déclarées + des remplacements par instance + des remplacements CLI. - Remplacez au moment du rendu avec
npx hyperframes render --variables '{...}'(niveau supérieur) ou avecdata-variable-values='{...}'sur l'élément hôte (par instance pour les sous-compositions).
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"Titre","default":"Bonjour"},
{"id":"theme","type":"enum","label":"Thème","default":"light","options":[
{"value":"light","label":"Clair"},
{"value":"dark","label":"Sombre"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# L'aperçu de développement utilise les valeurs par défaut déclarées
npx hyperframes preview
# Rendu avec remplacements
npx hyperframes render --variables '{"title":"Rapport Q4","theme":"dark"}' --output q4.mp4
# Ou depuis un fichier JSON
npx hyperframes render --variables-file ./vars.json
Valeurs par instance de sous-composition : le même getVariables() fonctionne à l'intérieur des sous-compositions chargées via data-composition-src. Chaque élément hôte transmet ses propres valeurs :
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"29€"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Entreprise","price":"99€"}'
></div>
Animations
Règles GSAP
- Ne jamais utiliser
gsap.set()– utilisezgsap.from()ougsap.fromTo(). GSAP.set équivaut àgsap.to({duration:0})et contourneuseFramessi défini. Utilisezfrom/fromTopour garantir que la position CSS est l'état final. - Ne jamais utiliser
tl.delay()– utilisez le paramètre de position d'un appelto/from/fromTo:tl.to(el, {}, 1.5)au lieu detl.to(el, {delay:1.5}). Les retards peuvent casser les calculs de durée de la timeline. - Ne jamais utiliser
tl.play()– utiliseztl.resume()outl.totalProgress().tl.play()réinitialise la direction àforwardcomme effet secondaire. - Ne jamais utiliser
tl.seek(0)– utiliseztl.totalProgress(0).seekréinitialisevarset peut avoir d'autres effets secondaires dans GSAP 3.14. - Ne jamais invoquer
getVariables()avant le DOMContentLoaded – au moment où ce script s'exécute, le DOM peut ne pas avoir fini de charger ou d'analyser les attributs de variable. Enveloppez-la toujours dans un écouteur d'événement DOMContentLoaded ou placez le script à la fin du<body>. - Utilisez
gsap.quickTo()pour les animations performantes – particulièrement pour les mises à jour basées sur la souris ou le défilement.quickToévite la création d'objets en interne et donne le meilleur taux de rafraîchissement. - Utilisez
ease: "none"avecgsap.to(el, {motionPath: {...}})– évite un easement non uniforme le long du chemin qui ferait que l'objet ralentisse ou accélère de manière inattendue aux virages. - Les animations en boucle doivent être explicitement demandées – ne mettez pas en boucle les animations indéfiniment sauf si l'utilisateur le demande. Si une boucle est nécessaire (icône tournante, pulsation), utilisez
repeat: -1sur le tween (to/fromavecrepeat, pas surto/fromde la timeline) et ajouteztl.timeScale(<nombre>)sur la timeline uniquement lorsque la boucle est explicitement demandée.
Règles SVG
- Préfixez les IDs SVG avec l'ID de la composition – les IDs SVG sont globaux dans le document. L'utilisation d'IDs en conflit (deux compositions utilisant
#gradient) fait que la dernière définition écrase la précédente. - Styles SVG OK : fill, stroke, stroke-width, opacity, filter, mask, clip-path. Pas de display: grid/flex à l'intérieur des SVG (les éléments SVG n'ont pas de disposition de bloc).
Transitions
Pour ajouter des transitions entre les scènes, ajoutez data-transition-* sur le conteneur de la scène :
| Attribut | Valeurs |
|---|---|
data-transition-in | crossfade, wipe-left, wipe-right, wipe-up, wipe-down, reveal-left, reveal-right, noir |
data-transition-out | crossfade, wipe-left, wipe-right, wipe-up, wipe-down, noir, dissolve, shatter, fade-through-black |
data-transition-duration-in | Secondes (par défaut 0.5) |
data-transition-duration-out | Secondes (par défaut 0.5) |
Les transitions shader utilisent GLSL pour des effets avancés. Spécifiez data-shader-transition="<nom-du-shader>" à la place de l'attribut de transition standard, et incluez data-shader-duration.
Rendu et exportation
Voir le skill hyperframes-cli. Les commandes clés : npx hyperframes init, npx hyperframes preview, npx hyperframes render. L'aperçu est itératif — une visualisation localhost reflète les changements en temps réel.
Écosystème de skills
- s2530786-cell/hyperframes-cli — Commandes CLI dev-loop (init, lint, inspect, preview, render)
- s2530786-cell/hyperframes-media — Prétraitement des assets (tts, transcribe, remove-background)