HyperFrames CLI
Tout s'exécute via npx hyperframes. Nécessite Node.js >= 22 et FFmpeg.
Workflow
- Scaffold —
npx hyperframes init my-video - Écrire — rédiger la composition HTML (voir la compétence
hyperframes) - Lint —
npx hyperframes lint - Aperçu —
npx hyperframes preview - Rendu —
npx hyperframes render
Effectuez le lint avant l'aperçu — cela détecte les data-composition-id manquants, les pistes qui se chevauchent, les timelines non enregistrées.
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 --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 les fichiers à la main.
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
Analyse index.html et tous les fichiers dans compositions/. Signale les erreurs (à corriger), les avertissements (devrait être corrigé) et les informations (avec --verbose).
Aperçu
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 dans votre navigateur automatiquement.
Rendu
npx hyperframes render # MP4 standard (sortie dans renders/ automatiquement)
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 # sortie identique octet par octet
| Option | Options | Par défaut | Remarques |
|---|---|---|---|
--output | chemin | renders/name_timestamp.mp4 | Chemin de sortie |
--fps | 24, 30, 60 | 30 | 60 ips 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 | flag | désactivé | Sortie reproductible |
--gpu | flag | désactivé | Encodage accéléré par GPU |
--strict | flag | désactivé | Échouer en cas d'erreurs de lint |
--strict-all | flag | désactivé | Échouer en cas d'erreurs ET d'avertissements |
Conseil 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 (Text-to-Speech)
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 Chrome intégré
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.
Pièges à éviter
Le chemin --out doit être un répertoire, pas un nom de fichier
npx hyperframes render --out renders/output.mp4 → ✗ erreur : "Not a directory"
npx hyperframes render → ✅ sortie dans renders/name_timestamp.mp4 automatiquement
Utilisez --output (pas --out) pour spécifier un chemin de fichier nommé.
La timeline racine index.html doit correspondre à data-composition-id de la sous-composition
Si index.html contient uniquement une référence data-composition-src (pas de contenu en ligne), vous avez quand même besoin d'un enregistrement window.__timelines qui correspond à un véritable data-composition-id. Bonne pratique : enregistrer window.__timelines['<sub-comp-id>'] = gsap.timeline({paused:true}) — mais comme les sous-compositions enregistrent leurs propres timelines, le bloc de script index.html n'est nécessaire que pour passer le lint. Utilisez l'identifiant de la sous-composition (pas 'root').
Le <div> de la sous-composition a besoin de data-start="0" et data-duration
Le <div data-composition-id="..."> à l'intérieur de <template> doit avoir data-start="0" et data-duration="N" sinon le lint émettra un avertissement et la lecture risque de ne pas démarrer.
Autres
npx hyperframes compositions # lister les compositions du projet
npx hyperframes docs # ouvrir la documentation
npx hyperframes benchmark . # évaluer les performances de rendu