Communitygithub.com

scott-fryxell/brayness

Créez des compositions vidéo, animations, cartes-titres, incrustations, sous-titres, voix off, visuels réactifs à l'audio et transitions de scènes en HTML HyperFrames.

Qu'est-ce que brayness ?

Cette compétence permet aux agents IA (Claude Code, Cursor, etc.) de créer, modifier et gérer des compositions vidéo à l'aide du framework HyperFrames, où le HTML est la source de vérité pour la vidéo. Une composition est un fichier HTML enrichi d'attributs `data-*` pour le timing, d'une timeline GSAP pour l'animation et de CSS pour l'apparence. Le framework prend en charge la visibilité des clips, la lecture multimédia et la synchronisation temporelle. L'agent suit un pipeline en trois étapes : découverte et système de design (à partir d'un fichier design.md ou d'une sélection visuelle), expansion du prompt, puis planification détaillée (récit, structure, rythme, timing, mise en page avant animation). La règle clé est de construire d'abord la mise en page statique (l'état final le plus visible) avant d'ajouter toute animation GSAP. Des règles strictes garantissent un fonctionnement déterministe : pas de `Math.random()`, aucune construction asynchrone de timeline, des transitions obligatoires entre chaque scène (sans coupure), et une vérification de conformité via `npx hyperframes lint` et `npx hyperframes validate`. La compétence référence une multitude de guides spécialisés (typographie, motion design, transitions, sous-titres, audio-réactivité, etc.) pour couvrir tous les cas d'usage : cartes-titres, voice-over TTS, slides, infographies, et plus encore.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scott-fryxell/brayness/tree/HEAD/skills/hyperframes

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. L'utilisateur a nommé un style ou une ambiance ? Lisez styles-visuels.md (8 préréglages nommés), choisissez le plus proche.
  2. Parcourir visuellement ? Lancez le sélecteur de design - références/sélecteur-design.md.
  3. 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

  1. Quoi - arc narratif, moments clés, émotions.
  2. Structure - combien de compositions, sous-compositions vs en ligne, quelles pistes portent quoi.
  3. 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.
  4. Timing - quels clips déterminent la durée, où tombent les transitions.
  5. Mise en page - construisez d'abord l'état final (section suivante).
  6. 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.

  1. 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.
  2. Écrivez le CSS statique pour cela. .scene-content DOIT remplir la scène : width: 100%; height: 100%; padding: Npx; avec display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Le padding pousse le contenu vers l'intérieur - JAMAIS position: absolute; top: Npx sur un conteneur de contenu (cela déborde quand le contenu grandit). Réservez le positionnement absolu pour les éléments décoratifs.
  3. 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 via data-composition-src : préférez gsap.fromTo() - voir références/principes-mouvement.md.)
  4. 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 :

  1. Oublier l'enregistrement window.__timelines
  2. Utiliser une vidéo pour l'audio - toujours vidéo muette + <audio> séparé
  3. Imbriquer une vidéo dans une div temporisée - utilisez un wrapper non temporisé
  4. Utiliser data-layer (utilisez data-track-index) ou data-end (utilisez data-duration)
  5. Animer les dimensions d'un élément vidéo - animez une div wrapper
  6. Appeler play/pause/seek sur le média - le framework possède la lecture
  7. Créer un conteneur de niveau supérieur sans data-composition-id
  8. Utiliser repeat: -1 sur une timeline ou une interpolation
  9. Construire des timelines de manière asynchrone
  10. 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 tl.set(selecteur, vars, positionTemporelle) à ou après le data-start du clip.
  11. Utiliser <br> dans le texte de contenu - il s'empile avec l'habillage naturel et provoque des chevauchements ; utilisez max-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.

  1. Utilisez TOUJOURS des transitions entre les scènes. Pas de coupures brusques.
  2. 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.
  3. 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.
  4. 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-nums sur 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 lint et npx hyperframes validate ré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 inspect ré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 :

FichierCouvre
références/authoring.mdattributs data, structure de template, variables, vidéo/audio, polices/ressources
références/composition-vidéo.mdrègles du média vidéo - celles-ci remplacent les instincts web
références/typographie.mdappariement de polices, OpenType, ajustements fond sombre
références/principes-mouvement.mddesign de mouvement, mouvement d'image, règles GSAP porteuses

À lire aussi toujours pour les compositions multi-scènes :

FichierCouvre
références/direction-rythme.mdtemplates de rythme, verbes de chorégraphie, couches de profondeur
références/transitions.mdsé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 :

FichierLire quand
références/vérifications-qualité.mdexécution des vérifications inspect/contraste/design/animation-map
références/cli.mdtoute commande CLI ; dépannage build/rendu
références/sous-titres.mdtout texte synchronisé avec le timing audio
références/guide-transcription.mdgestion de transcription côté sous-titres (l'invocation CLI vit dans media.md)
références/techniques-dynamiques.mdanimation dynamique de sous-titres (karaoké, slam, dispersion)
références/audio-reactif.mdvisuels répondant à la musique/voix
références/patterns-css.mdsurbrillance de marqueur (surlignage, cercle, éclat, gribouillage)
références/techniques.mdtechniques de planification par rythme (11 motifs avec code)
références/narration.mdrythme voix off/TTS et structure de script
références/media.mdTTS (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.mdcréation visuelle d'un design.md
références/depuis-site-web.mdtransformer un site web en vidéo
références/registre.mdinstallation/contribution de blocs de registre (hyperframes add)
styles-visuels.mdl'utilisateur nomme un style ; génération de design.md
style-maison.mdvaleurs esthétiques par défaut quand aucun design.md
patterns.mdPiP, cartes-titres, diaporamas
donnees-en-mouvement.mddonné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.

Skills associés