Communitygithub.com

simpletibr/simplicio-loop-marketing

Permet d'écrire des compositions animées HTML (typographie cinétique, cartes de citation animées, bandes de visualisation de données programmatiques) pour le rendu HyperFrames, utilisé lorsque le fournisseur vidéo résolu par la matrice de routage est `hyperframes`.

Qu'est-ce que simplicio-loop-marketing ?

Cette compétence (skill) est le guide d'écriture pour le moteur de rendu HyperFrames, qui convertit des fichiers HTML en vidéos MP4 de manière déterministe et reproductible. Elle est invoquée lorsqu'une tâche marketing nécessite une animation de haute qualité à partir de variables déclarées (comme des indicateurs clés de performance hebdomadaires ou des citations animées). Les compositions sont des fichiers HTML bruts avec des attributs spécifiques (`data-start`, `data-duration`, `data-track-index`) ; le rendu utilise un navigateur headless pour chronométrer chaque image et les assemble avec FFmpeg. La compétence impose des règles strictes : chaque élément doit avoir une animation d'entrée, toutes les timelines sont enregistrées en pause et pilotées par le framework, et l'utilisation de `Math.random()` ou de logique temporelle non déterministe est interdite. Elle fonctionne sur la plateforme HyperFrames dans un environnement Claude, Cursor ou Codex, en collaboration avec les skills `hyperframes-prompt-builder` (qui prépare les entrées) et `hyperframes-cli` (qui valide et effectue le rendu). L'objectif est de produire des artefacts vidéo re-rendus à l'identique avec les mêmes variables, pour des campagnes marketing automatisées et fiables.

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

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.md ou un provider_override.video: hyperframes dans le frontmatter) vers le fournisseur HyperFrames.
  • La tâche est motion-typography, data-viz-reel, programmatic-short ou 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, --variables différents, ligne de base identique en octets.

Entrées

  • composition_id : chaîne. Slug court utilisé pour le répertoire du projet et data-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 de clients/<slug>/design.md lorsqu'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éfaut outputs/<client>/<date>/<piece-id>/).

Processus

  1. 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.
  2. 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.
  3. 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 sorties gsap.to().
  4. Composer le HTML. La racine <html> porte data-composition-id, data-width, data-height. Chaque clip porte id, data-start, data-duration, data-track-index. Paramétrer avec data-composition-variables (tableau JSON sur <html>) ; lire à l'exécution avec window.__hyperframes.getVariables().
  5. 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 de Math.random(), pas de logique temporelle, pas de construction de timeline asynchrone.
  6. 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.
  7. Vidéo et audio. <video> doit être muet ; l'audio vit dans un élément <audio> séparé sur sa propre piste.
  8. Valider localement avec npx hyperframes lint, puis npx hyperframes inspect (débordement de texte, rognage de conteneur). Ne rendre que lorsque les deux passent. Délégué à la compétence hyperframes-cli.
  9. É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 dans CLAUDE.md.

Sorties

  • project_path : chaîne. Chemin vers le répertoire du projet HyperFrames.
  • composition_html : chaîne. Le contenu du index.html écrit (ou le chemin vers celui-ci sous project_path).
  • render_args : objet. Les indicateurs à passer à npx hyperframes render (--fps, --quality, --variables, --strict).
  • expected_artifact : chaîne. Le chemin MP4 qui apparaîtra sous output_dir aprè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 de Date.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-variables pour que la même composition se re-rende pour de nouvelles pièces.
  • Ne jamais modifier un MP4 rendu sous outputs/ ; relancer hyperframes 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.md manquant et aucun jeton de design passé : s'arrêter et demander. Ne pas inventer de palette.
  • npx hyperframes lint signale des erreurs (data-composition-id manquant, pistes qui se chevauchent, timelines non enregistrées) : bloquer le rendu jusqu'à correction.
  • npx hyperframes inspect signale 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_seconds de la composition : couper l'audio, ne jamais étendre duration_seconds pour 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 par video-prompt-builder lorsque la matrice résout vers hyperframes.
  • 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

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

Skills associés