Communitygithub.com

LingoJack/jcli

Créez des compositions vidéo, animations, cartes-titres, incrustations, légendes, voix off, visuels réactifs à l'audio et transitions de scènes en HyperFrames HTML. Utilisez cette compétence lorsqu'on vous demande de construire tout contenu vidéo en HTML, d'ajouter des légendes ou sous-titres synchronisés avec l'audio, de générer une narration par synthèse vocale, de créer une animation réactive à l'audio (synchronisation au rythme, lueur, pulsation entraînée par la musique), d'ajouter un surlignage de texte animé (balayages de marqueur, cercles dessinés à la main, lignes d'éclatement, gribouillis, esquisse) ou d'ajouter des transitions entre les scènes (fondus, volets, révélations, transitions shader). Couvre la création de compositions, le timing, le support multimédia et l'ensemble du workflow de production vidéo. Pour les commandes CLI du cycle de développement (init, lint, inspect, preview, render), voir la compétence hyperframes-cli ; pour les commandes de prétraitement des ressources (tts, transcribe, remove-background), voir la compétence hyperframes-media.

Qu'est-ce que jcli ?

Cette compétence pour agents IA (LingoJack/jcli) vous permet de créer et de manipuler des compositions vidéo complètes en utilisant HyperFrames, un framework où le HTML est la source de vérité unique pour la vidéo. L'agent peut générer des animations, des cartes-titres, des incrustations, des légendes synchronisées avec l'audio, des voix off text-to-speech, des visuels réactifs au rythme de la musique, du surlignage de texte animé et des transitions de scènes sophistiquées. Le workflow est structuré en étapes claires : découverte (pour les demandes exploratoires), configuration du système de design (à partir de design.md ou de choix utilisateur), expansion du prompt, planification (structure, rythme, timing et mise en page), et animation. L'agent suit des règles strictes de mise en page (positionnement des éléments à leur état final visible avant d'ajouter des animations), utilise des attributs de données pour le timing et les pistes, et prend en charge les compositions paramétrées pour une réutilisation flexible du contenu. La compétence est conçue pour fonctionner sur les plateformes d'agents IA comme Cursor, Claude Code ou Codex, et nécessite la présence d'autres compétences (hyperframes-cli, hyperframes-media) pour les commandes CLI et de prétraitement.

Compatible avec~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/LingoJack/jcli/tree/HEAD/.jcli/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 des 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 de la timeline.

Approche

Découverte (demandes exploratoires uniquement)

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

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

Pour les demandes spécifiques ("ajoute une carte-titre", "corrige le timing de la scène 3"), sautez la découverte.

Pour les demandes exploratoires, envisagez de proposer 2 à 3 variations qui diffèrent significativement — pas seulement des changements de couleur, mais des rythmes, niveaux d'énergie ou approches structurelles différents. Une option sûre/attendue, une ambitieuse. N'imposez pas cela — c'est un outil disponible quand il est approprié.

Étape 1 : Système de design

Si design.md ou DESIGN.md existe dans le projet, lisez-le d'abord (vérifiez les deux casses — 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. Utilisez ses valeurs exactes — n'inventez pas de couleurs et ne substituez pas de polices. Tout format fonctionne (frontmatter YAML, prose, tableaux — extrayez simplement 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), avertissez l'utilisateur avant d'écrire du HTML : "design.md spécifie [nom de la police] mais aucun fichier de police trouvé. Veuillez ajouter des fichiers .woff2 à fonts/ ou je reviendrai à [l'alternative intégrée la plus proche]."

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

  1. L'utilisateur a nommé un style ou une ambiance ? → Lisez visual-styles.md pour les 8 préréglages nommés. Choisissez la correspondance la plus proche.
  2. Vous voulez parcourir les options visuellement ? → Lancez le sélecteur de design : lisez references/design-picker.md pour le workflow complet. Cela sert une page sélecteur 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. Vous voulez ignorer et aller vite ? → Demandez : ambiance, clair ou sombre, des couleurs/polices de marque ? Ensuite, choisissez une palette dans 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. Utilisez les couleurs de la marque à une échelle adaptée à la vidéo — pas à l'opacité d'une interface web.

Étape 2 : Expansion du prompt

Toujours exécuter sur chaque composition (sauf 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 tous les agents en aval lisent de la même manière.

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

Étape 3 : Planification

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

  1. Quoi — que devrait vivre le spectateur ? Identifiez l'arc narratif, les moments clés et les battements émotionnels.
  2. Structure — combien de compositions, lesquelles sont des sous-compositions vs en ligne, quelles pistes transportent quoi (vidéo, audio, incrustations, légendes).
  3. Rythme — déclarez votre rythme de scène avant de l'implémenter. Quelles scènes sont des frappes rapides, lesquelles sont des poses, où atterrissent les shaders, où l'énergie culmine. Nommez le motif : rapide-rapide-LENTE-rapide-SHADER-pause. Lisez references/beat-direction.md pour les modèles de rythme.
  4. Timing — quels clips déterminent la durée, où atterrissent les transitions, quel est le rythme.
  5. Mise en page — construisez d'abord l'état final. Voir "Mise en page avant animation" ci-dessous.
  6. Animer — puis ajoutez du mouvement en utilisant les règles ci-dessous.

Construisez ce qui a été demandé. Une demande pour "une carte-titre" n'est pas une demande pour "une carte-titre + 3 scènes de soutien + musique d'ambiance + légendes." Chaque scène, chaque élément, chaque interpolation doit mériter sa place. Si des scènes ou éléments supplémentaires amélioreraient véritablement la pièce, proposez-les — ne les ajoutez pas.

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

Mise en page avant animation

Positionnez chaque élément là où il doit être à son moment le plus visible — l'image où il est complètement entré, correctement placé et pas encore en train de sortir. Écrivez 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 jusqu'à où vous pensez qu'ils devraient atterrir, vous devinez la mise en page 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 mise en page avant d'ajouter du mouvement.

Le processus

  1. Identifiez l'image héroïque pour chaque scène — le moment où le plus d'éléments sont simultanément visibles. C'est la mise en page que vous construisez.
  2. Écrivez du CSS statique pour cette image. Le conteneur .scene-content DOIT remplir la scène entière en utilisant width: 100%; height: 100%; padding: Npx; avec display: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Utilisez le padding pour pousser le contenu vers l'intérieur — JAMAIS position: absolute; top: Npx sur un conteneur de contenu. Les conteneurs de contenu positionnés en absolu débordent lorsque le contenu est plus grand que l'espace restant. Réservez position: absolute uniquement pour les éléments décoratifs.
  3. Ajoutez les entrées avec gsap.from() — animez DEPUIS hors écran/invisible VERS la position CSS. La position CSS est la vérité de base ; l'interpolation décrit le voyage pour y arriver. (Dans les sous-compositions chargées via data-composition-src, préférez gsap.fromTo() — voir les règles GSAP importantes dans references/motion-principles.md.)
  4. Ajoutez les sorties avec gsap.to() — animez VERS 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. */

MAUVAIS — 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 des éléments partagent 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 mise en page, vous ne détecterez pas le cas où ils se chevauchent accidentellement en raison d'une erreur de timing.

Ce qui est considéré comme un chevauchement intentionnel

Les effets en couches (lueur derrière le texte, éléments d'ombre, motifs d'arrière-plan) et les conceptions empilées en z (piles de cartes, couches de profondeur) sont intentionnels. L'étape de mise en page consiste à détecter les chevauchements non intentionnels — deux titres atterrissant l'un sur l'autre, une statistique recouvrant 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 par défaut correspond à la durée du média.
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 — utilisez CSS z-index.

Clips de composition

AttributRequisValeurs
data-composition-idOuiID de composition unique
data-startOuiHeure de début (composition racine : utilisez "0")
data-durationOuiPrioritaire sur 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 une enveloppe <template>. Les compositions autonomes (le fichier principal index.html) n'utilisent PAS <template> — elles placent directement la div data-composition-id dans <body>. L'utilisation de <template> sur un fichier autonome cache tout le contenu au navigateur et interrompt le rendu.

Structure de sous-composition :

<template id="ma-comp-template">
  <div data-composition-id="ma-comp" data-width="1920" data-height="1080">
    <!-- contenu -->
    <style>
      [data-composition-id="ma-comp"] {
        /* styles limités à cette portée */
      }
    </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["ma-comp"] = tl;
    </script>
  </div>
</template>

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

Variables (compositions paramétrées)

Rendez la même composition avec un contenu différent — titre, couleur de thème, prix, légendes — sans modifier le HTML source.

Modèle en trois étapes :

  1. Déclarez les variables sur la racine <html> de la composition avec data-composition-variables. Chaque entrée nécessite id, type (un de string, number, color, boolean, enum), label et default. Les entrées enum ont également besoin de options: [{value, label}, ...].
  2. Lisez les valeurs résolues dans le script de la composition avec window.__hyperframes.getVariables(). Retourne le résultat fusionné des valeurs par défaut déclarées + des remplacements par instance + des remplacements CLI.
  3. Remplacez 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-comps).
<!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":"Sombre"}
  ]}
]'
>
  <body>
    <div data-composition-id="racine" 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 remplacements
npx hyperframes render --variables '{"title":"Rapport Q4","theme":"dark"}' --output q4.mp4

# Ou à partir d'un fichier JSON
npx hyperframes render --variables-file ./vars.json

Valeurs par instance de sous-composition : le même getVariables() fonctionne dans les sous-comps chargées via data-composition-src. Chaque élément hôte passe ses propres valeurs :

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

Interpolation des pistes audio avec GSAP

Créez des pistes de base de groove, des beats d'accentuation, des fondus de sous-trames et des builds avec gsap.timeline() et des clips audio. Les clips audio dans HyperFrames utilisent les mêmes attributs de données que les clips visuels (data-start, data-duration, data-track-index).

const audioTl = gsap.timeline({ paused: true });

// Piste de groove — lent et large
audioTl.to(".audio-groove", { volume: 0.8, duration: 4, ease: "sine.inOut" }, 0);
audioTl.to(".audio-groove", { volume: 0.4, duration: 2, ease: "sine.inOut" }, 4);

// Piste d'accentuation — frappes rapides
audioTl.to(".audio-accent", { volume: 1, duration: 0.5, ease: "power2.out" }, 1);
audioTl.to(".audio-accent", { volume: 0, duration: 0.3, ease: "power2.in" }, 1.5);

// Enregistrer dans le gestionnaire de timeline HyperFrames
window.__timelines["audio-sequences"] = audioTl;

Utilisez le séquencement audio pour créer des paysages sonores dynamiques qui réagissent au contenu visuel ou qui conduisent indépendamment le rythme.

Résumé des clips et des attributs de données

Référez-vous à references/video-composition.md pour la spécification complète des types de clips et des attributs.

Types de clips

  • El : Élément div — utile pour les conteneurs, les mises en page et les espaces réservés
  • Img : Image — prend en charge les formats PNG, JPEG, WebP, SVG, GIF
  • Video : Fichier vidéo — prend en charge MP4, WebM, MOV
  • Audio : Fichier audio — prend en charge MP3, WAV, OGG, AAC, M4A
  • Comp : Composition — permet d'imbriquer des compositions
  • Timer : Chronomètre — suit le temps écoulé dans la composition
  • Overlay : Calque d'incrustation — un calque graphique superposé à la vidéo
  • Text : Texte — ajoute du texte à la vidéo
  • CaptionTrack : Piste de légendes — chargée à partir d'un fichier de sous-titres (SRT, VTT, ASS, SBV, JSON)
  • Shape : Forme — un élément de forme vectorielle (cercle, rectangle, polygone)

Attributs de données standard pour tous les clips

AttributDescriptionRequis
idIdentifiant uniqueOui
data-startHeure de début dans la composition (secondes)Oui
data-durationDurée du clip (secondes)Oui
data-track-indexIndex de piste pour éviter les chevauchementsOui
data-media-startDécalage temporel dans le média sourceNon
data-volumeVolume (0 à 1, par défaut 1)Non

Skills associés