HyperFrames
HyperFrames est un moteur de rendu HTML → MP4 (Apache 2.0). Les compositions sont de simples fichiers HTML avec les attributs data-start, data-duration, data-track-index ; le moteur pilote un Chrome headless à travers la timeline image par image et envoie les images à FFmpeg. La compétence hyperframes-prompt-builder est le point d'entrée du dispatcher marketing ; cette compétence contient les règles d'écriture.
Quand l'invoquer
- Une pièce est routée (via
PROVIDERS.mdou unprovider_override.video: hyperframesdans le frontmatter) vers le fournisseur HyperFrames. - La tâche est
motion-typography,data-viz-reel,programmatic-shortou toute composition nécessitant une sortie déterministe à partir de variables déclarées (p. ex., bande KPI hebdomadaire qui se re-rend à l'identique avec de nouveaux nombres). - Un visuel approuvé (carte de citation, diapositive de carrousel) doit être promu en une courte pièce animée sans modifier le système typographique.
- L'orchestrateur a besoin d'un artefact re-rendable : même composition,
--variablesdifférents, ligne de base identique en octets.
Entrées
composition_id: chaîne. Slug court utilisé pour le répertoire du projet etdata-composition-id.aspect:9:16|1:1|16:9|4:5.duration_seconds: entier. Durée totale de la composition.scenes: tableau. Chacune{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }.design_tokens: objet. Couleurs de marque, familles typographiques primaires/secondaires, échelle d'espacement. Provenant declients/<slug>/design.mdlorsqu'il existe.variables: tableau, optionnel. Paramètres déclarés que les appelants peuvent remplacer au moment du rendu{ id, type, label, default }.assets: objet, optionnel.{ video?, audio?, images[] }— chemins locaux sous le projet.output_dir: chaîne. Répertoire dans lequel le moteur écrit le MP4 (par défautoutputs/<client>/<date>/<piece-id>/).
Processus
- Lire d'abord le contexte de marque. Charger
clients/<client-actif>/design.md(ou les jetons de design passés). Refuser d'écrire du HTML avant que les jetons soient connus — revenir aux valeurs par défaut du dépôt uniquement si le client n'en a pas. - Planifier l'arc narratif à voix haute (scènes, rythme, transitions, battement) avant d'écrire le balisage. Accroche dans les 1,5 premières secondes, corps, CTA en fin de séquence.
- Disposition avant animation. Écrire d'abord la disposition finale à l'écran — placer les éléments là où ils se trouvent à la fin. Animer vers ces positions avec
gsap.from(); seule la scène finale peut utiliser des sortiesgsap.to(). - Composer le HTML. La racine
<html>portedata-composition-id,data-width,data-height. Chaque clip porteid,data-start,data-duration,data-track-index. Paramétrer avecdata-composition-variables(tableau JSON sur<html>) ; lire à l'exécution avecwindow.__hyperframes.getVariables(). - Enregistrer chaque timeline en pause.
const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;— le cadre pilote la lecture. Pas de répétitions infinies, pas deMath.random(), pas de logique temporelle, pas de construction de timeline asynchrone. - Transitions entre chaque scène. Pas de coupures brusques. Utiliser les transitions cataloguées (fondu, volet, masqué, shader) listées dans la référence amont
references/transitions.md. - Vidéo et audio.
<video>doit être muet ; l'audio vit dans un élément<audio>séparé sur sa propre piste. - Valider localement avec
npx hyperframes lint, puisnpx hyperframes inspect(débordement de texte, rognage de conteneur). Ne rendre que lorsque les deux passent. Délégué à la compétencehyperframes-cli. - Émettre le manifeste. Écrire
manifest.jsonà côté du MP4 avec{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }. Requis par la Définition de Fait dansCLAUDE.md.
Sorties
project_path: chaîne. Chemin vers le répertoire du projet HyperFrames.composition_html: chaîne. Le contenu duindex.htmlécrit (ou le chemin vers celui-ci sousproject_path).render_args: objet. Les indicateurs à passer ànpx hyperframes render(--fps,--quality,--variables,--strict).expected_artifact: chaîne. Le chemin MP4 qui apparaîtra sousoutput_diraprès le rendu.cost_estimate_usd: nombre. Rendu local — temps de calcul uniquement ; signaler 0 pour DRY_RUN, sinon estimer à partir de--workers× durée.
Règles non négociables
- Chaque élément a une animation d'entrée (
gsap.from()). - Toutes les timelines commencent en pause et sont enregistrées sur
window.__timelines. - Pas de
Math.random(), pas deDate.now()dans la logique de composition, pas d'animation pilotée par setTimeout. - Pistes vidéo muettes ; ne jamais intégrer d'audio dans
<video>. - Ne jamais intégrer directement le texte client dans le balisage s'il pourrait être une variable — le déclarer dans
data-composition-variablespour que la même composition se re-rende pour de nouvelles pièces. - Ne jamais modifier un MP4 rendu sous
outputs/; relancerhyperframes renderà la place.
Exemples
Exemple 1 : bande KPI hebdomadaire (programmatic-short)
Entrée : { composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] }
Sortie : un projet sous outputs/<client>/<date>/kpi-weekly-w21/ dont index.html lit les deux variables numériques et les anime ; render_args.--variables les résout par pièce.
Exemple 2 : carte de citation animée (motion-typography)
Entrée : { composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] }
Sortie : une composition typographique cinétique qui respecte l'appariement typographique du client actif, avec une entrée de texte masqué et une pause douce sur l'image finale.
Modes d'échec
design.mdmanquant et aucun jeton de design passé : s'arrêter et demander. Ne pas inventer de palette.npx hyperframes lintsignale des erreurs (data-composition-idmanquant, pistes qui se chevauchent, timelines non enregistrées) : bloquer le rendu jusqu'à correction.npx hyperframes inspectsignale un débordement de texte sur une scène : privilégier le réaménagement de la disposition plutôt que de réduire la taille de police en dessous du minimum système.- Piste audio plus longue que
duration_secondsde la composition : couper l'audio, ne jamais étendreduration_secondspour l'adapter. - La composition utilise
Math.random()ou l'heure de l'horloge murale : refactoriser en une variable déclarée ou un générateur déterministe basé sur une graine avant le rendu.
Compétences associées
hyperframes-cli: commandes lint, inspect, preview, render. Toujours invoquée après l'écriture.hyperframes-prompt-builder: spécialiste marketing qui traduit un brief de pièce dans la forme d'entrée attendue par cette compétence, appelée parvideo-prompt-builderlorsque la matrice résout vershyperframes.video-prompt-builder: dispatcheur générique.qa-tech-specs: valide le MP4 rendu par rapport aux spécifications de la plateforme (aspect, durée, zones de sécurité).compliance-<client actif>: s'exécute après le rendu sur l'artefact rendu et le texte à l'écran résolu à partir des variables.
Référence amont
Compétence amont complète (modèles de composition, catalogue de transitions, audio-réactif, sous-titres, données en mouvement) : https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes