Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution du plugin lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Que fait HyperFrames Keyframes ?
Les keyframes sont un contrat de pose : états visibles, identité continue du sujet, exécution seek-safe, pixels vérifiés.
Utilisez hyperframes-animation pour les recettes de scène larges. Utilisez hyperframes-cli pour la documentation complète des commandes. Utilisez references/keyframe-patterns.md uniquement lors du choix des mécanismes d'implémentation, pas du style visuel.
Limite d'édition du créateur
Les keyframes gèrent le mouvement visuel, pas l'assemblage des clips. Les coupures brutales de la source, le rognage, l'épissage et la réorganisation appartiennent à /hyperframes-core : rédigez un élément média par plage conservée, placez-le avec data-start et data-duration, et sélectionnez son décalage source avec data-media-start. Les plages adjacentes créent une coupure brutale. Un fondu enchaîné utilise des clips qui se chevauchent sur différentes pistes plus des keyframes d'opacité visuelle ; les fondus sonores utilisent /hyperframes-audio.
| Demande du créateur | Mécanisme véridique |
|---|---|
| Punch-in / punch-out | Keyframe scale avec translation x/y ou pourcentage sur un wrapper visuel/recadrage non temporisé à l'intérieur du clip. Utilisez un tween court/ferme pour un punch brusque et un tween pour un mouvement fluide. |
| Zoom fluide multi-état ou recadrage | Gardez un wrapper de sujet vivant et rédigez plusieurs états de zoom/recadrage comme une échelle de poses avec un easing par segment. |
| Panoramique, recadrage ou mouvement de caméra Ken Burns | Animer la translation du wrapper plus l'échelle. La géométrie est rédigée ; ce n'est pas un suivi de visage ou un recadrage sémantique automatique. |
| Mouvements de caméra enchaînés | Enchaînez des temps de transformation étiquetés sur une seule timeline seek-safe enregistrée. |
| Cut correspondant ou whip pan | /hyperframes-animation gère le transfert visuel ; /hyperframes-registry fournit les primitives ; les keyframes préservent la géométrie, la direction et la vélocité rédigées. Il n'y a pas de découverte automatique de trame correspondante. |
| Recadrage par crop et masque | Interpolez clip-path ou un masque sur un wrapper visuel interne pour recadrer/recadrer sans changer le temps source. Les keyframes polygonales peuvent former une transition polygone/masque. |
| Cut wipe directionnel ou cut iris/révélation | Animez une limite de masque/clip à travers des clips visuels qui se chevauchent ; /hyperframes-animation gère la chorégraphie du transfert. |
| Transfert split-screen | Gardez les deux clips visuels placés par le core, puis keyframez leurs wrappers internes de crop/masque et la géométrie du séparateur. |
| Retiming constant de la source | /hyperframes-core gère le data-playback-rate normalisé (0.1..10) pour une image sécurisée au rendu et un son préservé en hauteur. Il est constant pour tout l'élément média. |
| Rampes de vitesse de la source | Une piste rate dans data-automation sur le <video>/<audio> (t en secondes de clip, v 0.1..10, interpolation logarithmique) ; elle l'emporte sur le taux constant. |
| Gel / arrêt | Une pose visuelle, une image source finale ou une sous-composition terminée peut tenir. Un gel arbitraire au milieu de la source n'est pas pris en charge ; prétraitez un segment fixe/dérivé, placez-le comme son propre clip, puis reprenez avec une autre plage source. |
Lors de l'édition de l'image et du son ensemble, chargez /hyperframes-core, cette compétence pour le mouvement visuel, et /hyperframes-audio pour les fondus, fondus enchaînés, automation de volume, ducking/carve, ou effets sur les pistes placées.
Un traitement de transition visuelle ou de recadrage n'est pas un rognage ou un épissage temporel de la source. /hyperframes-core gère la timeline, le timing des clips et les plages source ; les keyframes ne font qu'animer le transfert ou le recadrage visible sur les wrappers à l'intérieur de ces clips. Pour des recettes combinées image/son copiables, utilisez /hyperframes-core → references/creator-editing-recipes.md.
Procédure
- Identifiez le sujet animé, les états visibles, l'état final et la durée d'exécution.
- Choisissez le plus petit mécanisme qui prouve l'invite. Lisez
references/keyframe-patterns.mduniquement si le mécanisme n'est pas clair. - Rédigez des keyframes seek-safe dans la durée d'exécution déclarée. N'enregistrez l'instance d'exécution qu'une fois la construction terminée ; la construction à l'intérieur de
document.fonts.readyest acceptable. - Vérifiez avec
hyperframes check(il exécute lint),hyperframes keyframes, un--shotciblé, et des instantanés aux moments de preuve. - Si la preuve échoue, corrigez les keyframes source et relancez le diagnostic le plus petit avant le rendu.
Contrat
- Nommez le sujet en mouvement.
- Nommez les poses nécessaires pour prouver le mouvement prévu, y compris l'état final.
- Keyframez les canaux visibles, pas l'état d'aide cachée.
- Préservez l'identité de l'objet lorsque la continuité compte.
- N'utilisez le fondu enchaîné que lorsque le mouvement prévu est un remplacement ou une dissolution.
- Maintenez les états lisibles ou sémantiques assez longtemps pour être vus.
- L'image finale fait partie de l'animation, pas du nettoyage.
- Ne revenez pas au repos sauf si demandé.
- Ne terminez pas sur du noir sauf si demandé.
- Si vous éditez une scène de départ, préservez la mise en page, la copie, les actifs, les couleurs et l'état final sauf si une refonte est demandée.
Règles d'exécution
GSAP :
- construisez au chargement de la page ou à l'intérieur de
document.fonts.ready, et n'enregistrez qu'après la fin de la construction - utilisez
gsap.timeline({ paused: true }) - enregistrez comme
window.__timelines[compositionId] - la clé d'enregistrement doit correspondre à
data-composition-id - n'appelez pas
tl.play()pour un mouvement critique pour le rendu - gardez les répétitions finies
CSS keyframes :
- durée et nombre d'itérations finis
- délai déterministe
animation-fill-mode: both- utilisez
data-startlorsque le timing appartient à un clip
Anime.js :
- créez de manière synchrone
autoplay: false- durée et boucles finies
- poussez chaque instance vers
window.__hfAnime
WAAPI :
durationfiniefill: "both"- construction déterministe
- la surface de texte ne liste pas WAAPI ; vérifiez avec
--shot(il cherche WAAPI) et les instantanés
N'utilisez jamais pour un mouvement critique pour le rendu :
Date.now()performance.now()Math.random()non ensemencé- déclencheurs de survol/défilement
- minuteries
- une timeline enregistrée avant la fin de sa construction asynchrone
requestAnimationFramenon enregistrée- boucles infinies
Squelette GSAP
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
Utilisez des étiquettes pour les états sémantiques. Utilisez des paramètres de position au lieu de délais chaînés. Utilisez immediateRender: false pour les tweens from()/fromTo() ultérieurs touchant la même propriété.
Formes de keyframes
- Keyframes de tableau : échelle de poses avec durée/easing par étape.
- Keyframes en pourcentage : timing exact à l'intérieur d'un seul tween.
- Tableaux de propriétés : changements multi-arrêts compacts.
ease: "none"sur le parent lorsque chaque arrêt porte son propre easing.easeEachlorsque chaque segment doit partager la même sensation.
Ne copiez pas les distances numériques ou les timings des exemples. Dérivez-les de la géométrie et de la durée réelles de la composition.
Pour un sujet se déplaçant entre deux boîtes, préférez un seul tween de transformation continu ou FLIP. Divisez x/y/scale en plusieurs keyframes avec easing uniquement lorsque le spectateur doit ressentir des battements distincts ; chaque segment change de vélocité et peut être perçu comme un accroc.
Canaux
Préférez les canaux compositeur/visuels : x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masques, vars CSS, valeurs de chemin/dash SVG, transformations de caméra, uniforms de shader.
Évitez les canaux de mise en page/cycle de vie : top/left/right/bottom, width/height, margin/padding, display, visibility, création DOM tardive, superpositions d'aide faisant le mouvement du sujet.
Pour les changements de visibilité, utilisez autoAlpha sur la timeline GSAP seekable enregistrée, ou un tl.set() de durée nulle à une limite explicite. Ciblez uniquement un élément non clip ou un wrapper à l'intérieur du clip ; ne ciblez jamais .clip lui-même. Ne faites jamais de tween de durée sur visibility brut, et ne faites jamais de tween sur display.
Choix du mécanisme
Choisissez le plus petit mécanisme qui prouve l'invite :
| Besoin | Mécanisme |
|---|---|
| Le même sujet change de boîte ou de hiérarchie | élément partagé / FLIP |
| Le sujet parcourt un itinéraire visible | voyage sur chemin |
| Le trait s'allonge ou trace | dessin de trait |
| Une forme en devient une autre | interpolation de forme |
| La limite de révélation est visible | clip, masque, ou uniform de shader |
| Plusieurs éléments bougent avec un ordre | décalage en éventail / indexé |
| Le texte lui-même bouge | subdivision en lignes, mots, caractères ou bandes |
| La surface se plie, s'étire ou recadre | contre-transformation parent/enfant |
| L'interface a des états | machine d'état explicite |
| La scène a de la profondeur | DOM 3D, Three.js, ou keyframes de caméra/objet WebGL |
Les mécanismes peuvent se combiner, mais chacun doit clarifier l'idée. La décoration n'est pas une preuve.
Timing
- Anticipation uniquement lorsqu'elle clarifie la cause ou la direction.
- L'accélération quitte le repos.
- La preuve maximale montre le mécanisme sans équivoque.
- Le suivi vend l'énergie et la direction.
- Le dépassement uniquement lorsque le sujet doit sembler élastique ou tactile.
- Le voyage sur chemin à vitesse constante nécessite généralement
ease: "none". - Les états d'interface discrets nécessitent généralement un ease-out brusque.
- Les éléments répétés nécessitent des décalages ordonnés, pas un timing identique.
- Les blocages finaux nécessitent des poses plus longues que les poses de transition.
- La fluidité signifie une vélocité continue sur le même sujet.
- Ne superposez pas les tweens qui écrivent la même propriété de transformation, sauf si la superposition est intentionnelle et vérifiée.
- Évitez d'animer de grands changements de
clip-path/masque pendant que la même surface héroïque se met également à l'échelle ou se déplace ; utilisez des révélations imbriquées après que le mouvement principal s'est installé.
Texte
Préservez les boîtes de ligne, l'espacement des mots, la lisibilité et l'ajustement final. Si le texte se déplace à l'intérieur, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez un instantané des images lisibles.
SVG
Pour la croissance des traits, préférez DrawSVGPlugin, puis stroke-dasharray/stroke-dashoffset. Pour l'interpolation de forme, préférez MorphSVGPlugin ; convertissez les primitives en chemins si nécessaire et divisez les silhouettes complexes en parties plus simples.
3D
L'échelle seule n'est pas une profondeur réelle. Utilisez la perspective sur un parent stable, transform-style: preserve-3d, voyage en z, rotation, mouvement de caméra/monde, occlusion et ordre des calques lorsque les objets se croisent.
Utilisez un ou deux angles de diagnostic qui exposent la relation de profondeur. Si la preuve angulaire ne montre aucun croisement de profondeur, améliorez le z/caméra/occlusion.
Canvas / WebGL
Keyframez la position de la caméra, la cible de la caméra, la transformation de l'objet, l'opacité du matériau, les uniforms du shader et l'intensité du post-traitement via un état déterministe. Rendez à partir du temps HyperFrames. Utilisez --ghost car les boîtes de marqueur ne peuvent pas voir le mouvement interne du canvas.
Preuve CLI
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<sélecteur>" --shot "<fichier>" --samples <n>
npx hyperframes keyframes . --selector "<sélecteur>" --shot "<fichier>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<fichier>" --ghost --angle <angle>
npx hyperframes snapshot . --at <temps>
Choisissez <sélecteur> pour le vrai sujet animé. Choisissez <temps> pour la première image, les poses de preuve, la dernière image avant la pose finale, et l'image finale exacte. Choisissez <angle> uniquement lorsque la profondeur doit être prouvée.
| Outil | Prouve |
|---|---|
keyframes | cibles, arrêts explicites, chemins, traces, mouvement composé parent/enfant, arrêts CSS, enregistrement Anime |
--shot | fantômes, forme de l'itinéraire, espacement temporel, projection DOM 3D, preuve de sélecteur ciblé |
--layout strip | mouvement sur place, chevauchements, contact, échelle/opacité subtiles, vagues de texte |
--ghost | canvas, WebGL, mouvement de shader, 3D rendu |
snapshot --at | masques, chemins, arrêts nets, états finaux, texte sur plusieurs trames |