HyperFrames
Le HTML est la source de vérité pour la vidéo. Une composition est un fichier HTML avec
les 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 multimédia et la
synchronisation temporelle.
API des attributs, structure composition/template, variables et règles médias : références/authoring.md. Lisez-le avant d'écrire votre premier fichier HTML de composition dans une session.
Approche
Découverte (requêtes exploratoires uniquement)
Pour les demandes ouvertes ("fais-moi une vidéo de lancement de produit") où l'utilisateur ne s'est pas engagé sur une direction, comprenez l'intention avant de choisir les couleurs : audience, plateforme, priorité (qualité du mouvement vs précision vs rapidité) et s'ils veulent des variations. Si variations, proposez-en 2-3 qui diffèrent par le rythme ou la structure - une sûre, une ambitieuse - pas des changements de couleurs.
Pour les demandes spécifiques ("ajoute une carte-titre", "corrige le timing de la scène 3"), sautez la découverte.
Étape 1 : Système de design
Si design.md ou DESIGN.md existe, lisez-le d'abord (les deux casses - ce sont des
fichiers différents sous Linux). C'est la source de vérité pour les couleurs de marque,
polices et contraintes - utilisez ses valeurs exactes. S'il nomme des polices sans
fichiers .woff2 dans fonts/ et sans équivalent intégré, prévenez l'utilisateur avant
d'écrire le HTML.
Si aucun design.md n'existe, proposez un choix :
- L'utilisateur a nommé un style ou une ambiance ? Lisez styles-visuels.md (8 préréglages nommés), choisissez le plus proche.
- Parcourir visuellement ? Lancez le sélecteur de design - références/sélecteur-design.md.
- Aller vite ? Demandez l'ambiance, clair/sombre, couleurs de marque/polices ; choisissez une palette dans style-maison.md.
design.md définit la marque, pas les règles de composition vidéo. Celles-ci viennent de références/composition-vidéo.md et style-maison.md. Couleurs de marque à l'échelle vidéo, pas opacité d'interface web.
Étape 2 : Expansion du prompt
Exécutez sur chaque composition sauf les scènes uniques et les modifications triviales - ancre l'intention par rapport à design.md/style-maison.md dans un intermédiaire cohérent. Processus et format : références/expansion-prompt.md.
Étape 3 : Planification
- Quoi - arc narratif, moments clés, émotions.
- Structure - combien de compositions, sous-compositions vs en ligne, quelles pistes portent quoi.
- Rythme - déclarez le rythme de la scène avant d'implémenter (rapide-rapide-LENT-rapide-SHADER-pause). Templates : références/direction-rythme.md.
- Timing - quels clips déterminent la durée, où tombent les transitions.
- Mise en page - construisez d'abord l'état final (section suivante).
- Animer - puis ajoutez le mouvement.
Construisez ce qui a été demandé. "Une carte-titre" n'est pas "une carte-titre + 3 scènes de soutien + musique + sous-titres." Proposez des suppléments ; ne les ajoutez pas.
Pour les petites modifications, passez directement aux règles.
<PORTE-ÉTROITE>
Avant d'écrire QUEL CONQUE code HTML de composition - vérifiez que vous avez une identité visuelle de l'Étape 1. Si vous utilisez #333, #3b82f6 ou Roboto, vous l'avez ignorée.
</PORTE-ÉTROITE>
Mise en page avant animation
Positionnez chaque élément là où il doit être à son moment le plus visible - complètement entré, correctement placé, pas encore en train de sortir. Écrivez cela d'abord en HTML+CSS statique. Pas encore de GSAP.
Pourquoi : si vous positionnez les éléments à leur état de début animé (hors écran, opacité 0) et que vous effectuez une transition vers où vous pensez qu'ils atterrissent, vous devinez la disposition finale et les chevauchements restent invisibles jusqu'au rendu. Construisez d'abord l'état final et les bugs de mise en page sont visibles avant que le mouvement n'existe.
- Identifiez le cadre héro par scène - le moment où la plupart des éléments sont simultanément visibles. Construisez cette mise en page.
- Écrivez le CSS statique pour cela.
.scene-contentDOIT remplir la scène :width: 100%; height: 100%; padding: Npx;avecdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Le padding pousse le contenu vers l'intérieur - JAMAISposition: absolute; top: Npxsur un conteneur de contenu (cela déborde quand le contenu grandit). Réservez le positionnement absolu pour les éléments décoratifs. - Entrées avec
gsap.from()- animez DEPUIS l'extérieur de l'écran VERS la position CSS. Le CSS est la vérité de base ; l'interpolation est le voyage. (Sous-compositions chargées viadata-composition-src: préférezgsap.fromTo()- voir références/principes-mouvement.md.) - Dernière scène uniquement : sorties avec
gsap.to(). Toutes les autres scènes se terminent entièrement visibles - la transition EST la sortie (règle de transition 3 ci-dessous).
Si l'élément A sort avant que l'élément B n'entre dans la même zone, donnez aux deux les positions CSS correctes pour leurs propres cadres héro - la timeline les empêche de coexister et l'étape de mise en page détecte les chevauchements accidentels dus aux erreurs de timing. Les superpositions intentionnelles (lueur derrière le texte, piles de cartes) sont acceptables ; l'étape existe pour détecter les chevauchements non intentionnels - deux titres qui se heurtent, une statistique couvrant une étiquette, du contenu hors cadre.
Contrat de timeline
- Toutes les timelines commencent
{ paused: true }- le lecteur contrôle la lecture - Enregistrez chaque timeline :
window.__timelines["<id-composition>"] = 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.
PRNG ensemencé (ex. mulberry32) pour le pseudo-aléatoire.
GSAP : animez uniquement les propriétés visuelles (opacity, x, y, scale,
rotation, color, backgroundColor, borderRadius, transformations). Ne jamais
animer visibility ou display ; ne jamais appeler video.play()/audio.play().
Conflits d'animation : n'animez jamais la même propriété sur le même élément depuis plusieurs timelines simultanément.
Pas de repeat: -1 : les répétitions infinies cassent le moteur de capture. Calculez
repeat: Math.ceil(durée / duréeCycle) - 1.
Construction synchrone de timeline : ne construisez jamais de timelines à l'intérieur
d'async/await, setTimeout ou de Promesses - le moteur de capture lit
window.__timelines de manière synchrone après le chargement. Les polices sont intégrées par le
compilateur ; pas d'attente de chargement de polices.
Ne faites jamais :
- Oublier l'enregistrement
window.__timelines - Utiliser une vidéo pour l'audio - toujours vidéo muette +
<audio>séparé - Imbriquer une vidéo dans une div temporisée - utilisez un wrapper non temporisé
- Utiliser
data-layer(utilisezdata-track-index) oudata-end(utilisezdata-duration) - Animer les dimensions d'un élément vidéo - animez une div wrapper
- Appeler play/pause/seek sur le média - le framework possède la lecture
- Créer un conteneur de niveau supérieur sans
data-composition-id - Utiliser
repeat: -1sur une timeline ou une interpolation - Construire des timelines de manière asynchrone
- 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. Utiliseztl.set(selecteur, vars, positionTemporelle)à ou après ledata-startdu clip. - Utiliser
<br>dans le texte de contenu - il s'empile avec l'habillage naturel et provoque des chevauchements ; utilisezmax-widthà la place. Exception : titres d'affichage courts délibérément un mot par ligne.
Transitions de scènes (Non-négociables)
Toute composition multi-scène DOIT suivre les quatre règles. En violer une seule est une composition cassée.
- Utilisez TOUJOURS des transitions entre les scènes. Pas de coupures brusques.
- Animez TOUJOURS chaque élément EN ENTRANT via
gsap.from(). Rien n'apparaît complètement formé. Cinq éléments signifient cinq interpolations d'entrée. - N'utilisez JAMAIS d'animations de sortie sauf sur la dernière scène. Pas de
gsap.to()estompant l'opacité, déplaçant hors écran ou réduisant à 0 avant une transition - la transition EST la sortie et la scène sortante doit être entièrement visible quand elle se déclenche. Une interpolation de sortie avant une transition donne à la transition une image vide. - Dernière scène uniquement peut estomper des éléments en sortie.
Sélection et implémentation des transitions : références/transitions.md.
Garde-fous d'animation
- Décalez la première animation de 0,1 à 0,3 s (pas t=0)
- Variez les easings - au moins 3 easings différents par scène, pas de motif d'entrée répété dans une scène
- Évitez les dégradés linéaires plein écran sur fonds sombres (bandes H.264) - dégradés radiaux ou unis + lueur localisée
- Titres de 60px+, corps de 20px+, étiquettes de données de 16px+
font-variant-numeric: tabular-numssur les colonnes de nombres
Modifier des compositions existantes
- Lisez les fichiers réels, ne devinez pas. La composition EST la spécification - extrayez les codes hexadécimaux exacts, les polices et les motifs d'easing de la source, pas de la mémoire.
- Ne modifiez que ce qui a été demandé ; préservez le timing des clips non concernés.
Liste de vérification de sortie
Rapide (exécutez immédiatement, bloquez sur les résultats) :
-
npx hyperframes lintetnpx hyperframes validateréussissent tous les deux - Conformité au design vérifiée si design.md existe
Lent (exécutez en parallèle tout en présentant l'aperçu) :
-
npx hyperframes inspectréussit, ou tout débordement signalé est intentionnellement marqué - Avertissements de contraste traités
- Chorégraphie d'animation vérifiée (script animation-map)
Comment exécuter et corriger chaque vérification : références/vérifications-qualité.md.
Index des références
À lire toujours pour toute nouvelle composition :
| Fichier | Couvre |
|---|---|
| références/authoring.md | attributs data, structure de template, variables, vidéo/audio, polices/ressources |
| références/composition-vidéo.md | règles du média vidéo - celles-ci remplacent les instincts web |
| références/typographie.md | appariement de polices, OpenType, ajustements fond sombre |
| références/principes-mouvement.md | design de mouvement, mouvement d'image, règles GSAP porteuses |
À lire aussi toujours pour les compositions multi-scènes :
| Fichier | Couvre |
|---|---|
| références/direction-rythme.md | templates de rythme, verbes de chorégraphie, couches de profondeur |
| références/transitions.md | sélection de transitions ; catalogue achemine vers les implémentations ; les transitions shader vivent dans le package npm @hyperframes/shader-transitions (lisez sa source dans node_modules) |
À lire quand la tâche l'exige :
| Fichier | Lire quand |
|---|---|
| références/vérifications-qualité.md | exécution des vérifications inspect/contraste/design/animation-map |
| références/cli.md | toute commande CLI ; dépannage build/rendu |
| références/sous-titres.md | tout texte synchronisé avec le timing audio |
| références/guide-transcription.md | gestion de transcription côté sous-titres (l'invocation CLI vit dans media.md) |
| références/techniques-dynamiques.md | animation dynamique de sous-titres (karaoké, slam, dispersion) |
| références/audio-reactif.md | visuels répondant à la musique/voix |
| références/patterns-css.md | surbrillance de marqueur (surlignage, cercle, éclat, gribouillage) |
| références/techniques.md | techniques de planification par rythme (11 motifs avec code) |
| références/narration.md | rythme voix off/TTS et structure de script |
| références/media.md | TTS (Kokoro), transcription (Whisper), suppression d'arrière-plan |
| références/expansion-prompt.md | Étape 2 de l'approche |
| références/sélecteur-design.md | création visuelle d'un design.md |
| références/depuis-site-web.md | transformer un site web en vidéo |
| références/registre.md | installation/contribution de blocs de registre (hyperframes add) |
| styles-visuels.md | l'utilisateur nomme un style ; génération de design.md |
| style-maison.md | valeurs esthétiques par défaut quand aucun design.md |
| patterns.md | PiP, cartes-titres, diaporamas |
| donnees-en-mouvement.md | données, statistiques, infographies |
Adaptateurs d'exécution (lire quand la composition utilise cet environnement d'exécution au lieu de GSAP) : waapi, lottie, three, animejs, animations-css, typegpu.