Manuel d'utilisation

Du prompt à la vidéo avec le skill HyperFrames

HyperFrames rend de la vidéo à partir de HTML. Le skill /hyperframes apprend à votre agent de code (Claude Code, Codex, Cursor…) à écrire ces compositions, à les vérifier, à les prévisualiser et à les rendre en MP4.

• HTMLUne composition est un fichier HTML dont le DOM déclare son minutage avec des attributs data-*.
• 1 entrée/hyperframes lit l'état du projet, cadre la demande et choisit le bon workflow.
• 4 gestesDemander, vérifier (check), prévisualiser (Studio), rendre (render).

Ce manuel suit un exemple réel de bout en bout : une intro de 15 secondes en trois scènes, créée, vérifiée, prévisualisée et rendue sur macOS avec Node 22 et la CLI hyperframes 0.8.149. Toutes les captures de terminal reproduisent les sorties réellement obtenues ; les captures de Studio sont de vraies captures du navigateur.

Prérequis

La CLI demande Node.js 22 ou plus récent et FFmpeg. Il n'y a rien à installer globalement : toutes les commandes passent par npx hyperframes ….

node -v
ffmpeg -version
npx hyperframes doctor

Installation du skill

HyperFrames installe d'office un socle — /hyperframes, les skills de domaine hyperframes-* et /media-use — et n'installe les workflows (un par type de vidéo) qu'au moment où vous en avez besoin.

# Installer les skills HyperFrames pour votre agent
npx hyperframes skills

# Sans la CLI : même résultat avec l'installeur de skills
npx skills add heygen-com/hyperframes --all

# Vérifier ce qui est installé et à jour
npx hyperframes skills check

Votre première vidéo, pas à pas

L'exemple : « une intro de 15 secondes sur HyperFrames ». Vous écrivez la demande, l'agent fait le reste en suivant le skill ; les commandes ci-dessous sont celles qu'il exécute (et que vous pouvez lancer vous-même).

1

Créer le projet

npx hyperframes init demo-video

Le projet contient index.html (la composition racine), hyperframes.json, package.json (scripts épinglés sur la version de la CLI), meta.json et les consignes pour l'agent (CLAUDE.md, AGENTS.md).

Option	Usage
--resolution portrait	1080×1920. Aussi : landscape (1920×1080), square, et leurs variantes -4k.
--example warm-grain	Partir d'un exemple : warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
--video clip.mp4 / --audio piste.mp3	Démarrer avec un média (transcrit automatiquement avec Whisper).
--tailwind	Projet avec le runtime navigateur de Tailwind v4.

---
workflow: general-video
flow: automation
storyboard: no
message: "Avec HyperFrames, une page HTML devient une vidéo"
aspect: 1920x1080
language: fr
length: 15s
---

## Intent

Une intro de 15 secondes qui sert de fil rouge au manuel…

3

Le workflow s'installe à la demande

npx hyperframes skills update general-video

Si cette commande échoue, l'agent doit vous le dire plutôt que d'improviser le workflow de mémoire — voir Dépannage pour le cas le plus courant.

## Frame 2 — Trois gestes

- scene: Trois colonnes numérotées — écrire, prévisualiser, rendre
- duration: 6s
- transition_in: cut
- status: animated
- src: compositions/etapes.html

5

La composition : du HTML minuté

La racine index.html ne contient que des emplacements minutés ; chaque scène vit dans son propre fichier, chargé par data-composition-src.

<div id="root" data-composition-id="main"
     data-start="0" data-duration="15" data-width="1920" data-height="1080">

  <div class="clip"
       data-composition-id="intro"
       data-composition-src="compositions/intro.html"
       data-start="0" data-duration="5"
       data-track-index="1" data-track-kind="graphics"
       data-width="1920" data-height="1080"></div>
  <!-- etapes : 5 → 11 s · final : 11 → 15 s -->
</div>

Dans une scène, tout — styles, balisage, script — se place à l'intérieur de <template>, et l'animation est une timeline GSAP en pause, enregistrée sous l'identifiant de la composition :

<template>
  <style> #root { position: absolute; inset: 0; } </style>
  <div id="root" data-composition-id="intro" data-width="1920" data-height="1080">…</div>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.fromTo("#intro-sub", { opacity: 0, x: -30 }, { opacity: 1, x: 0, duration: 0.5 }, 1.25);
    window.__timelines["intro"] = tl;
  </script>
</template>

Règle d'or : le déterminisme. Chaque image doit dépendre uniquement de son instant : pas de Date.now(), pas de Math.random() sans graine, pas de requête réseau au rendu, et la durée finale est celle du data-duration de la racine.

Avant d'animer à la main, l'agent cherche un effet tout prêt dans le catalogue (446 blocs et composants), en décrivant l'effet voulu en anglais, puis l'installe avec add :

npx hyperframes catalog --query "reveal a headline one line at a time"
npx hyperframes add line-by-line-slide

6

Vérifier : lint puis check

# Retour rapide pendant l'écriture
npx hyperframes lint

# Contrôle final : lint + exécution + mise en page + mouvement + contraste
npx hyperframes check --snapshots

Avec --snapshots, check enregistre aussi des images clés dans snapshots/. Lors de la première passe de cet exemple, il a signalé deux avertissements réels — un halo décoratif qui déborde du cadre et une barre de commande trop étroite — corrigés avant la preview. Un débordement voulu se déclare avec data-layout-allow-overflow.

7

Prévisualiser dans Studio

npx hyperframes preview --background --port 3017

Studio est un véritable éditeur : cliquez un élément pour le modifier, éditez le texte, déplacez et rognez les clips ; chaque modification est enregistrée dans les fichiers du projet. Le bouton des marges affiche les deux cadres de sécurité : 90 % pour l'action, 80 % pour les titres.

Pour dire « change cet élément » à l'agent, sélectionnez-le dans Studio ; l'agent lit la sélection, puis vous arrêtez le serveur quand la revue est finie :

npx hyperframes preview --context --json --context-fields selection
npx hyperframes preview --stop

8

Rendre en MP4

Le rendu ne se lance qu'après votre accord sur la preview — jamais simplement parce que les contrôles passent.

npx hyperframes render --quality looks --output out.mp4

Qualité	Quand
--quality draft	Itérations rapides.
--quality looks	Premier vrai encodage (valeur par défaut).
--quality delivery	Livraison finale.

Vérifiez toujours le fichier produit :

ffprobe -v error -show_format -show_streams out.mp4

Autres formats : --format webm ou mov (transparence), gif, png-sequence, hls ; --fps 24|30|60 ; --docker pour un rendu reproductible.

Les 10 workflows

Pour une création, /hyperframes retient la première ligne qui correspond au livrable demandé — pas à un mot ou à un type de fichier cité en passant.

Sur un projet existant, le skill ne repose pas les questions : une retouche précise est appliquée directement, et une opération isolée (vérifier, prévisualiser, rendre, publier) est exécutée seule.

Skills de domaine

Le workflow charge ces skills au fil de l'eau ; vous pouvez aussi les invoquer vous-même.

Aide-mémoire CLI

Studio et l'application desktop

La preview Studio permet déjà de tout modifier à la main et d'exporter. Ce qu'elle ne fait pas : dialoguer — son bouton « Ask agent » copie simplement un prompt à coller dans votre conversation.

L'application desktop HyperFrames (gratuite) ajoute un assistant, Framey, qui modifie la vidéo depuis un chat et sur lequel on peut dessiner pour désigner un élément. Depuis Studio, le bouton Edit with Framey y conduit ; depuis le terminal :

# Ouvrir le projet dans l'application desktop
npx hyperframes open

# De retour dans votre agent : ce qui a été demandé et modifié dans l'application
npx hyperframes catch-up

Un projet lisible dans Studio

• Chaque scène est une sous-composition : sinon elle devient une ligne opaque, impossible à rogner partie par partie.
• Une seule piste de sous-titres, marquée data-track-kind="captions".
• Un type d'élément par piste : vidéo, graphismes, sous-titres, audio.
• Marges de sécurité : tout le visible dans 90 % du cadre, les titres et contenus clés dans 80 %.

Dépannage

« Clone timed out after 300s » à l'installation d'un workflow

Rencontré pendant la rédaction de ce manuel : le dépôt des skills est volumineux et le clonage a dépassé le délai par défaut.

SKILLS_CLONE_TIMEOUT_MS=1200000 npx hyperframes skills update general-video

La scène s'affiche en tout petit, sans style

Dans une sous-composition, seul le contenu de <template> est transporté : un <style> ou un <script> laissé dans <head> est ignoré.

Aucune animation, le rendu attend 45 s par scène

Le data-composition-id de l'emplacement, celui de la racine du fichier chargé et la clé de window.__timelines[…] doivent être identiques.

check annonce « 0 sample(s) » et « 0/0 text checks »

Ce n'est pas un succès : une erreur de lint désactive les audits de mise en page et de contraste. Corrigez d'abord le lint.

Le projet utilise une ancienne version de la CLI

Les scripts de package.json épinglent une version pour que les rendus restent reproductibles ; elle n'avance jamais seule.

npx hyperframes@latest upgrade --project . --check
npx hyperframes@latest upgrade --project .
npx hyperframes check

La recherche dans le catalogue ne renvoie rien

Le catalogue est indexé en anglais : décrivez l'effet en anglais, même si la vidéo est en français.

Vidéos

Deux résumés du parcours, installation puis utilisation, avec les explications affichées à l'écran.

Ces deux vidéos ont elles-mêmes été réalisées avec le skill HyperFrames ; leur musique de fond a été générée en local.