Que fait HyperFrames CLI ?
Tout s'exécute via npx hyperframes. Nécessite Node.js >= 22 et FFmpeg.
Workflow
- Scaffold —
npx hyperframes init mon-projet - Écrire — composer la composition HTML (voir la compétence
hyperframes) - Lint —
npx hyperframes lint - Inspection visuelle —
npx hyperframes inspect - Prévisualisation —
npx hyperframes preview - Rendu —
npx hyperframes render
Lintez et inspectez avant la prévisualisation. lint détecte les data-composition-id manquants, les pistes qui se chevauchent et les timelines non enregistrées. inspect ouvre la composition rendue dans Chrome headless, parcourt la timeline et signale le texte qui dépasse des bulles/conteneurs ou du cadre.
Scaffold
npx hyperframes init mon-projet # assistant interactif
npx hyperframes init mon-projet --example warm-grain # choisir un exemple
npx hyperframes init mon-projet --video clip.mp4 # avec fichier vidéo
npx hyperframes init mon-projet --audio piste.mp3 # avec fichier audio
npx hyperframes init mon-projet --example blank --tailwind # avec Tailwind v4 runtime navigateur
npx hyperframes init mon-projet --non-interactive # ignorer les invites (CI/agents)
Modèles : blank, warm-grain, play-mode, swiss-grid, vignelli, decision-tree, kinetic-type, product-promo, nyt-graph.
init crée la bonne structure de fichiers, copie les médias, transcrit l'audio avec Whisper et installe les compétences de codage IA. Utilisez-le plutôt que de créer les fichiers à la main.
Lorsque vous utilisez --tailwind, invoquez la compétence tailwind avant de modifier les classes ou les jetons de thème. Le scaffold utilise Tailwind v4.2 via le runtime navigateur, pas la configuration Tailwind v3 de Studio.
Linting
npx hyperframes lint # répertoire courant
npx hyperframes lint ./mon-projet # projet spécifique
npx hyperframes lint --verbose # résultats de niveau info
npx hyperframes lint --json # lisible par machine
Linte index.html et tous les fichiers dans compositions/. Signale les erreurs (à corriger), les avertissements (à corriger de préférence) et les informations (avec --verbose).
Inspection visuelle
npx hyperframes inspect # inspecter la mise en page rendue sur la timeline
npx hyperframes inspect ./mon-projet # projet spécifique
npx hyperframes inspect --json # résultats lisibles par agent
npx hyperframes inspect --samples 15 # balayage de timeline plus dense
npx hyperframes inspect --at 1.5,4,7.25 # horodatages explicites des images clés
Utilisez cette commande après lint et validate, en particulier pour les compositions avec des bulles de dialogue, des cartes, des légendes ou une typographie serrée. Elle signale :
- Texte s'étendant à l'extérieur du conteneur visuel ou de la bulle le plus proche
- Texte coupé par sa propre boîte à largeur/hauteur fixe
- Texte s'étendant à l'extérieur du cadre de la composition
- Enfants s'échappant des conteneurs de rognage
Les erreurs doivent être corrigées avant le rendu. Les avertissements sont remontés pour examen par l'agent ; ajoutez --strict pour échouer également sur les avertissements. Les problèmes statiques répétés sont regroupés par défaut pour que la sortie JSON reste compacte pour les fenêtres de contexte LLM. Si le débordement est intentionnel pour une animation d'entrée/sortie, marquez l'élément ou l'ancêtre avec data-layout-allow-overflow. Si un élément décoratif ne doit jamais être audité, marquez-le avec data-layout-ignore.
npx hyperframes layout reste disponible comme alias de compatibilité pour la même passe d'inspection visuelle.
Prévisualisation
npx hyperframes preview # servir le répertoire courant
npx hyperframes preview --port 4567 # port personnalisé (par défaut 3002)
Recharge à chaud lors des modifications de fichiers. Ouvre le studio automatiquement dans votre navigateur.
Lorsque vous remettez un projet à l'utilisateur, utilisez l'URL du projet Studio, pas le chemin index.html source :
http://localhost:<port>/#project/<nom-du-projet>
Utilisez le port réel de la sortie de prévisualisation et le nom du répertoire du projet. Par exemple, après npx hyperframes preview --port 3017 dans codex-openai-video, signalez http://localhost:3017/#project/codex-openai-video.
Considérez index.html uniquement comme un contexte de code source. Il est acceptable de le lier en tant que fichier d'implémentation, mais ne l'étiquetez pas comme le projet ou la surface de prévisualisation.
Rendu
npx hyperframes render # MP4 standard
npx hyperframes render --output final.mp4 # sortie nommée
npx hyperframes render --quality draft # itération rapide
npx hyperframes render --fps 60 --quality high # livraison finale
npx hyperframes render --format webm # WebM transparent
npx hyperframes render --docker # identique octet par octet
| Option | Options | Défaut | Notes |
|---|---|---|---|
--output | chemin | renders/nom_timestamp.mp4 | Chemin de sortie |
--fps | 24, 30, 60 | 30 | 60fps double le temps de rendu |
--quality | draft, standard, high | standard | draft pour itérer |
--format | mp4, webm | mp4 | WebM prend en charge la transparence |
--workers | 1-8 ou auto | auto | Chacun lance Chrome |
--docker | drapeau | désactivé | Sortie reproductible |
--gpu | drapeau | désactivé | Encodage accéléré par GPU |
--strict | drapeau | désactivé | Échouer sur les erreurs de lint |
--strict-all | drapeau | désactivé | Échouer sur les erreurs ET les avertissements |
--variables | objet JSON | — | Remplacer les valeurs des variables déclarées dans data-composition-variables |
--variables-file | chemin | — | Fichier JSON avec les valeurs des variables (alternative à --variables) |
--strict-variables | drapeau | désactivé | Échouer le rendu sur les clés non déclarées ou les types incompatibles dans --variables |
Conseils de qualité : draft pendant l'itération, standard pour la révision, high pour la livraison finale.
Rendus paramétrés : la composition déclare ses variables sur la racine <html> avec data-composition-variables — un tableau JSON de déclarations ({id, type, label, default} par entrée) qui définit le schéma. Les scripts à l'intérieur lisent les valeurs résolues via window.__hyperframes.getVariables(). La CLI --variables '{"title":"Rapport Q4"}' est un objet JSON indexé par id qui remplace les valeurs par défaut déclarées pour un rendu ; les clés manquantes se rabattent sur les valeurs par défaut, de sorte que la même composition s'exécute inchangée en prévisualisation de développement et en production. (Les hôtes de sous-composition peuvent également remplacer par instance avec data-variable-values — même forme d'objet, limitée à un montage de la sous-composition. Voir la compétence hyperframes pour le modèle complet.)
Prétraitement des ressources
npx hyperframes tts, transcribe et remove-background produisent des ressources (audio de narration, transcriptions mot à mot, vidéo transparente) qui sont déposées dans une composition. Chacune télécharge son propre modèle lors de la première exécution. Pour la sélection de la voix, les règles du modèle Whisper (le piège .en-traduit-non-anglais), le choix du format de sortie (VP9 alpha WebM vs ProRes) et la chaîne TTS → transcription → sous-titres, invoquez la compétence hyperframes-media.
Dépannage
npx hyperframes doctor # vérifier l'environnement (Chrome, FFmpeg, Node, mémoire)
npx hyperframes browser # gérer Chrome fourni
npx hyperframes info # version et détails de l'environnement
npx hyperframes upgrade # vérifier les mises à jour
Exécutez doctor en premier si le rendu échoue. Problèmes courants : FFmpeg manquant, Chrome manquant, mémoire insuffisante.
Autres
npx hyperframes compositions # lister les compositions dans le projet
npx hyperframes docs # ouvrir la documentation
npx hyperframes benchmark . # comparer les performances de rendu