HyperFrames
L'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 framework gère la visibilité des plans, la lecture des médias et la synchronisation avec la timeline.
Approche
Découverte (uniquement pour les requêtes exploratoires)
Pour les demandes ouvertes (« réalise une vidéo de lancement produit », « crée quelque chose pour notre marque ») où l'utilisateur n'a pas encore choisi une direction, comprenez d'abord l'intention avant de choisir les couleurs :
- Public — qui regarde cette vidéo ? Développeurs ? Dirigeants ? Grand public ?
- Plateforme — où sera-t-elle diffusée ? Réseaux sociaux (15s), site web (hero), démo produit, usage interne ?
- Priorité — quel est le plus important ? Qualité du mouvement ? Exactitude du contenu ? Fidélité à la marque ? Rapidité ?
- Variantes — l'utilisateur veut-il des options, ou une seule version optimale ?
Pour les demandes spécifiques (« ajoute une carte-titre », « corrige le timing de la scène 3 »), sautez la phase de découverte.
Pour les demandes exploratoires, envisagez de proposer 2 à 3 variantes qui diffèrent significativement — pas seulement des changements de couleurs, mais un rythme, un niveau d'énergie ou une approche structurelle différents. Une version sécurisée/attendue, une version ambitieuse. N'imposez pas cela — c'est un outil disponible quand c'est approprié.
Étape 1 : Design system
Si design.md ou DESIGN.md existe dans le projet, lisez-le d'abord (vérifiez les deux cas — ce sont des fichiers différents sur 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. N'importe quel format fonctionne (YAML frontmatter, prose, tableaux — extrayez simplement les valeurs).
S'il nomme des polices que vous ne trouvez pas localement (pas de répertoire fonts/ avec des fichiers .woff2, pas une police intégrée), prévenez l'utilisateur avant d'écrire du HTML : « design.md spécifie la police [nom de la police] mais aucun fichier de police trouvé. Veuillez ajouter des fichiers .woff2 dans fonts/ ou je me rabattrai sur l'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 presets nommés. Choisissez le plus proche.
- Veut-il explorer les options visuellement ? → Exécutez le sélecteur de design : lisez references/design-picker.md pour le flux 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.
- Veut-il aller vite sans se poser de questions ? → Demandez : ambiance, clair ou sombre, des couleurs/polices de marque ? Choisissez ensuite 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 viennent 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écutée sur chaque composition (à l'exception des scènes uniques et des modifications triviales). Cette étape ancre l'intention de l'utilisateur par rapport à design.md et house-style.md et produit un intermédiaire cohérent que chaque 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 du HTML, réfléchissez à un haut niveau :
- Quoi — que doit ressentir le spectateur ? Identifiez l'arc narratif, les moments clés et les battements émotionnels.
- Structure — combien de compositions, lesquelles sont des sous-compositions vs en ligne, quelles pistes transportent quoi (vidéo, audio, incrustations, sous-titres).
- Rythme — déclarez le rythme de votre scène avant de l'implémenter. Quelles scènes sont des hits rapides, lesquelles sont des temps d'arrêt, où atterrissent les shaders, où l'énergie atteint son pic. Nommez le motif : rapide-rapide-LENT-rapide-SHADER-temps d'arrêt. Lisez references/beat-direction.md pour les modèles de rythme.
- Timing — quels plans déterminent la durée, où atterrissent les transitions, quel est le rythme.
- Mise en page — construisez d'abord l'état final. Voir « Mise en page avant l'animation » ci-dessous.
- Animer — ajoutez ensuite le 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 des éléments supplémentaires améliorent réellement la pièce, proposez-les — ne les ajoutez pas.
Pour les petites modifications (corriger une couleur, ajuster un timing, ajouter un élément), passez directement aux règles.
Mise en page avant l'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, échelle à 0, opacité 0) et que vous les animez vers où vous pensez qu'ils doivent atterrir, vous devinez la mise en page finale. Les chevauchements sont invisibles jusqu'au rendu de la vidéo. En construisant d'abord l'état final, vous pouvez voir et corriger les problèmes de mise en page avant d'ajouter du mouvement.
Le processus
- Identifiez l'image héroïque de chaque scène — le moment où le plus d'éléments sont simultanément visibles. C'est la mise en page que vous construisez.
- Écrivez du CSS statique pour cette image. Le conteneur
.scene-contentDOIT remplir toute la scène avecwidth: 100%; height: 100%; padding: Npx;etdisplay: 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 grand que l'espace restant. Réservezposition: absoluteuniquement pour les éléments décoratifs. - Ajoutez les entrées avec
gsap.from()— animez DEPUIS l'état hors écran/invisible VERS la position CSS. La position CSS est la vérité de base ; le tween décrit le chemin pour y arriver. (Dans les sous-compositions chargées viadata-composition-src, préférezgsap.fromTo()— voir les règles GSAP structurelles dans references/motion-principles.md.) - Ajoutez les sorties avec
gsap.to()— animez VERS l'état 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 : Animez 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 : Animez 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);
Lorsque 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 mise en page, 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 conceptions en z-stack (piles de cartes, couches de profondeur) sont intentionnels. L'étape de mise en page vise à 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 plans
| Attribut | Requis | Valeurs |
|---|---|---|
id | Oui | Identifiant unique |
data-start | Oui | Secondes ou référence d'ID de plan ("el-1", "intro + 2") |
data-duration | Requis pour img/div/compositions | Secondes. La vidéo/l'audio par défaut correspond à la durée du média. |
data-track-index | Oui | Entier. Les plans sur la 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.
Plans de composition
| Attribut | Requis | Valeurs |
|---|---|---|
data-composition-id | Oui | Identifiant de composition unique |
data-start | Oui | Heure de début (composition racine : utilisez "0") |
data-duration | Oui | Prédominance 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-composition |
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'interface 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 la div data-composition-id directement dans <body>. L'utilisation de <template> sur un fichier autonome masque tout le contenu au navigateur et casse le rendu.
Structure de 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 dé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 code source HTML.
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 d'énumération nécessitent égalementoptions: [{value, label}, ...]. - Lisez les valeurs résolues dans le script de la composition avec
window.__hyperframes.getVariables(). Renvoie 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 : la même getVariables() fonctionne dans les 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>
Modèle de composition minimal
<!doctype html>
<html>
<head>
<style>
body { margin: 0; overflow: hidden; }
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
</head>
<body>
<div data-composition-id="mon-fichier" data-width="1920" data-height="1080">
<div id="fond" class="clip"
data-start="0" data-duration="10" data-track-index="0">
<img src="assets/bg.jpg" style="width:100%;height:100%;object-fit:cover">
</div>
<div id="texte" class="clip"
data-start="0" data-duration="10" data-track-index="1">
<div class="titre">Titre</div>
</div>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from(".titre", { y: 60, opacity: 0, duration: 0.8, ease: "power3.out" }, 1);
window.__timelines["mon-fichier"] = tl;
</script>
</div>
</body>
</html>
