CLI HyperFrames
Tout s'exécute via npx hyperframes. Nécessite Node.js >= 22 et FFmpeg.
Workflow
- Échafaudage —
npx hyperframes init my-video - Écrire — composer du HTML (voir la compétence
hyperframes) - Linter —
npx hyperframes lint - Inspection visuelle —
npx hyperframes inspect - Aperçu —
npx hyperframes preview - Rendu —
npx hyperframes render
Linter et inspecter avant l'aperçu. 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 sans tête, parcourt la timeline et signale le texte qui déborde des bulles/conteneurs ou du canevas.
Échafaudage
npx hyperframes init my-video # assistant interactif
npx hyperframes init my-video --example warm-grain # choisir un exemple
npx hyperframes init my-video --video clip.mp4 # avec fichier vidéo
npx hyperframes init my-video --audio track.mp3 # avec fichier audio
npx hyperframes init my-video --example blank --tailwind # avec Tailwind v4 runtime navigateur
npx hyperframes init my-video --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 structure de fichiers appropriée, 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 des fichiers manuellement.
Lors de l'utilisation de --tailwind, invoquez la compétence tailwind avant de modifier les classes ou les jetons de thème. L'échafaudage 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 ./my-project # projet spécifique
npx hyperframes lint --verbose # résultats informatifs
npx hyperframes lint --json # lisible par machine
Analyse index.html et tous les fichiers dans compositions/. Signale les erreurs (à corriger), les avertissements (à considérer) et les informations (avec --verbose).
Inspection visuelle
npx hyperframes inspect # inspecte la disposition rendue sur la timeline
npx hyperframes inspect ./my-project # 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 héroïques explicites
À utiliser après lint et validate, en particulier pour les compositions avec bulles de parole, cartes, légendes ou typographie serrée. 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 en dehors du canevas de la composition
- Enfants s'échappant des conteneurs de découpe
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 réduits par défaut afin que la sortie JSON reste compacte pour les fenêtres de contexte LLM. Si un 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.
Aperçu
npx hyperframes preview # sert le répertoire courant
npx hyperframes preview --port 4567 # port personnalisé (défaut 3002)
Rechargement à chaud lors des modifications de fichiers. Ouvre automatiquement le studio dans votre navigateur.
Lorsque vous remettez un projet à l'utilisateur, utilisez l'URL du projet Studio, pas le chemin source index.html :
http://localhost:<port>/#project/<nom-du-projet>
Utilisez le port réel de la sortie d'aperçu 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.
Traitez index.html uniquement comme contexte de code source. Il est acceptable de le lier comme fichier d'implémentation, mais ne le qualifiez pas de projet ou de surface d'aperçu.
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
| Drapeau | Options | Défaut | Remarques |
|---|---|---|---|
--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 supporte la transparence |
--workers | 1-8 ou auto | auto | Chaque spawn 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 de variables déclarées dans data-composition-variables |
--variables-file | chemin | — | Fichier JSON avec valeurs de 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 |
Conseil de qualité : draft pour itérer, 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 internes lisent les valeurs résolues via window.__hyperframes.getVariables(). La CLI **`--variables '{