CLI HyperFrames
Tout se fait via npx hyperframes. Nécessite Node.js >= 22 et FFmpeg.
Workflow
- Scaffolder —
npx hyperframes init my-video - Écrire — composer une composition HTML (voir le skill
hyperframes) - Linter —
npx hyperframes lint - Inspecter visuellement —
npx hyperframes inspect - Prévisualiser —
npx hyperframes preview - Rendre —
npx hyperframes render
Lintez et inspectez avant la prévisualisation. lint détecte les data-composition-id manquants, les chevauchements de pistes 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épasse des bulles/conteneurs ou du canevas.
Scaffolding
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. À utiliser plutôt que de créer les fichiers manuellement.
En utilisant --tailwind, faites appel au skill 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 du Studio.
Linting
npx hyperframes lint # répertoire courant
npx hyperframes lint ./my-project # projet spécifique
npx hyperframes lint --verbose # résultats au niveau info
npx hyperframes lint --json # lisible par machine
Lint index.html et tous les fichiers dans compositions/. Signale les erreurs (à corriger impérativement), les avertissements (devraient être corrigés) et les informations (avec --verbose).
Inspection visuelle
npx hyperframes inspect # inspecter la disposition rendue dans 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 plus dense de la timeline
npx hyperframes inspect --at 1.5,4,7.25 # horodatages explicites des images clés
Utilisez cette commande après lint et validate, surtout pour les compositions contenant des bulles de discours, des cartes, des légendes ou une typographie serrée. Elle signale :
- Le texte qui dépasse du conteneur visuel ou de la bulle le plus proche
- Le texte rogné par sa propre boîte à largeur/hauteur fixe
- Le texte qui s'étend en dehors du canevas de la composition
- Les éléments enfants qui s'échappent des conteneurs avec 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 afin 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.
Lors de la remise d'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 affiché par la 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 contexte de code source. Il est acceptable de le lier en tant que fichier d'implémentation, mais ne l'étiquetez pas comme projet ou 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
| Drapeau | Options | Par 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 avertissements |
Conseils de qualité : draft pendant l'itération, standard pour la révision, high pour la livraison finale.
Transcription
npx hyperframes transcribe audio.mp3
npx hyperframes transcribe video.mp4 --model medium.en --language en
npx hyperframes transcribe subtitles.srt # importer existant
npx hyperframes transcribe subtitles.vtt
npx hyperframes transcribe openai-response.json
Synthèse vocale (TTS)
npx hyperframes tts "Texte ici" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma
npx hyperframes tts --list # afficher toutes les voix
Dépannage
npx hyperframes doctor # vérifier l'environnement (Chrome, FFmpeg, Node, mémoire)
npx hyperframes browser # gérer le Chrome intégré
npx hyperframes info # détails de version et d'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 du projet
npx hyperframes docs # ouvrir la documentation
npx hyperframes benchmark . # benchmarker les performances de rendu