ZardLi1115/zedclaw

HyperFrames

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 moteur HyperFrames capture la page image par image et encode en MP4/WebM avec FFmpeg.

Complémentaire de manim-video : Utilisez manim-video pour les explications mathématiques/géométriques (équations, style 3B1B). Utilisez hyperframes pour les graphiques animés, les vidéos tête parlante avec sous-titres, les visites guidées de produits, les superpositions sociales, les transitions avec shaders et tout ce qui est piloté par des médias vidéo/audio réels.

Quand l'utiliser

• L'utilisateur demande une vidéo rendue à partir de texte, d'un script ou d'un site web
• Cartes titres animées, tiers inférieurs ou intros typographiques
• Vidéo de narration avec sous-titres (TTS + sous-titres synchronisés avec la forme d'onde)
• Visuels réactifs à l'audio (syncope de rythme, barres de spectre, lueur pulsée)
• Transitions de scène à scène (fondu, balayage, déformation shader, flash à travers le blanc)
• Superpositions sociales (style Instagram/TikTok/YouTube)
• Pipeline site web vers vidéo (capturer une URL, produire une promotion)
• Toute animation HTML/CSS/JS qui doit être rendue de manière déterministe dans un fichier vidéo

N'utilisez pas cette compétence pour :

• Les animations mathématiques/équations pures (→ manim-video)
• La génération d'images ou les mèmes (→ meme-generation, modèles d'images)
• La visioconférence ou le streaming en direct

Référence rapide

npx hyperframes init my-video               # créer un projet
cd my-video
npx hyperframes lint                        # valider avant l'aperçu/le rendu
npx hyperframes preview                     # aperçu en direct dans le navigateur (port 3002)
 npx hyperframes render --output final.mp4   # rendu en MP4
npx hyperframes doctor                      # diagnostiquer les problèmes d'environnement

Indicateurs de rendu : --quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker (reproductible) · --strict.

Référence complète de la CLI : references/cli.md.

Configuration (une fois)

bash "$(dirname "$(find ~/.zedclaw/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

Le script :

1. Vérifie que Node.js >= 22 et FFmpeg sont installés (affiche les instructions de correction si non).
2. Installe la CLI hyperframes globalement (npm install -g hyperframes@>=0.4.2).
3. Pré-met en cache chrome-headless-shell via Puppeteer — requis pour un rendu de meilleure qualité via le chemin de capture HeadlessExperimental.beginFrame de Chrome.
4. Exécute npx hyperframes doctor et rapporte le résultat.

Consultez references/troubleshooting.md si la configuration échoue.

Procédure

1. Planifier avant d'écrire le HTML

Avant de toucher au code, articulez à un niveau élevé :

• Quoi — arc narratif, moments clés, ressorts émotionnels
• Structure — compositions, pistes (vidéo/audio/superpositions), durées
• Identité visuelle — couleurs, polices, caractère du mouvement (explosif / cinématique / fluide / technique)
• Image clé — pour chaque scène, le moment où le plus d'éléments sont visibles simultanément. C'est la mise en page statique que vous construirez en premier.

Porte d'identité visuelle (HARD-GATE). Avant d'écrire QUELQUE composition HTML que ce soit, une identité visuelle doit être définie. N'écrivez PAS de compositions avec des couleurs par défaut ou génériques (#333, #3b82f6, Roboto sont des signes que cette étape a été ignorée). Vérifiez dans l'ordre :

1. DESIGN.md à la racine du projet ? → Utilisez ses couleurs, polices, règles de mouvement et contraintes "Quoi ne PAS faire" exactes.

2. L'utilisateur a nommé un style (par exemple "Swiss Pulse", "dark and techy", "marque de luxe") ? → Générez un DESIGN.md minimal avec ## Style Prompt, ## Colors (3-5 hex avec rôles), ## Typography (1-2 familles), ## What NOT to Do (3-5 anti-patrons).

3. Rien de ce qui précède ? → Posez 3 questions avant d'écrire du HTML :

   • Ambiance ? (explosif / cinématique / fluide / technique / chaotique / chaleureux)
   • Toile claire ou foncée ?
   • Des couleurs de marque, polices ou références visuelles ?

   Générez ensuite un DESIGN.md à partir des réponses. Chaque composition doit retracer sa palette et sa typographie jusqu'à DESIGN.md ou une direction explicite de l'utilisateur.

2. Créer le squelette

npx hyperframes init my-video --non-interactive

Modèles : blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph. Passez --example <nom> pour en choisir un, --video clip.mp4 ou --audio track.mp3 pour l'amorcer avec des médias.

3. Disposition avant animation

Écrivez d'abord le HTML+CSS statique pour l'image clé — pas encore de GSAP. Le conteneur .scene-content doit remplir la scène (width:100%; height:100%; padding:Npx) avec display:flex + gap. Utilisez le remplissage (padding) pour pousser le contenu vers l'intérieur — jamais position: absolute; top: Npx sur un conteneur de contenu (le contenu déborde quand il est plus grand que l'espace restant).

Ce n'est qu'après que l'image clé a l'air correcte, ajoutez des entrées gsap.from() (animez vers la position CSS) et des sorties gsap.to() (animez depuis celle-ci).

Consultez references/composition.md pour le schéma complet des attributs de données et les règles de composition.

4. Animer avec GSAP

Chaque composition doit :

• Enregistrer sa timeline : window.__timelines["<id-composition>"] = tl
• Démarrer en pause : gsap.timeline({ paused: true }) — le lecteur contrôle la lecture
• Utiliser des valeurs de repeat finies (pas de repeat: -1 — casse le moteur de capture). Calculez : repeat: Math.ceil(duration / cycleDuration) - 1.
• Être déterministe — pas de Math.random(), Date.now() ou logique basée sur l'horloge. Utilisez un générateur pseudo-aléatoire ensemencé si vous avez besoin de pseudo-aléatoire.
• Être construite de manière synchrone — pas de async/await, setTimeout ou Promises autour de la construction de la timeline.

Consultez references/gsap.md pour l'API GSAP de base (tweens, easings, stagger, timelines).

5. Transitions entre les scènes

Les compositions multi-scènes nécessitent des transitions. Règles :

1. Utilisez toujours une transition entre les scènes — pas de coupes brusques.
2. Utilisez toujours des animations d'entrée sur chaque élément de scène (gsap.from(...)).
3. N'utilisez jamais d'animations de sortie sauf sur la scène finale — la transition EST la sortie.
4. La scène finale peut s'estomper.

Utilisez npx hyperframes add <nom-de-transition> pour installer les transitions avec shaders (flash-through-white, liquid-wipe, etc.). Liste complète : npx hyperframes add --list.

6. Audio, sous-titres, TTS, réactif à l'audio, surlignage

• Audio : toujours un élément <audio> séparé (la vidéo est muted playsinline).
• TTS : npx hyperframes tts "Texte du script" --voice af_nova --output narration.wav. Listez les voix avec --list. La première lettre de l'ID de la voix encode la langue (a/b=Anglais, e=Espagnol, f=Français, j=Japonais, z=Mandarin, etc.) — la CLI déduit automatiquement la locale du phonémiseur ; passez --lang uniquement pour remplacer. La phonémisation non-anglaise nécessite espeak-ng installé au niveau système.
• Sous-titres : npx hyperframes transcribe narration.wav → transcription au niveau du mot. Choisissez un style en fonction du ton de la transcription (hype / corporate / tutorial / storytelling / social — voir le tableau dans references/features.md). Règle de langue : n'utilisez jamais les modèles whisper .en sauf si l'audio est confirmé en anglais — .en traduit l'audio non-anglais au lieu de le transcrire. Chaque groupe de sous-titres DOIT avoir une coupure dure tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) après son tween de sortie — sinon les groupes fuient visibles dans les suivants.
• Visuels réactifs à l'audio : extrayez préalablement les bandes audio (basses / médiums / aigus) et échantillonnez par image à l'intérieur de la timeline avec une boucle for de tl.call(draw, [], f / fps) — un seul long tween ne réagit PAS à l'audio. Mappez les basses → scale (pulsation), les aigus → textShadow/boxShadow (lueur), l'amplitude globale → opacity/y/backgroundColor. Évitez les clichés de barres d'égaliseur — laissez le contenu guider le visuel, l'audio piloter son comportement.
• Surlignage de style marqueur : les effets de surlignage, cercle, éclat, gribouillage, contour pour l'emphase du texte sont déterministes en CSS+GSAP — voir references/features.md#marker-highlighting. Totalement accessible par seek, pas de filtres SVG animés.
• Transitions de scène : toute composition multi-scènes DOIT utiliser des transitions (pas de coupes brusques). Choisissez parmi les primitives CSS (poussée glissée, fondu avec flou, zoom à travers, blocs décalés) ou les transitions avec shaders (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split, etc.) via npx hyperframes add. Les tables d'ambiance et d'énergie se trouvent dans references/features.md#transitions. Ne mélangez pas les transitions CSS et shaders dans la même composition.

7. Lint, valider, inspecter, prévisualiser, rendre

npx hyperframes lint              # détecte les data-composition-id manquants, les pistes qui se chevauchent, les timelines non enregistrées
npx hyperframes validate          # audit de contraste WCAG à 5 horodatages
npx hyperframes inspect           # audit de mise en page visuelle — débordement, éléments hors cadre, texte occulté
npx hyperframes preview           # aperçu en direct dans le navigateur
npx hyperframes render --quality draft --output draft.mp4    # itération rapide
npx hyperframes render --quality high --output final.mp4     # livraison finale

hyperframes validate échantillonne les pixels d'arrière-plan derrière chaque élément de texte et avertit sur les rapports de contraste inférieurs à 4.5:1 (ou 3:1 pour les grands textes). hyperframes inspect est le compagnon côté mise en page — il parcourt la page à plusieurs horodatages et signale les problèmes qu'un lint statique ne peut pas voir (un sous-titre qui dépasse la zone de sécurité seulement à 4.5s, une carte qui déborde quand son titre est la variante la plus longue, un élément qui se retrouve derrière un shader de transition). Exécutez inspect particulièrement sur les compositions avec des bulles de parole, des cartes, des sous-titres ou une typographie serrée.

8. Site web vers vidéo (si l'utilisateur donne une URL)

Utilisez le workflow de capture vers vidéo en 7 étapes dans references/website-to-video.md : capture → DESIGN.md → SCRIPT.md → storyboard → composition → rendu → livraison.

Pièges

• HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ a supprimé ce protocole. Assurez-vous d'être sur hyperframes@>=0.4.2 (détection automatique et repli en mode capture d'écran). Porte de sortie : export PRODUCER_FORCE_SCREENSHOT=true. Voir hyperframes#294 et references/troubleshooting.md.
• Chrome système (pas chrome-headless-shell) — les rendus bloquent pendant 120s puis timeout. Exécutez npx puppeteer browsers install chrome-headless-shell (setup.sh le fait). hyperframes doctor rapporte quel binaire sera utilisé.
• repeat: -1 n'importe où — casse le moteur de capture. Calculez toujours un nombre de répétitions fini.
• gsap.set() sur des éléments de clip qui entrent plus tard — l'élément n'existe pas au chargement de la page. Utilisez tl.set(selector, vars, timePosition) à l'intérieur de la timeline à la place, à ou après le data-start du clip.
• <br> dans le texte du contenu — les sauts forcés ne connaissent pas la largeur de police rendue, donc le retour à la ligne naturel + <br> double les sauts. Utilisez max-width pour laisser le texte se renvoyer à la ligne. Exception : les titres d'affichage courts où chaque mot est délibérément sur sa propre ligne.
• Animer visibility ou display — GSAP ne peut pas tweenner ces propriétés. Utilisez autoAlpha (gère à la fois la visibilité et l'opacité).
• Appeler video.play() ou audio.play() — le framework possède la lecture. Ne les appelez jamais vous-même.
• Construire des timelines de manière asynchrone — le moteur de capture lit window.__timelines de manière synchrone après le chargement de la page. N'enveloppez jamais la construction de la timeline dans async, setTimeout ou une Promise.
• index.html autonome enveloppé dans <template> — cache tout le contenu au navigateur. Seules les sous-compositions chargées via data-composition-src utilisent <template>.
• Utiliser la vidéo pour l'audio — toujours <video> en muet + <audio> séparé.

Vérification

Avant et après le rendu :

1. Lint + validation + inspection passent : npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect (lint détecte les problèmes structurels, validate détecte le contraste, inspect détecte les problèmes de mise en page visuelle / débordement — voir troubleshooting.md si des avertissements apparaissent).
2. Chorégraphie d'animation — pour les nouvelles compositions ou les changements d'animation importants, exécutez la carte d'animation. npx hyperframes init copie les scripts de la compétence dans le projet, donc le chemin est local au projet :

   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
     --out <composition-dir>/.hyperframes/anim-map
   

   Produit un seul animation-map.json avec des résumés par tween, une timeline Gantt ASCII, la détection de stagger, les zones mortes (>1s sans animation), les cycles de vie des éléments et des indicateurs (offscreen, collision, invisible, paced-fast <0.2s, paced-slow >2s). Scannez les résumés et les indicateurs — corrigez ou justifiez chacun. Ignorez sur les petites modifications.
3. Fichier existe et non nul : ls -lh final.mp4.
4. Durée correspond à data-duration : ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4.
5. Vérification visuelle : extrayez une image en milieu de composition : ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png.
6. Audio présent si attendu : ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1.

Si hyperframes render échoue, exécutez npx hyperframes doctor et joignez sa sortie lors du signalement.

Références

• composition.md — attributs de données, contrat de timeline, règles non négociables, règles de typographie/actifs
• cli.md — toutes les commandes CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
• gsap.md — API GSAP de base pour HyperFrames (tweens, easings, stagger, timelines, matchMedia)
• features.md — sous-titres, TTS, réactif à l'audio, surlignage de marqueur, transitions (chargement à la demande)
• website-to-video.md — workflow de capture vers vidéo en 7 étapes
• troubleshooting.md — correction OpenClaw, variables d'environnement, erreurs de rendu courantes