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 framework gère la visibilité des clips, la lecture des médias et la synchronisation de la timeline.
Approche
Avant d'écrire du HTML, réfléchissez à un niveau élevé :
- Quoi — que doit vivre 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, superpositions, sous-titres).
- Timing — quels clips déterminent la durée, où se placent les transitions, quel est le rythme.
- Disposition — construisez d'abord l'état final. Voir "Disposition avant Animation" ci-dessous.
- Animer — puis ajoutez du mouvement en utilisant les règles ci-dessous.
Pour les petites modifications (corriger une couleur, ajuster le timing, ajouter un élément), passez directement aux règles.
Porte d'Identité Visuelle
Vérifiez dans cet ordre :
- DESIGN.md existe dans le projet ? → Lisez-le. Utilisez ses couleurs, polices, règles de mouvement et contraintes "Ce qu'il ne faut PAS faire" exactes.
- visual-style.md existe ? → Lisez-le. Appliquez son
style_prompt_fullet ses champs structurés. (Note :visual-style.mdest un fichier spécifique au projet.visual-styles.mdest la bibliothèque de styles avec 8 préréglages nommés — fichiers différents.) - L'utilisateur a nommé un style (ex. "Swiss Pulse", "dark and techy", "luxury brand") ? → Lisez visual-styles.md pour les 8 préréglages nommés. Générez un DESIGN.md minimal avec :
## Style Prompt(un paragraphe),## Colors(3-5 valeurs hexadécimales avec rôles),## Typography(1-2 familles de polices),## What NOT to Do(3-5 anti-patrons). - Rien de ce qui précède ? → Posez 3 questions avant d'écrire du HTML :
- Quelle est l'ambiance ? (explosif / cinématographique / fluide / technique / chaotique / chaleureux)
- Toile claire ou sombre ?
- Des couleurs, polices ou références visuelles spécifiques de marque ? Générez ensuite un DESIGN.md minimal à partir des réponses.
Chaque composition doit faire remonter sa palette et sa typographie à un DESIGN.md, visual-style.md, ou à une direction utilisateur explicite. Si vous utilisez #333, #3b82f6, ou Roboto — vous avez sauté cette étape.
Pour les valeurs par défaut du mouvement, le dimensionnement, les motifs d'entrée et l'assouplissement — suivez house-style.md. Le style maison gère COMMENT les choses bougent. Le DESIGN.md gère À QUOI ressemblent les choses.
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 d'abord cela 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 les animez vers où vous pensez qu'ils devraient atterrir, vous devinez la disposition finale. Les chevauchements sont invisibles jusqu'à ce que la vidéo soit rendue. En construisant d'abord l'état final, 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 du 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 ; l'interpolation décrit le voyage pour y arriver. - 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 de 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 en couches (lueur derrière le texte, éléments d'ombre, motifs d'arrière-plan) et les conceptions en pile 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 recouvrant 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 est la durée du média. |
data-track-index | Oui | Entier. Les clips de la même piste ne peuvent pas se chevaucher. |
data-media-start | Non | Décalage de découpage 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 | Identifiant unique de composition |
data-start | Oui | Heure de début (composition racine : utiliser "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 |
Structure de Composition
Les sous-compositions chargées via data-composition-src utilisent un wrapper <template>. Les compositions autonomes (le index.html principal) n'utilisent PAS <template> — elles placent le div data-composition-id directement dans <body>. Utiliser <template> sur un fichier autonome cache tout le contenu au navigateur et casse le rendu.
Structure de sous-composition :
<template id="ma-comp-template">
<div data-composition-id="ma-comp" data-width="1920" data-height="1080">
<!-- contenu -->
<style>
[data-composition-id="ma-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 });
// interpolations...
window.__timelines["ma-comp"] = tl;
</script>
</div>
</template>
Charger dans la racine : <div id="el-1" data-composition-id="ma-comp" data-composition-src="compositions/ma-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Vidéo et Audio
La vidéo doit être muted playsinline. L'audio est toujours un élément <audio> séparé :
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
Contrat de Timeline
- Toutes les timelines commencent
{ paused: true }— le lecteur contrôle la lecture - Enregistrez chaque timeline :
window.__timelines["<composition-id>"] = tl - Le framework imbrique automatiquement les sous-timelines — ne les ajoutez PAS manuellement
- La durée provient de
data-duration, pas de la longueur de la timeline GSAP - Ne créez jamais d'interpolations vides pour définir la durée
Règles (Non Négociables)
Déterministe : Pas de Math.random(), Date.now(), ou logique basée sur le temps. Utilisez un PRNG à graine si vous avez besoin de valeurs pseudo-aléatoires (ex. mulberry32).
GSAP : Animez uniquement les propriétés visuelles (opacity, x, y, scale, rotation, color, backgroundColor, borderRadius, transformations). N'animez PAS visibility, display, ou n'appelez pas video.play()/audio.play().
Conflits d'animation : N'animez jamais la même propriété sur le même élément à partir de plusieurs timelines simultanément.
Pas de repeat: -1 : Les timelines à répétition infinie cassent le moteur de capture. Calculez le nombre exact de répétitions à partir de la durée de la composition : repeat: Math.ceil(duration / cycleDuration) - 1.
Construction synchrone de timeline : Ne construisez jamais de timelines à l'intérieur de async/await, setTimeout, ou Promesses. Le moteur de capture lit window.__timelines de manière synchrone après le chargement de la page. Les polices sont intégrées par le compilateur, donc elles sont disponibles immédiatement — pas besoin d'attendre le chargement des polices.
Ne jamais faire :
- Oublier l'enregistrement
window.__timelines - Utiliser la vidéo pour l'audio — toujours vidéo muette +
<audio>séparé - Nicher une vidéo à l'intérieur d'un div temporisé — utiliser un wrapper non temporisé
- Utiliser
data-layer(utiliserdata-track-index) oudata-end(utiliserdata-duration) - Animer les dimensions de l'élément vidéo — animer un wrapper div
- Appeler play/pause/seek sur le média — le framework possède la lecture
- Créer un conteneur de premier niveau sans
data-composition-id - Utiliser
repeat: -1sur une timeline ou une interpolation — toujours des répétitions finies - Construire des timelines de manière asynchrone (à l'intérieur de
async,setTimeout,Promise) - Utiliser
gsap.set()sur des éléments de clip de scènes ultérieures — ils n'existent pas dans le DOM au chargement de la page. Utilisez plutôttl.set(selector, vars, timePosition)à l'intérieur de la timeline au moment ou après ledata-startdu clip. - Utiliser
<br>dans le texte de contenu — les sauts de ligne forcés ne tiennent pas compte de la largeur réelle de la police rendue. Le texte qui se plie naturellement + un<br>produit un saut supplémentaire indésirable, provoquant un chevauchement. Laissez le texte se plier viamax-widthà la place. Exception : les titres d'affichage courts où chaque mot est délibérément sur sa propre ligne (ex. "THE\nIMMORTAL\nGAME" à 130px).
Transitions de Scène (Non Négociables)
Chaque composition multi-scène DOIT suivre TOUTES ces règles. En violer une seule est une composition cassée.
- TOUJOURS utiliser des transitions entre les scènes. Pas de coupes franches. Aucune exception.
- TOUJOURS utiliser des animations d'entrée sur chaque scène. Chaque élément anime ENTRANT via
gsap.from(). Aucun élément ne peut apparaître complètement formé. Si une scène a 5 éléments, elle a besoin de 5 interpolations d'entrée. - NE JAMAIS utiliser d'animations de sortie sauf sur la scène finale. Cela signifie : PAS de
gsap.to()qui anime l'opacité à 0, y hors écran, l'échelle à 0, ou toute autre animation "de sortie" avant qu'une transition ne se déclenche. La transition EST la sortie. Le contenu de la scène sortante DOIT être entièrement visible au moment où la transition commence. - Scène finale uniquement : La dernière scène peut estomper des éléments (ex. fondu au noir). C'est la SEULE scène où
gsap.to(..., { opacity: 0 })est autorisé.
MAUVAIS — animation de sortie avant la transition :
// INTERDIT — cela vide la scène avant que la transition ne puisse l'utiliser
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// la transition se déclenche sur une image vide
CORRECT — entrée uniquement, la transition gère la sortie :
// Animations d'entrée de la scène 1
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// PAS d'interpolations de sortie — la transition à 7.2 s gère le changement de scène
// Animations d'entrée de la scène 2
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
Garde-fous d'Animation
- Décalez la première animation de 0,1 à 0,3 s (pas à t=0)
- Variez les assouplissements entre les interpolations d'entrée — utilisez au moins 3 assouplissements différents par scène
- Ne répétez pas un motif d'entrée dans une scène
- Évitez les dégradés linéaires plein écran sur les arrière-plans sombres (bandes H.264 — utilisez radial ou uni + lueur localisée)
- Titres de 60px+, corps de 20px+, étiquettes de données de 16px+ pour la vidéo rendue
font-variant-numeric: tabular-numssur les colonnes de nombres
Lorsqu'aucun visual-style.md ou direction d'animation n'est fourni, suivez house-style.md pour les valeurs par défaut esthétiques.
Typographie et Ressources
- Polices : Écrivez simplement la
font-familyque vous voulez en CSS — le compilateur intègre automatiquement les polices prises en charge. Si une police n'est pas prise en charge, le compilateur avertit. - Ajoutez
crossorigin="anonymous"aux médias externes