HyperFrames CLI
Exécutez les commandes sous la forme npx hyperframes ... sauf si les instructions du projet fournissent un wrapper. Suivez le wrapper lorsqu'il est présent. La CLI nécessite Node.js 22 ou plus récent et FFmpeg.
Boucle de développement
- Échafaudage :
npx hyperframes init <projet>ou capturez un site. En mode non-TTY, passez--non-interactive --example=<nom>. - Rédaction : écrivez la composition à l'aide de
/hyperframes-core. - Obtenez un retour rapide pendant l'édition : exécutez
npx hyperframes lintaprès le premier passage HTML et après les changements structurels. - Exécutez la porte finale : exécutez
npx hyperframes check; il relance lint avant d'ouvrir le navigateur. N'ajoutez pas d'invocation lint autonome redondante avant. Ajoutez--snapshotspour des images de synthèse annotées et la recherche de recadrages. - Inspectez les sous-compositions : lorsque
index.htmlmontedata-composition-src, capturez des instantanés à mi-parcours et inspectez chaque scène montée. - Ouvrez l'aperçu final du Studio : exécutez
npx hyperframes preview, donnez l'URL du projet de timeline à l'utilisateur, et demandez s'il faut réviser ou rendre. - Effectuez le rendu uniquement après approbation : utilisez la qualité brouillon pour l'itération et haute qualité pour la livraison.
- Vérifiez la sortie : confirmez que le fichier existe, n'est pas vide et a une durée plausible.
# Vérification d'itération rapide ; répétez pendant la rédaction si nécessaire.
npx hyperframes lint
# Porte finale requise ; inclut lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check exécute d'abord lint, puis utilise une session navigateur et un passage de recherche pour auditer les erreurs d'exécution, les requêtes échouées, la mise en page, les assertions *.motion.json et le contraste WCAG. Les constatations persistantes bloquent le code de sortie ; les constatations transitoires d'entrée ou de sortie sont informatives. Utilisez --strict pour bloquer les avertissements. validate, inspect et layout restent des alias pour la compatibilité mais ne doivent pas apparaître dans de nouvelles instructions ou scripts.
Deux surfaces d'aperçu différentes
Ne confondez pas ces états :
| Surface | Quand elle peut s'ouvrir | Objectif |
|---|---|---|
| Tableau de storyboard | Avant les vérifications de composition, uniquement si storyboard: yes | Examiner les fiches de plan et les croquis de maquette. Ouvrir ?view=storyboard#project/<nom>. |
| Aperçu final de la composition | Après la réussite de check | Examiner la timeline assemblée avant le rendu. Ouvrir #project/<nom>. |
Le tableau précoce n'est pas une approbation de la vidéo finale. Le rendu nécessite toujours l'approbation finale définie par hyperframes-core/references/review-loop.md.
Test de fumée des sous-compositions
Les audits statiques ne peuvent pas détecter toutes les défaillances de montage. Lorsque le projet utilise des sous-compositions, capturez au moins un point médian visible pour chaque emplacement hôte :
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Considérez le contenu minuscule non stylisé, les icônes de taille de canevas, les éléments héros manquants ou les délais d'enregistrement de timeline comme des défauts de montage bloquants le rendu. Voir hyperframes-core/references/sub-compositions.md pour les corrections correspondantes.
Conventions pour l'agent
-
Préférez
--jsonpour les appels d'agent et CI. Le mode serveurrender,previewetplayne fournissent pas de sortie JSON ordinaire ;preview --selection --jsonetpreview --context --jsonsont des exceptions de mode requête. -
doctor --jsonse termine toujours par zéro. Bloquez sur sa charge utile :npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Le mode non-TTY est automatique.
initnécessite--exampledans ce cas ; utilisez--non-interactivepour forcer un comportement déterministe sur un TTY. -
Utilisez un seul
HYPERFRAMES_RUN_IDpour toutes les commandes dans la même boucle de vérification. -
Utilisez
--strict,--strict-allet--strict-variableslorsque les avertissements, variables ou conditions CI correspondants doivent bloquer le rendu. -
Les chemins JSON masquent le répertoire personnel sous la forme
$HOME; n'essayez pas d'inverser ce masquage. -
Ne rendez jamais simplement parce que les vérifications réussissent. Faites une pause à l'aperçu final et attendez l'approbation.
Modifications dirigées par Studio
Lorsque l'utilisateur fait référence à « cet élément » ou à la sélection en cours, interrogez Studio au lieu de deviner :
npx hyperframes preview --context --json --context-fields selection
Utilisez selection.target.hfId lorsqu'il est disponible, sinon son sélecteur et son fichier source. Si le résultat signale no-selection, demandez à l'utilisateur de cliquer sur l'élément et de réexécuter. Ne demandez que les tranches de contexte dont vous avez besoin ; utilisez --context-detail full uniquement pour les styles calculés ou les métadonnées de texte modifiable. Le comportement complet et les codes d'échec se trouvent dans references/preview-render.md.
Choix de rendu
| Besoin | Commande |
|---|---|
| Itération locale rapide | npx hyperframes render --quality draft |
| Livraison locale finale | npx hyperframes render --quality high --output out.mp4 |
| Rendu conteneur reproductible | npx hyperframes render --docker --strict --output out.mp4 |
| Rendu par lot local piloté par variables | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Rendu cloud hébergé HeyGen sans infrastructure | npx hyperframes cloud render |
| Rendu AWS distribué auto-géré | npx hyperframes lambda render <projet> --width 1920 --height 1080 --wait |
| Rendu GCP distribué auto-géré | npx hyperframes cloudrun render <projet> --width 1920 --height 1080 --wait |
Utilisez le rendu cloud lorsque l'utilisateur souhaite un rendu hébergé sans Chrome local, FFmpeg ou AWS. Utilisez Lambda uniquement lorsque la propriété AWS est requise. Utilisez Cloud Run uniquement lorsque la propriété GCP est requise. Lisez la référence correspondante avant d'exécuter tout chemin cloud.
Après avoir vérifié un rendu réussi, envoyez un rapport de feedback sauf si la télémétrie est désactivée ou si l'utilisateur s'est désinscrit :
npx hyperframes feedback --rating <0-10> --comment "<résultat spécifique ou friction>"
Gardez le feedback pour une exécution propre concis. Pour tout bug ou friction, capturez un paquet de reproduction avant de soumettre ; n'envoyez pas seulement un résumé des symptômes. Incluez la commande réexécutable et le répertoire de travail, le comportement attendu par rapport au comportement réel, l'erreur exacte, si la sortie est terminée/repliée/échouée, la solution de contournement et l'état du projet de reproduction. Pour une note ≤ 7 décrivant un défaut visuel (image noire, scintillement, sortie corrompue, mauvais cadre, sortie vide, autre anomalie visuelle), incluez également un bloc COMPOSITION_STRUCTURE: — une anatomie structurelle respectueuse de la vie privée (recensement des éléments + présence d'attributs + forme de la timeline) afin que les responsables puissent faire correspondre des schémas avec des familles de bugs connues sans le ZIP de la composition. Les agents remplissent automatiquement ce bloc via l'assistant de recensement de composition ; l'utilisateur humain ne le remplit pas manuellement. Si le problème ne s'est pas reproduit, dites-le et incluez quand même la dernière commande et les derniers logs. Utilisez --file-issue uniquement avec consentement : il publie une reproduction minimale sur une URL publique. Le format obligatoire du paquet et l'avertissement de confidentialité se trouvent dans references/preview-render.md.
Lisez la référence correspondante avant d'exécuter une commande
Les références et compétences propriétaires suivantes sont des contrats de commande obligatoires, pas une lecture de fond optionnelle. Avant d'exécuter une commande dans le tableau, lisez sa ligne correspondante.
| Besoin | Référence |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, sidecars de mouvement, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch piloté par variables | references/compare-and-batch.md |
beats pour la grille de beats Studio d'un projet existant | references/beats.md |
preview, play, render, publish, contexte Studio, feedback | references/preview-render.md |
doctor, gestion du navigateur | references/doctor-browser.md |
auth, rendu cloud hébergé HeyGen et variables de modèle | references/cloud.md |
| Déploiement et rendu AWS Lambda | references/lambda.md |
| Déploiement et rendu Google Cloud Run | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, télémétrie, prétraitement média | references/upgrade-info-misc.md |
Pour les variables de composition, lisez également /hyperframes-core → references/variables-and-media.md. Pour hyperframes add et hyperframes catalog, utilisez /hyperframes-registry. Avant hyperframes present, lisez /slideshow ; avant hyperframes keyframes, lisez /hyperframes-keyframes. Pour les choix TTS, transcription, sous-titres ou suppression d'arrière-plan, utilisez /media-use.
Les commandes spécialisées sont délibérément documentées par leurs workflows propriétaires :
npx hyperframes present <répertoire-projet> --port 3004 --no-open
npx hyperframes beats <répertoire-projet> --json
npx hyperframes keyframes <répertoire-projet> --json
present sert un deck navigable avec synchronisation présentateur et public. beats est l'utilitaire autonome de grille de beats Studio défini dans references/beats.md. keyframes expose des diagnostics d'animation et de chemin de mouvement sûrs pour la recherche.