Communitygithub.com

leocosta/octopus

Transformez une application en cours d'exécution en une vidéo promotionnelle dynamique et haute-fidélité en pilotant le vrai produit (Chrome headless) sur un environnement de démonstration, en capturant des captures d'écran nettes et en composant un montage animé (typographie cinétique, zooms cinématographiques, surbrillance spotlight, cadres téléphone, musique) avec HyperFrames + GSAP. Indépendant de l'application : lit un fichier promo.config et une liste de séquences par projet ; extrait automatiquement le système de design de l'application cible pour que les superpositions correspondent à sa marque. Génère un master 16:9 et un format vertical 9:16.

Qu'est-ce que octopus ?

Le skill **leocosta/octopus** (anciennement Motion Promo Protocol) crée des vidéos promotionnelles de qualité publicitaire à partir d'une application web réelle. Au lieu d'un enregistrement d'écran traditionnel, il utilise un navigateur headless (Chrome) pour capturer des captures d'écran nettes de chaque écran dans un environnement de démonstration, puis les assemble en un montage animé : typographie cinétique, zooms cinématographiques, surbrillance spotlight, cadres téléphone pour les écrans mobiles, et une piste musicale. Ce skill est agnostique à l'application : il lit un fichier de configuration (promo.config.mjs) et une liste de séquences (beats.json) propres à chaque projet, et extrait automatiquement les tokens de design (couleurs, polices, rayons) de l'application cible pour que les superpositions s'adaptent à sa marque. Il est compatible avec les agents de codage comme Claude Code et Cursor, et nécessite Node 20+, Chrome système, ffmpeg/ffprobe, ainsi qu'un environnement de démonstration exécutable. Le rendu final produit un master 16:9 et un format vertical 9:16, idéal pour des pages d'accueil, des annonces de fonctionnalités ou des vidéos de démonstration produit. L'extraction des tokens de design et l'utilisation de HyperFrames (HTML→MP4) garantissent des résultats déterministes, reproductibles et conformes à la marque.

Compatible avec~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Protocole de Promotion Vidéo Animée

Aperçu

Ce skill génère une vidéo promotionnelle dynamique de qualité publicitaire d'un véritable produit, pas un enregistrement d'écran ni une maquette. Il pilote l'application réelle dans un navigateur headless sur un environnement de démonstration, capture des images nettes de chaque écran et compose un montage animé par-dessus : typographie cinétique, zooms cinématographiques, surbrillance spotlight qui suivent le zoom, cadres téléphone pour les écrans mobiles, coupures rythmées, et une piste musicale. La sortie est un master 16:9 et une version verticale 9:16.

C'est la contrepartie de rendu de launch-feature : launch-feature écrit un video-script.md (le script/sequences en prose) ; motion-promo transforme une liste de séquences en la vidéo finale montée et mise en musique. Quand les deux sont exécutés, enchaînez-les — script généré par launch-feature → séquences pour motion-promo.

Pourquoi HyperFrames (HTML→MP4) et pas un enregistrement d'écran : déterministe, reproductible, contrôlable pour la marque, et évite les modes de défaillance de la capture de navigation en direct (voir Règles). L'application n'est utilisée que pour produire des images fixes + des tokens de design ; tout le mouvement est créé par code.

Quand l'utiliser

  • Une page d'accueil / page de vente a besoin d'une démo produit ou d'une vidéo vedette.
  • Annoncer une fonctionnalité et vous voulez la vidéo rendue, pas seulement le script.
  • Vous avez un espace de démonstration/sandbox avec des données réalistes à montrer.

Ne pas utiliser pour : des présentations internes où la fidélité n'a pas d'importance (une capture d'écran brute est moins chère), ou des applications sans environnement de démonstration exécutable.

Prérequis et secrets

Aucune clé API / secret n'est requis. Le rendu HyperFrames est sans clé (HTML→MP4 local), et les polices (Google Fonts) + la musique par défaut (incompetech) sont des URL publiques. La seule information d'authentification est le login de démo de l'application cible, qui se trouve dans le fichier promo.config.mjs du dépôt cible — jamais dans ce skill. L'authentification est une recette enfichable : authInject() retourne les valeurs à injecter (token dans localStorage, cookie, clé API, sélection de tenant en plusieurs étapes), ou authFlow(page) PILOTE une interface de connexion interactive (Azure AD / Entra, Okta, Google SSO) et le moteur prend un instantané de la session (localStorage + sessionStorage + cookies, y compris HttpOnly). Les identifiants SSO proviennent des variables d'environnement, pas du fichier. Headless ne peut pas passer une MFA interactive — utilisez un compte de démonstration exempté de MFA (exception d'accès conditionnel) ou un mot de passe d'application.

Dépendances système (vous les installez — le skill ne peut pas) : Node 20+, Chrome système (google-chrome/Chromium), ffmpeg + ffprobe. Sortie réseau pour les polices/musique.

Dépendances automatiques/sur demande : hyperframes est récupéré à la demande via npx (pas de pré-installation). puppeteer-core est une dépendance npm installée — il utilise le Chrome système et ne télécharge pas Chromium.

Configuration : copier templates/ dans video/<slug>/ (inclut hyperframes.json ; meta.json est généré par compose-gen), renommer gitignore en .gitignore, puis npm install et npm run preflight (vérifie Chrome, ffmpeg/ffprobe et puppeteer-core ; échoue bruyamment si l'un manque). Exécutez le pipeline étape par étape ou npm run build.

  • Un sandbox/démo exécutable de l'application cible.

Entrées

Tout ce qui est spécifique au projet se trouve dans le dépôt cible, jamais dans ce skill :

  1. promo.config.mjs — le contrat (voir templates/promo.config.example.mjs). URL de l'application / comment la servir, recette d'authentification, compte/tenant de démo, chemins de sortie et préférence musicale. Les tokens de design sont extraits automatiquement (étape 2) mais peuvent être surchargés ici.
  2. beats.json — la liste ordonnée des séquences (voir templates/beats.schema.json). Chaque séquence = un écran (route ou image fixe) + cible de surbrillance optionnelle + texte de callout + viewport (desktop/mobile).

Copiez les deux dans video/<slug>/ du dépôt cible à partir de templates/.

Protocole

Travaillez dans video/<slug>/ du dépôt cible. Chaque étape a une vérification.

0. Soigner les données de démo (faites-le d'abord — cela fait ou défait la vidéo)

Les données de démo/sandbox sont généralement obsolètes ou remises à zéro pour la période en cours (factures impayées du mois en cours, entonnoirs vides), ce qui se lit comme "R$0 de revenus" à côté de "en pilotage automatique" — activement contre-productif. Avant la capture, écrivez un germe idempotent et relatif à la date actuelle qui donne à chaque séquence des chiffres sains (voir Règles → Zéros dans les données de démo). Vérifiez en interrogeant les métriques que chaque séquence montrera.

1. Servir l'application contre l'API de démo, sur une origine autorisée CORS

Construisez/servez l'application pointant vers l'API de démo. L'origine de service doit être dans la liste d'autorisation CORS de l'API sinon chaque récupération de données est bloquée et les écrans s'affichent vides (voir Règles → Origine CORS). Sonder la liste d'autorisation de l'API et servez sur un port autorisé. Vérifiez : une route approfondie retourne 200 et une requête authentifiée /api/... depuis cette origine retourne 2xx.

2. Extraire le système de design de l'application cible

Exécutez templates/engine/extract-design.mjs contre l'application authentifiée servie. Il échantillonne les styles calculés (fond de page, couleur primaire/accent depuis les boutons/liens, familles de polices heading + mono, rayon) → design.tokens.json. Ceux-ci alimentent la composition comme variables CSS afin que les superpositions cinétiques, l'accent et les polices correspondent automatiquement à la marque de l'application. Examinez et surchargez dans promo.config si un token échantillonné est incorrect.

3. Capturer des images nettes par séquence

Exécutez templates/engine/capture.mjs. Il s'authentifie (via la recette authInject de la configuration), navigue vers la route de chaque séquence à son viewport, attend que les données réelles arrivent (pas seulement le réseau inactif — voir Règles), et prend des captures d'écran dans assets/<beat>.png. Vérifiez que chaque image montre du contenu chargé (taille > ~10 Ko, vérifiez ponctuellement que l'élément cible est présent).

4. Définir les séquences + générer la composition

Remplissez beats.json (route/image fixe, surbrillance {x,y,w,h,label} dans l'espace de pixels de l'image — ou {selector,label,padding?}, mesuré automatiquement par capture.mjs et préféré aux coordonnées réglées manuellement, callout {kicker,headline,sub}, viewport, durées). Exécutez templates/engine/compose-gen.mjs → index.html depuis templates/composition.html, en injectant les tokens + séquences. Gardez la rythmique : 3–5 s par séquence, coupures franches, une idée par séquence.

5. Récupérer une piste musicale libre

Exécutez templates/engine/fetch-music.mjs → assets/music.mp3. La source par défaut est CC-BY (incompetech) ; CC-BY nécessite une attribution (notez-la pour la description du LP). Préférez une piste fournie par le projet/CC0 quand elle est disponible.

6. Rendu

npx hyperframes render → MP4 silencieux. Exécutez d'abord hyperframes lint/inspect ; traitez les débordements décoratifs/de sortie d'animation en dehors du cadre comme du bruit, un vrai recadrage de texte comme une correction.

7. Examiner les images + corriger l'alignement des surbrillances

Extrayez les images au début et à la fin de chaque zoom et examinez-les visuellement. Le défaut n°1 : la surbrillance spotlight dérive de sa cible pendant le zoom — parce que la boîte de surbrillance doit être un enfant du conteneur mis à l'échelle (voir Règles → Suivi de surbrillance). Vérifiez aussi : pas d'écrans vides/animation de chargement, les écrans mobiles sont bien cadrés dans le cadre téléphone, le texte est lisible.

8. Ajouter la musique

Exécutez templates/engine/mux.mjs → MP4 final mis en musique (loudnorm, fondu entrée/sortie, -shortest). Vérifiez que la sortie a un flux audio et correspond à la durée de la vidéo.

9. Dériver la version 9:16

mux.mjs --reframe produit une version 1080×1920. Ne faites pas de recadrage centré (il coupe les callouts ancrés en bas) — utilisez une boîte floutée qui préserve tout le cadre ; les séquences mobiles sont déjà centrées.

Règles (dures à acquérir — ne les réapprenez pas)

  • Suivi de surbrillance. Un rectangle de surbrillance/spotlight au-dessus d'un écran qui est zoomé DOIT être un enfant du même élément qui reçoit la transformation scale, dans l'espace de coordonnées de pixels de l'image fixe. En tant que frère, il reste fixe pendant que l'image zoome et dérive de sa cible tout au long du plan.
  • Zéros dans les données de démo. La période en cours est souvent non payée/vide. Soignez-la avec un germe idempotent (identifiants déterministes, supprimer-puis-insérer) et relatif à current_date pour qu'il se corrige automatiquement chaque période.
  • Origine CORS. Une version servie localement appelant une API de démo déployée est cross-origin. Servez sur une origine que l'API autorise dans sa liste (sondez-la) — ne désactivez jamais la sécurité web du navigateur pour contourner cela.
  • Attendre les données réelles. networkidle2 peut se résoudre avant que la requête de données de l'application n'arrive → vous capturez un écran de chargement. Attendez en plus une réponse /api/... réussie (ou le sélecteur de contenu cible) avant de prendre la capture d'écran.
  • HyperFrames plutôt que capture en direct. Le screencast CDP cesse d'émettre des images sur une page visuellement statique et fonctionne en dessous de la fréquence d'images nominale ; la création en HTML (GSAP) évite les deux. Si vous devez absolument enregistrer en direct, faites vibrer le curseur et encodez à la fréquence d'images effective.
  • Licence musicale. CC-BY (incompetech/Kevin MacLeod) nécessite une attribution dans la description du LP ; CC0 (Pixabay etc.) non. N'expédiez jamais un clip récupéré non licencié sur une page publiée.
  • Concaténation avec le filtre, pas le démultiplexeur si les segments ont des fréquences d'images variables — le démultiplexeur supprime silencieusement des images.

Extraction du système de design (image de marque agnostique)

La composition est neutre en termes de marque ; extract-design.mjs remplit ses variables CSS à partir de l'application cible elle-même : --bg (fond du body), --accent (couleur primaire/lien), --fg (couleur des titres), --font-hero/--font-mono (familles de polices calculées), --radius. C'est ce qui permet à un seul skill de produire des promos conformes à la marque pour n'importe quelle application sans choisir manuellement les tokens. Vérifiez toujours les tokens échantillonnés — une couleur à faible contraste ou ponctuelle peut occasionnellement être mal échantillonnée ; surchargez dans promo.config.design.

Erreurs

  • L'application ne s'authentifie pas en headless → la recette authInject de la configuration est incorrecte ; vérifiez que les tokens arrivent dans localStorage/cookies avant la première navigation.
  • Les écrans s'affichent vides → origine CORS (étape 1) ou attente des données (Règle) manquée.
  • Erreurs de rendu hors cadre → un vrai recadrage de texte nécessite une police plus petite / un retour à la ligne ; le débordement décoratif/de sortie est du bruit.
  • Surbrillance mal alignée → elle n'est pas un enfant du conteneur mis à l'échelle (Règle).

Composition avec le rôle de marketeur

Utilisez le rôle marketeur pour le texte : les accroches, les titres et le cadrage de valeur par séquence doivent suivre la voix du projet (launch-feature's voice.md / marketer-hooks.md quand ils sont présents). Limitez le texte à l'écran à une accroche + un court titre + une sous-ligne par séquence.

Skills associés