heygen-com/hyperframes

Installation des plugins : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution des plugins lorsque ce skill se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.

Keyframes HyperFrames

Les keyframes sont un contrat de poses : états visibles, identité continue du sujet, exécution fiable en seek, 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 franches sur la source, le rognage, l'épissage et le réordonnancement appartiennent à /hyperframes-core : créez 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. Des plages adjacentes créent une coupure franche. Un fondu enchaîné utilise des clips superposés 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 x/y ou translation en pourcentage sur un wrapper visuel/recadrage non temporel à l'intérieur du clip. Utilisez un tween court pour un punch sec et un tween pour un mouvement fluide.
Zoom ou reframe fluide multi-état	Gardez un wrapper de sujet vivant et créez plusieurs états de zoom/reframe comme une échelle de poses avec un easing par segment.
Panoramique, reframe ou effet Ken Burns	Animer la translation du wrapper plus le scale. La géométrie est créée manuellement ; ce n'est pas un suivi de visage ni un recadrage sémantique automatique.
Mouvements de caméra enchaînés	Enchaînez des transformations étiquetées sur une timeline unique enregistrée et compatible seek.
Cut match ou whip pan	/hyperframes-animation gère la transition visuelle ; /hyperframes-registry fournit les primitives ; les keyframes préservent la géométrie, la direction et la vélocité créées. Il n'y a pas de découverte automatique de cadre correspondant.
Recadrage et reframe par masque	Interpolez clip-path ou un masque sur un wrapper visuel interne pour recadrer/reframer sans changer le temps source. Les keyframes polygonales peuvent former une transition polygone/masque.
Cut par volet directionnel ou iris/révélation	Animez une limite de masque/clip à travers des clips visuels superposés ; /hyperframes-animation gère la chorégraphie de transition.
Transition split-screen	Gardez les deux clips visuels placés par core, puis keyframez leurs wrappers de recadrage/masque internes et la géométrie de séparation.
Retiming constant de source	/hyperframes-core gère data-playback-rate normalisé (0.1..10) pour une image sécurisée au rendu et un son préservant la hauteur. Il est constant pour tout l'élément média.
Rampes de vitesse source	Une piste rate dans data-automation sur <video>/<audio> (t en secondes de clip, v 0.1..10, interpolation log) ; elle prime sur le taux constant.
Freeze / arrêt sur image	Une pose visuelle, une image source finale ou une sous-composition terminée peut rester figée. Un freeze arbitraire au milieu de la source n'est pas pris en charge ; prétraitez un segment figé/dérivé, placez-le comme son propre clip, puis reprenez avec une autre plage source.

Lorsque vous éditez l'image et le son ensemble, chargez /hyperframes-core, ce skill pour le mouvement visuel, et /hyperframes-audio pour les fondus, fondus enchaînés, automations 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 la transition visible ou le recadrage 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

1. Identifiez le sujet animé, les états visibles, l'état final et la durée d'exécution.
2. Choisissez le plus petit mécanisme qui prouve la demande. Lisez references/keyframe-patterns.md uniquement si le mécanisme n'est pas clair.
3. Créez des keyframes compatibles seek dans la durée déclarée. Construisez de manière synchrone et enregistrez l'instance d'exécution.
4. Vérifiez avec hyperframes lint, hyperframes check, hyperframes keyframes, un --shot ciblé, et des instantanés aux temps de preuve.
5. Si la preuve échoue, corrigez les keyframes source et relancez le plus petit diagnostic en échec avant de rendre.

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 les états cachés d'assistance.
• Préservez l'identité de l'objet lorsque la continuité est importante.
• Faites un fondu enchaîné uniquement lorsque le mouvement prévu est un remplacement ou une dissolution.
• Maintenez les états lisibles ou sémantiques assez longtemps pour être vus.
• La dernière image fait partie de l'animation, pas du nettoyage.
• Ne revenez pas à l'état de 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, les copies, les ressources, les couleurs et l'état final sauf si une refonte est demandée.

Règles d'exécution

GSAP :

• construisez de manière synchrone au chargement de la page
• utilisez gsap.timeline({ paused: true })
• enregistrez comme window.__timelines[compositionId]
• la clé de registre doit correspondre à data-composition-id
• n'appelez pas tl.play() pour le mouvement critique pour le rendu
• gardez les répétitions finies

Keyframes CSS :

• durée limitée et nombre d'itérations
• délai déterministe
• animation-fill-mode: both
• utilisez data-start lorsque le timing appartient à un clip

Anime.js :

• créez de manière synchrone
• autoplay: false
• durée et boucles limitées
• poussez chaque instance vers window.__hfAnime

WAAPI :

• duration limitée
• fill: "both"
• construction déterministe
• la surface texte ne liste pas WAAPI ; vérifiez avec --shot (il cherche WAAPI) et les instantanés

N'utilisez jamais pour le mouvement critique pour le rendu :

• Date.now()
• performance.now()
• Math.random() non ensemencé
• déclencheurs hover/scroll
• timers
• timelines créées de manière asynchrone
• requestAnimationFrame non enregistré
• 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 en 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 compacts multi-arrêts.
• ease: "none" sur le parent lorsque chaque étape porte son propre easing.
• easeEach lorsque 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 transform continu ou FLIP. Divisez les x/y/scale en plusieurs keyframes avec easing uniquement lorsque le spectateur doit ressentir des étapes distinctes ; chaque segment change de vélocité et peut être perçu comme un à-coup.

Canaux

Privilégiez les canaux du compositeur/visuels : x/y/z, xPercent/yPercent, scale, rotationX/Y/Z, skew, transformOrigin, svgOrigin, opacity, autoAlpha, clip-path, masques, variables CSS, valeurs SVG path/dash, transformations de caméra, uniforms shader.

Évitez les canaux de mise en page/cycle de vie : top/left/right/bottom, width/height, margin/padding, display, visibility, création tardive du DOM, overlays d'assistance effectuant le mouvement du sujet.

Pour les changements de visibilité, utilisez autoAlpha sur la timeline GSAP enregistrée et compatible seek, 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 temporel sur la visibility brute, et ne faites jamais de tween sur display.

Choix du mécanisme

Choisissez le plus petit mécanisme qui prouve la demande :

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 (path travel)
Un trait s'allonge ou trace	dessin de trait (stroke draw)
Une forme se transforme en une autre	interpolation de forme (shape interpolation)
La limite de révélation est visible	clip, masque ou uniform shader
Plusieurs éléments bougent avec un ordre	stagger / délai indexé
Le texte lui-même bouge	subdivision de ligne, mot, caractère ou bande
La surface se plie, s'étire ou se recadre	contre-transformation parent/enfant
L'interface a des états	machine à états 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

• L'anticipation uniquement lorsqu'elle clarifie la cause ou la direction.
• L'accélération quitte le repos.
• La preuve maximale montre le mécanisme de manière indubitable.
• Le suivi (follow-through) vend l'énergie et la direction.
• Le dépassement (overshoot) uniquement lorsque le sujet doit sembler élastique ou tactile.
• Un voyage à vitesse constante sur un chemin nécessite généralement ease: "none".
• Les états d'interface discrets nécessitent généralement un ease-out prononcé.
• Les éléments répétés ont besoin de décalages ordonnés, pas d'un timing identique.
• Les verrouillages finaux nécessitent des durées 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 le chevauchement est intentionnel et vérifié.
• Évitez d'animer de grands changements de clip-path/masque pendant que la même surface héroïque est également en train de se redimensionner ou de se déplacer ; utilisez des révélations imbriquées après que le mouvement principal se soit stabilisé.

Texte

Préservez les boîtes de ligne, l'espacement des mots, la lisibilité et l'ajustement final. Si le texte se déplace en interne, déplacez les glyphes ou les bandes masquées, pas seulement les décorations autour du texte. Prenez des instantanés des images lisibles.

SVG

Pour la croissance d'un trait, 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

Le scale seul est une fausse profondeur. Utilisez la perspective sur un parent stable, transform-style: preserve-3d, le déplacement en z, la rotation, le mouvement caméra/monde, l'occlusion et l'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 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 lint
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 véritable sujet animé. Choisissez <temps> pour la première image, les poses de preuve, la finale avant maintien, et la 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, scale/opacité subtils, vagues de texte
--ghost	canvas, WebGL, mouvement shader, 3D rendu
snapshot --at	masques, lisibilité du texte, état complet, verrouillage final, queues noires/repos

Si la preuve par sélecteur semble étrange pour le mouvement ciblé, elle est soit excessive soit mal ciblée. Ajustez le sélecteur pour cibler le sujet mobile réel.