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 framework gère la visibilité des clips, la lecture des médias et la synchronisation de la timeline.
Intégration Open Design (essentiel pour cette surface)
Lorsque cette compétence s'exécute dans Open Design (c'est-à-dire que $OD_PROJECT_DIR est défini), le flux de sortie est fixe : seul le fichier .mp4 rendu doit atterrir dans la racine du projet. Les fichiers sources de la composition (hyperframes.json, meta.json, index.html, assets) appartiennent à un répertoire de cache caché pour ne pas encombrer le FileViewer de l'utilisateur ou les « fichiers produits » du chat.
Flux de travail de rendu dans OD — chemin rapide :
Pour la plupart des requêtes OD (« vidéo test », « présentation produit 5s », « clip démo »), N'ÉCRIVEZ PAS le HTML de composition à partir de zéro. Utilisez l'échafaudage intégré d'HyperFrames et modifiez uniquement ce que la demande change réellement. Le chemin « création à partir de zéro » coûte des minutes de sortie du modèle et du temps d'outil de chat silencieux ; le chemin d'échafaudage coûte quelques secondes.
# 1. Choisissez un emplacement de cache caché. Le préfixe de fichier dot → la liste
# des fichiers du projet OD l'ignore, donc les fichiers sources n'encombrent jamais le chat.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. Obtenez un échafaudage directement rendu (hyperframes.json,
# meta.json, index.html avec CDN GSAP + window.__timelines.main
# déjà enregistré). Cela s'exécute dans votre shell — copie de fichier pure,
# pas de Chrome, pas de réseau au-delà du cache npx.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. Modifiez UNIQUEMENT $COMP/index.html — changez `data-duration` sur la racine
# si vous avez besoin d'une longueur non par défaut, remplacez la palette
# d'espace réservé dans <style>, ajoutez 1 à 3 <div> de clips pour le texte/l'image,
# et ajoutez les tweens GSAP correspondants dans le bloc existant
# `window.__timelines["main"] = gsap.timeline({paused:true})`.
# Gardez les modifications minimales ; l'échafaudage est déjà un HF valide.
# 4. Lancez le rendu via le démon OD. N'exécutez PAS `npx hyperframes
# render` depuis ce shell — le démon l'exécute pour vous dans un
# processus non sandboxé. (De nombreux CLI d'agents, Claude Code en particulier,
# encapsulent Bash dans sandbox-exec de macOS sous lequel le sous-processus Chrome
# de puppeteer se bloque en cours de capture d'image. Le processus du démon
# n'est pas sandboxé, donc les rendus se terminent de manière fiable.)
#
# Le dispatcher renvoie en ~1s un {taskId} ; pilotez le
# rendu jusqu'à son terme en bouclant les appels `od media wait <taskId>`.
# Chaque appel fait un long-poll jusqu'à 25s (bien en dessous du plafond
# par défaut de 30s de votre outil shell) et se termine avec 0/2/5 pour
# signifier terminé/en cours/échec.
out=$(node "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<nom-descriptif>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$(node "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
Chaque appel generate et chaque appel wait dure au maximum ~25s, donc le plafond par défaut de ~30s de l'outil shell de l'agent ne se déclenche jamais. Les lignes de progression de HF (Capturing frame N/M) sont diffusées sur stderr en direct tout au long de la boucle. Lorsque le rendu se termine, la dernière ligne stdout est {"file": { "name": "<output>", "size": …, "kind": "video", … }} — citez file.name dans votre réponse pour que l'utilisateur sache ce qui a été produit.
Ignorer la Porte d'Identité Visuelle dans OD. La section HARD-GATE ci-dessous (sous « Approche ») vous dit de lire DESIGN.md / visual-style.md ou de vous arrêter et de poser 3 questions d'ambiance avant d'écrire une composition. Cette porte concerne les projets HF autonomes. Les projets OD ont déjà leur propre couche de système de conception — l'utilisateur a choisi sa direction visuelle lors de la création du projet. Pour un rendu test OD, par défaut : toile sombre (#0b0b0f), un accent chaud (#ffb76b), un accent froid (#7da4ff), mouvement sobre. Ne demandez une contribution stylistique que si la demande de l'utilisateur est trop vague pour même choisir un sujet (très rare).
Quand sauter l'échafaudage et écrire à partir de zéro : seulement lorsque l'utilisateur demande explicitement quelque chose que le modèle vierge ne peut clairement pas accueillir (par exemple, timelines multi-composition, incrustations audio-réactives, sous-titres synchronisés avec une piste TTS qu'ils ont déjà générée). Pour tout le reste, init + modification est le chemin par défaut.
Les sous-commandes HF plus légères que vous POUVEZ toujours exécuter depuis votre propre shell (elles n'ont pas besoin de lancer Chrome) :
npx hyperframes lint "$COMP"— valider la composition avant envoinpx hyperframes transcribe <audio>— générer des sous-titresnpx hyperframes tts <texte>— générer une narration
Réservez l'envoi via le démon pour render/inspect/preview (tout ce qui nécessite Chrome).
N'appelez PAS od media generate --model hyperframes-html — ce chemin de dispatcher renvoie un 400 (AGENT_RENDERED) exprès. HyperFrames est rendu par vous directement via npx.
Ne placez PAS hyperframes.json / meta.json / index.html dans la racine du projet ; la liste des fichiers OD scanne récursivement et l'utilisateur verrait trois fichiers sans rapport apparaître dans le chat.
Pour les options CLI au-delà de render (lint, preview, transcribe, tts, inspect, benchmark) appelez-les directement depuis votre outil shell lorsque la tâche le justifie (par exemple, générer un audio TTS dans le cache avant de le référencer depuis la composition).
Approche
Avant d'écrire du HTML, pensez à un haut niveau :
- Quoi — que doit vivre le spectateur ? Identifiez l'arc narratif, les moments clés et les battements émotionnels.
- Structure — combien de compositions, lesquelles sont des sous-compositions ou en ligne, quelles pistes portent quoi (vidéo, audio, incrustations, sous-titres).
- Timing — quels clips pilotent la durée, où atterrissent les transitions, quel est le rythme.
- Mise en page — construisez d'abord l'état final. Voir « Mise en page avant l'animation » ci-dessous.
- Animer — puis ajoutez du mouvement en utilisant les règles ci-dessous.
Pour les petites modifications (corriger une couleur, ajuster le timing, ajouter un élément), passez directement aux règles.
Porte d'Identité Visuelle
Vérifiez dans cet ordre :
- DESIGN.md existe dans le projet ? → Lisez-le. Utilisez ses couleurs, polices, règles de mouvement et contraintes « Ce qu'il ne faut PAS faire » exactes.
- visual-style.md existe ? → Lisez-le. Appliquez son
style_prompt_fullet ses champs structurés. (Note :visual-style.mdest un fichier spécifique au projet.visual-styles.mdest la bibliothèque de styles avec 8 presets nommés — fichiers différents.) - L'utilisateur a nommé un style (par exemple, « Swiss Pulse », « dark and techy », « marque de luxe ») ? → Lisez visual-styles.md pour les 8 presets nommés. Générez un DESIGN.md minimal avec :
## Style Prompt(un paragraphe),## Colors(3-5 valeurs hexadécimales avec rôles),## Typography(1-2 familles de polices),## What NOT to Do(3-5 anti-patrons). - Rien de ce qui précède ? → Posez 3 questions avant d'écrire du HTML :
- Quelle est l'ambiance ? (explosive / cinématographique / fluide / technique / chaotique / chaleureuse)
- Toile claire ou sombre ?
- Des couleurs de marque, polices ou références visuelles spécifiques ? Générez ensuite un DESIGN.md minimal à partir des réponses.
Chaque composition doit faire remonter sa palette et sa typographie à un DESIGN.md, visual-style.md ou une directive explicite de l'utilisateur. Si vous utilisez #333, #3b82f6 ou Roboto — vous avez sauté cette étape.
Pour les paramètres par défaut du mouvement, le dimensionnement, les motifs d'entrée et les courbes d'assouplissement — suivez house-style.md. Le style maison gère COMMENT les choses bougent. Le DESIGN.md gère À QUOI ressemblent les choses.
Mise en page avant l'animation
Positionnez chaque élément là où il doit être à son moment le plus visible — l'image où il est complètement entré, correctement placé et pas encore en train de sortir. Écrivez cela en HTML+CSS statique d'abord. Pas encore de GSAP.
Pourquoi c'est important : Si vous positionnez les éléments à leur état de départ animé (hors écran, mis à l'échelle à 0, opacité 0) et que vous les animez jusqu'à l'endroit où vous pensez qu'ils devraient atterrir, vous devinez la mise en page finale. Les chevauchements sont invisibles jusqu'à ce que la vidéo soit rendue. En construisant l'état final d'abord, vous pouvez voir et corriger les problèmes de mise en page avant d'ajouter du mouvement.
Le processus
- Identifiez l'image héroïque pour chaque scène — le moment où le plus d'éléments sont simultanément visibles. C'est la mise en page que vous construisez.
- Écrivez du CSS statique pour cette image. Le conteneur
.scene-contentDOIT remplir la scène entière en utilisantwidth: 100%; height: 100%; padding: Npx;avecdisplay: flex; flex-direction: column; gap: Npx; box-sizing: border-box. Utilisez le padding pour pousser le contenu vers l'intérieur — JAMAISposition: absolute; top: Npxsur un conteneur de contenu. Les conteneurs de contenu positionnés en absolu débordent lorsque le contenu est plus haut que l'espace restant. Réservezposition: absoluteuniquement pour les éléments décoratifs. - Ajoutez les entrées avec
gsap.from()— animez DEPUIS hors écran/invisible VERS la position CSS. La position CSS est la vérité terrain ; le tween décrit le voyage pour y arriver. - Ajoutez les sorties avec
gsap.to()— animez VERS hors écran/invisible DEPUIS la position CSS.
Exemple
/* scene-content remplit la scène, le padding positionne le contenu */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* Le conteneur remplit toute taille de scène (1920x1080, 1080x1920, etc.).
Le padding positionne le contenu. Flex + gap gère l'espacement. */
MAUVAIS — dimensions codées en dur et positionnement absolu :
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// Étape 3 : Animer VERS ces positions
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// Étape 4 : Animer DEPUIS ces positions
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
Lorsque les éléments partagent l'espace dans le temps
Si l'élément A sort avant que l'élément B n'entre dans la même zone, les deux doivent avoir des positions CSS correctes pour leurs images héroïques respectives. L'ordre de la timeline garantit qu'ils ne coexistent jamais visuellement — mais si vous sautez l'étape de mise en page, vous ne détecterez pas le cas où ils se chevauchent accidentellement en raison d'une erreur de timing.
Ce qui compte comme chevauchement intentionnel
Les effets superposés (lueur derrière le texte, éléments d'ombre, motifs d'arrière-plan) et les conceptions empilées en z (piles de cartes, couches de profondeur) sont intentionnels. L'étape de mise en page consiste à détecter les chevauchements non intentionnels — deux titres atterrissant l'un sur l'autre, une statistique couvrant une étiquette, du contenu débordant hors de l'image.
Attributs de données
Tous les clips
| Attribut | Requis | Valeurs |
|---|---|---|
id | Oui | Identifiant unique |
data-start | Oui | Secondes ou référence d'ID de clip ("el-1", "intro + 2") |
data-duration | Requis pour img/div/compositions | Secondes. La vidéo/l'audio par défaut utilisent la durée du média. |
data-track-index | Oui | Entier. Les clips de la même piste ne peuvent pas se chevaucher. |
data-media-start | Non | Décalage de coupe dans la source (secondes) |
data-volume | Non | 0-1 (par défaut 1) |
data-track-index n'affecte pas la superposition visuelle — utilisez CSS z-index.
Clips de composition
| Attribut | Requis | Valeurs |
|---|---|---|
data-composition-id | Oui | ID de composition unique |
data-start | Oui | Heure de début (composition racine : utilisez "0") |
data-duration | Oui | Prédomine sur la durée de la timeline GSAP |
data-width / data-height | Oui | Dimensions en pixels (1920x1080 ou 1080x1920) |
data-composition-src | Non | Chemin vers un fichier HTML externe |
Structure de la composition
Les sous-compositions chargées via data-composition-src utilisent un wrapper <template>. Les compositions autonomes (le index.html principal) n'utilisent PAS <template> — elles placent la div data-composition-id directement dans <body>. L'utilisation de <template> sur un fichier autonome cache tout le contenu du navigateur et casse le rendu.
Structure de sous-composition :
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- contenu -->
<style>
[data-composition-id="my-comp"] {
/* styles isolés */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// tweens...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
Chargement dans la racine : <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
Vidéo
…
[tronqué pour la traduction]