Communitygithub.com

KingBridgeSS/sakugacut

Créez des compositions vidéo, des animations, des cartes de titre, des superpositions, des sous-titres, des voix off, des visuels réactifs à l'audio et des transitions de scène dans HyperFrames HTML. À utiliser lors de l'implémentation d'un plan de timeline SakugaCut figé.

Qu'est-ce que sakugacut ?

Cette compétence permet de générer des compositions vidéo complexes directement dans un fichier HTML unique en utilisant le framework HyperFrames, où le HTML est la vérité source de la vidéo. Elle excelle dans la création d'animations fluides grâce à GSAP, la synchronisation des pistes audio, l'ajout de voix off et de sous-titres, et la gestion des transitions de scène. Le processus en trois étapes — Système de design, Expansion de prompt, Planification — garantit que la sortie est cohérente et professionnelle. La compétence insiste sur la construction de l'état final du layout avant tout mouvement ("Layout Before Animation"), évitant ainsi les problèmes de superposition et d'overflow. Elle est optimisée pour Claude Code, Cursor, Codex et d'autres agents IA, et nécessite l'outil `hyperframes-cli` pour l'initialisation et le rendu. Le SKILL.md complet, qui guide strictement l'utilisateur à travers chaque phase, est fourni pour assurer une exécution fiable et prévisible.

Compatible avec~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/KingBridgeSS/sakugacut/tree/HEAD/hyperframes_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

HTML est la source de vérité pour la vidéo. Une composition est un fichier HTML avec des attributs data-* pour le minutage, 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

Découverte (requêtes exploratoires uniquement)

Pour les requêtes ouvertes (« fais-moi une vidéo de lancement de produit », « crée quelque chose pour notre marque ») où l'utilisateur ne s'est pas encore engagé sur une direction, comprendre l'intention avant de choisir les couleurs :

  • Public — qui regarde ça ? Développeurs ? Dirigeants ? Consommateurs grand public ?
  • Plateforme — où est-ce diffusé ? Réseaux sociaux (15s), page d'accueil d'un site web, démo produit, interne ?
  • Priorité — qu'est-ce qui compte le plus ? Qualité du mouvement ? Exactitude du contenu ? Fidélité à la marque ? Rapidité ?
  • Variations — l'utilisateur souhaite-t-il des options, ou une seule meilleure proposition ?

Pour les requêtes spécifiques (« ajoute un carton-titre », « corrige le timing de la scène 3 »), sauter la découverte.

Pour les requêtes exploratoires, envisager de proposer 2-3 variations qui diffèrent significativement — pas seulement un changement de couleurs, mais un rythme, des niveaux d'énergie ou des approches structurelles différents. Une proposition sûre/prévue, une ambitieuse. Ne pas imposer cela — c'est un outil disponible lorsque approprié.

Étape 1 : Système de design

Si design.md ou DESIGN.md existe dans le projet, le lire d'abord (vérifier les deux casse — ce sont des fichiers différents sous Linux). C'est la source de vérité pour les couleurs de la marque, les polices et les contraintes. Utiliser ses valeurs exactes — ne pas inventer de couleurs ni substituer de polices. N'importe quel format fonctionne (frontmatter YAML, prose, tableaux — il suffit d'extraire les valeurs).

S'il nomme des polices que vous ne trouvez pas localement (pas de répertoire fonts/ avec des fichiers .woff2, pas une police intégrée), prévenir l'utilisateur avant d'écrire du HTML : « design.md spécifie la police [nom de la police] mais aucun fichier de police trouvé. Veuillez ajouter des fichiers .woff2 dans fonts/ ou je vais utiliser [alternative intégrée la plus proche]. »

Si aucun design.md n'existe, proposer à l'utilisateur un choix :

  1. L'utilisateur a nommé un style ou une ambiance ? → Lire visual-styles.md pour les 8 préréglages nommés. Choisir la correspondance la plus proche.
  2. Souhaite parcourir les options visuellement ? → Exécuter le sélecteur de design : lire references/design-picker.md pour le workflow complet. Cela sert une page de sélection visuelle. L'utilisateur configure l'ambiance, la palette, la typographie et le mouvement dans le navigateur, puis copie le design.md généré et le colle dans la conversation.
  3. Souhaite ignorer et aller vite ? → Demander : ambiance, clair ou foncé, des couleurs/polices de marque ? Puis choisir une palette depuis house-style.md.

design.md définit la marque. Il ne définit pas les règles de composition vidéo. Celles-ci proviennent de references/video-composition.md et de house-style.md. Utiliser les couleurs de la marque à une échelle appropriée à la vidéo — pas à l'opacité d'une interface web.

Étape 2 : Expansion du prompt

Toujours exécuter sur chaque composition (sauf pour les pièces à scène unique et les modifications triviales). Cette étape ancre l'intention de l'utilisateur par rapport à design.md et house-style.md et produit un intermédiaire cohérent que chaque agent en aval lit de la même manière.

Lire references/prompt-expansion.md pour le processus complet et le format de sortie.

Étape 3 : Planification

Avant d'écrire du HTML, réfléchir à un niveau élevé :

  1. Quoi — que doit ressentir le spectateur ? Identifier l'arc narratif, les moments clés et les temps forts émotionnels.
  2. Structure — combien de compositions, lesquelles sont des sous-compositions ou en ligne, quelles pistes transportent quoi (vidéo, audio, superpositions, sous-titres).
  3. Rythme — déclarer son rythme de scène avant l'implémentation. Quelles scènes sont des impacts rapides, lesquelles sont des pauses, où les shaders atterrissent-ils, où l'énergie culmine. Nommer le motif : rapide-rapide-LENT-rapide-SHADER-pause. Lire references/beat-direction.md pour les modèles de rythme.
  4. Timing — quels clips déterminent la durée, où les transitions se situent, quel est le rythme.
  5. Disposition — construire l'état final d'abord. Voir « Disposition avant l'Animation » ci-dessous.
  6. Animer — puis ajouter du mouvement en utilisant les règles ci-dessous.

Construire ce qui a été demandé. Une demande pour « un carton-titre » n'est pas une demande pour « un carton-titre + 3 scènes de soutien + musique d'ambiance + sous-titres. » Chaque scène, chaque élément, chaque interpolation doit mériter sa place. Si des scènes ou éléments supplémentaires amélioreraient vraiment la pièce, les proposer — ne pas les ajouter.

Pour les petites modifications (corriger une couleur, ajuster le timing, ajouter un élément), passer directement aux règles.

Disposition avant l'Animation

Positionner chaque élément là où il devrait être à son moment le plus visible — l'image où il est complètement entré, correctement placé, et pas encore en train de sortir. Écrire cela d'abord 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 que vous les animez vers l'endroit 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 l'état final en premier, vous pouvez voir et corriger les problèmes de disposition avant d'ajouter du mouvement.

Le processus

  1. Identifier 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.
  2. Écrire du CSS statique pour cette image. Le conteneur .scene-content DOIT remplir toute la scène en utilisant width: 100%; height: 100%; padding: Npx; avec display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Utiliser le padding pour pousser le contenu vers l'intérieur — NE JAMAIS utiliser position: absolute; top: Npx sur 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éserver position: absolute uniquement pour les éléments décoratifs.
  3. Ajouter les entrées avec gsap.from() — animer DEPUIS l'état hors écran/invisible VERS la position CSS. La position CSS est la vérité de base ; l'interpolation décrit le chemin pour y arriver. (Dans les sous-compositions chargées via data-composition-src, préférer gsap.fromTo() — voir les règles GSAP structurantes dans references/motion-principles.md.)
  4. Ajouter les sorties avec gsap.to() — animer VERS l'état 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. */

FAUX — 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);

Lorsque les é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 superposés (lueur derrière le texte, éléments d'ombre, motifs d'arrière-plan) et les designs empilés en 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 couvrant une étiquette, un contenu débordant du cadre.

Attributs de Données

Tous les Clips

AttributRequisValeurs
idOuiIdentifiant unique
data-startOuiSecondes ou référence d'ID de clip ("el-1", "intro + 2")
data-durationRequis pour img/div/compositionsSecondes. La vidéo/audio prend la durée du média par défaut.
data-track-indexOuiEntier. Les clips de même piste ne peuvent pas se chevaucher.
data-media-startNonDécalage de coupe dans la source (secondes)
data-volumeNon0-1 (par défaut 1)

data-track-index n'affecte pas la superposition visuelle — utiliser CSS z-index.

Clips de Composition

AttributRequisValeurs
data-composition-idOuiID de composition unique
data-startOuiHeure de début (composition racine : utiliser "0")
data-durationOuiRemplace la durée de la timeline GSAP
data-width / data-heightOuiDimensions en pixels (1920x1080 ou 1080x1920)
data-composition-srcNonChemin vers un fichier HTML externe
data-variable-valuesNonObjet JSON des remplacements de variables par instance sur un hôte de sous-comp

Sur l'élément racine <html> :

AttributRequisValeurs
data-composition-variablesNonTableau JSON des variables déclarées (id/type/label/default) — pilote l'interface d'édition Studio et fournit les valeurs par défaut pour getVariables()

Structure de Composition

Les sous-compositions chargées via data-composition-src utilisent un wrapper <template>. Les compositions autonomes (le fichier 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="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- contenu -->
    <style>
      [data-composition-id="my-comp"] {
        /* styles limités à ce composant */
      }
    </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["my-comp"] = tl;
    </script>
  </div>
</template>

Chargement dans la racine : <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

Variables (Compositions Paramétrées)

Rendre la même composition avec un contenu différent — titre, couleur de thème, prix, sous-titres — sans modifier le code HTML source.

Modèle en trois étapes :

  1. Déclarer les variables sur la racine <html> de la composition avec data-composition-variables. Chaque entrée nécessite id, type (parmi string, number, color, boolean, enum), label, et default. Les entrées Enum ont également besoin de options: [{value, label}, ...].
  2. Lire les valeurs résolues dans le script de la composition avec window.__hyperframes.getVariables(). Renvoie le résultat fusionné des valeurs par défaut déclarées + des remplacements par instance + des remplacements CLI.
  3. Remplacer au moment du rendu avec npx hyperframes render --variables '{...}' (niveau supérieur) ou avec data-variable-values='{...}' sur l'élément hôte (par instance pour les sous-composants).
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Titre","default":"Bonjour"},
  {"id":"theme","type":"enum","label":"Thème","default":"light","options":[
    {"value":"light","label":"Clair"},
    {"value":"dark","label":"Foncé"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>
# L'aperçu de développement utilise les valeurs par défaut déclarées
npx hyperframes preview

# Rendu avec des remplacements
npx hyperframes render --variables '{"title":"Rapport Q4","theme":"dark"}' --output q4.mp4

# Ou depuis un fichier JSON
npx hyperframes render --variables-file ./vars.json

Valeurs par instance de sous-composition : le même getVariables() fonctionne à l'intérieur des sous-composants chargés via data-composition-src. Chaque élément hôte passe ses propres valeurs :

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Pro","price":"29€"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"


…

[version tronquée pour la traduction]

Skills associés