Communitygithub.com

Kingly-Agency/deadzone

Crée des compositions vidéo basées sur HTML, des cartes titres animées, des superpositions sociales, des vidéos de personnes parlant avec sous-titres, des visuels audio-réactifs et des transitions shader en utilisant HyperFrames. L'HTML est la source de vérité pour la vidéo. À utiliser lorsque l'utilisateur souhaite un MP4/WebM rendu à partir d'une composition HTML, animer du texte/des logos/des graphiques sur des médias, ajouter des sous-titres synchronisés à l'audio, utiliser la synthèse vocale (TTS) ou convertir un site web en vidéo.

Qu'est-ce que deadzone ?

HyperFrames est une compétence avancée pour créer des vidéos via HTML/CSS/JS, où l'HTML sert de source de vérité unique. Elle permet de produire des compositions vidéo enrichies (titres animés, superpositions sociales, vidéos avec sous-titres synchronisés, visuels audio-réactifs, transitions shader) en capturant chaque frame de la page et en encodant vers MP4/WebM avec FFmpeg. La compétence est conçue pour compléter `manim-video` : utilisez HyperFrames pour le motion-design, les vidéos tutoriels, les démonstrations de produits et tout contenu mixte, tandis que `manim-video` est réservé aux animations mathématiques ou géométriques. Le workflow structuré inclut un plan initial (avec gate d'identité visuelle), une phase de layout HTML+CSS (hero frame) avant l'animation GSAP, des transitions obligatoires entre scènes, la gestion de l'audio et des sous-titres (TTS + transcription), des vérifications de lint/validation/inspection, et des commandes CLI simples pour prévisualisation et rendu (avec options de qualité). La compétence est robuste face aux pièges techniques (problems Chromium, loops infinies, timeline asynchrone) et inclut des processus de vérification (lint, validation contrastes, inspection layout, animation map) pour garantir une production vidéo fiable et déterministe.

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

L'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 frame par frame et encode en MP4/WebM avec FFmpeg.

Complément à manim-video : Utilisez manim-video pour les explications mathématiques/géométriques (équations, style 3B1B). Utilisez hyperframes pour le motion-design, les vidéos avec personne parlante et sous-titres, les visites de produits, les superpositions sociales, les transitions shader, et tout contenu piloté par des médias vidéo/audio réels.

Quand 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 narrative avec sous-titres (TTS + sous-titres synchronisés sur la forme d'onde)
  • Visuels audio-réactifs (sync sur le beat, barres de spectre, lueur pulsante)
  • Transitions de scène à scène (fondu enchaîné, wipe, warp shader, flash-through-white)
  • 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 :

  • Animation mathématique pure / équation (→ manim-video)
  • Génération d'images ou mèmes (→ meme-generation, modèles image)
  • Visioconférence ou streaming en direct

Référence Rapide

npx hyperframes init my-video               # ébaucher un projet
cd my-video
npx hyperframes lint                        # valider avant prévisualisation/rendu
npx hyperframes preview                     # prévisualisation 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 (unique)

bash "$(dirname "$(find ~/.hermes/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 ce n'est pas le cas).
  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.

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

Procédure

1. Planifier avant d'écrire l'HTML

Avant de toucher au code, articulez à haut niveau :

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

Porte d'identité visuelle (HARD-GATE). Avant d'écrire UNE composition HTML, 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 indicateurs que cette étape a été sautée). Vérifiez dans l'ordre :

  1. DESIGN.md à la racine du projet ? → Utilisez ses couleurs exactes, polices, règles de mouvement et contraintes « Ce qu'il NE PAS Faire ».

  2. L'utilisateur a nommé un style (par ex. « Swiss Pulse », « sombre et technique », « marque de luxe ») ? → Générez un DESIGN.md minimal avec ## Style Prompt, ## Couleurs (3-5 hex avec rôles), ## Typographie (1-2 familles), ## Ce qu'il NE PAS Faire (3-5 anti-patrons).

  3. Aucun des cas ci-dessus ? → Posez 3 questions avant d'écrire tout HTML :

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

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

2. Ébaucher

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 amorcer avec des médias.

3. Mise en page avant l'animation

Écrivez d'abord le HTML+CSS statique pour le cadre héros — 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 padding pour pousser le contenu vers l'intérieur — ne jamais utiliser position: absolute; top: Npx sur un conteneur de contenu (le contenu déborde lorsqu'il est plus haut que l'espace restant).

Seulement après que le cadre héros semble correct, ajoutez les entrées gsap.from() (animer vers la position CSS) et les sorties gsap.to() (animer depuis celle-ci).

Voir references/composition.md pour le schéma complet des attributs data-* 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 repeat finies (pas de repeat: -1 — casse le moteur de capture). Calculez : repeat: Math.ceil(durée / duréeCycle) - 1.
  • Être déterministe — pas de Math.random(), Date.now(), ou logique basée sur l'horloge réelle. Utilisez un PRNG ensemencé si vous avez besoin de pseudo-aléatoire.
  • Être construite de manière synchrone — pas de async/await, setTimeout, ou Promesses autour de la construction de la timeline.

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

5. Transitions entre les scènes

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

  1. Toujours utiliser une transition entre les scènes — pas de cut directs.
  2. Toujours utiliser des animations d'entrée sur chaque élément de scène (gsap.from(...)).
  3. Ne jamais utiliser d'animations de sortie sauf sur la scène finale — la transition EST la sortie.
  4. La scène finale peut s'estomper (fade out).

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

6. Audio, sous-titres, TTS, audio-réactif, 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 le paramètre régional du phonémiseur ; passez --lang uniquement pour écraser. La phonémisation non-anglaise nécessite espeak-ng installé au niveau système.
  • Sous-titres : npx hyperframes transcribe narration.wav → transcription au niveau mot. Choisissez le style à partir 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 un tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) de suppression après son tween de sortie — sinon les groupes fuient visibles dans les suivants.
  • Visuels audio-réactifs : pré-extrayez les bandes audio (bass / mid / treble) et échantillonnez par frame à 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 bass → scale (pulsation), treble → textShadow/boxShadow (lueur), 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 type marqueur : les effets de surlignage, cercle, burst, griffonnage, sketchout pour l'emphase du texte sont du CSS+GSAP déterministe — voir references/features.md#surlignage-de-type-marqueur. Totalement déplaçable, pas de filtres SVG animés.
  • Transitions de scène : toute composition multi-scènes DOIT utiliser des transitions (pas de cut directs). Choisissez parmi les primitives CSS (push slide, blur crossfade, zoom through, staggered blocks) ou les transitions shader (flash-through-white, liquid-wipe, cross-warp-morph, chromatic-split, etc.) via npx hyperframes add. Les tableaux d'ambiance et d'énergie se trouvent dans references/features.md#transitions. Ne mélangez pas les transitions CSS et shader 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          # vérification de contraste WCAG à 5 horodatages
npx hyperframes inspect           # vérification de mise en page visuelle — débordement, éléments hors frame, texte occulté
npx hyperframes preview           # prévisualisation 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 prévient pour les ratios de contraste inférieurs à 4,5:1 (ou 3:1 pour les grands textes). hyperframes inspect est le compagnon côté mise en page — exécute 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 dialogue, cartes, sous-titres ou 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' n'a pas été trouvé — Chromium 147+ a supprimé ce protocole. Assurez-vous d'être sur hyperframes@>=0.4.2 (détecte automatiquement et retombe en mode capture d'écran). Échappatoire : 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 indique 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, au moment ou après le data-start du clip.
  • <br> à l'intérieur de texte de contenu — les sauts forcés ne connaissent pas la largeur de police rendue, donc le retour à la ligne naturel + <br> double le saut. Utilisez max-width pour laisser le texte se retourner. Exception : titres d'affichage courts où chaque mot est délibérément sur sa propre ligne.
  • Animer visibility ou display — GSAP ne peut pas interpoler ces propriétés. Utilisez autoAlpha (gère à la fois visibility et opacity).
  • Appeler video.play() ou audio.play() — le framework contrôle la lecture. N'appelez jamais ces méthodes 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 Promesse.
  • index.html autonome enveloppé dans <template> — cache tout le contenu du navigateur. Seules les sous-compositions chargées via data-composition-src utilisent <template>.
  • Utiliser la vidéo pour l'audio — toujours <video> muet + <audio> séparé.

Vérification

Avant et après le rendu :

  1. Passage de lint + validate + inspect : 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 significatifs, 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 <dossier-composition> \
      --out <dossier-composition>/.hyperframes/anim-map
    
    Génère un seul fichier animation-map.json avec des résumés par tween, une timeline ASCII Gantt, 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). Parcourez les résumés et les indicateurs — corrigez ou justifiez chacun. Ignorez sur les petites modifications.
  3. Le fichier existe et n'est pas nul : ls -lh final.mp4.
  4. La 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 frame du milieu de la 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 rapport.

Références

  • composition.md — attributs data, contrat de timeline, règles non négociables, règles de typographie/ressources
  • cli.md — chaque commande CLI (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
  • gsap.md — API GSAP de base pour HyperFrames (tweens, ease, stagger, timelines, matchMedia)
  • features.md — sous-titres, TTS, audio-réactif, surlignage de type 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

Skills associés