CLI HyperFrames
Exécutez les commandes sous la forme npx hyperframes ... sauf si les instructions du projet fournissent un wrapper. Obéissez au 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 en utilisant
/hyperframes-core. - Obtenez des retours rapides 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'appel lint autonome redondant. Ajoutez--snapshotspour des images d'aperçu 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, remettez l'URL du projet de timeline à l'utilisateur, et demandez s'il faut réviser ou rendre. - Rendu seulement après approbation : utilisez la qualité brouillon pour l'itération et la 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 rapide d'itération ; répétez au besoin pendant la rédaction.
npx hyperframes lint
# Porte finale obligatoire ; 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 de navigateur et un passage de recherche pour auditer les erreurs d'exécution, les requêtes échouées, la disposition, les assertions *.motion.json et le contraste WCAG. Les constats persistants conditionnent le code de sortie ; les constats transitoires à l'entrée ou à la sortie sont informatifs. Utilisez --strict pour conditionner les avertissements. validate, inspect, et layout restent des alias pour la compatibilité mais ne doivent pas apparaître dans les nouvelles instructions ou scripts.
Deux surfaces d'aperçu différentes
Ne confondez pas ces états :
| Surface | Quand elle peut s'ouvrir | Objectif |
|---|---|---|
| Tableau d'histoire | Avant les vérifications de composition, seulement si storyboard: yes | Examiner les fiches de plan et les croquis de maquette. Ouvrir ?view=storyboard#project/<nom>. |
| Aperçu final de composition | Après que check réussisse | 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 tous les échecs 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>
Traitez le contenu minuscule non stylé, 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 bloquant le rendu. Voir hyperframes-core/references/sub-compositions.md pour les correctifs correspondants.
Conventions pour les agents
-
Préférez
--jsonpour les appels d'agent et d'IC. Lesrender,preview, etplayen mode serveur ne fournissent pas de sortie JSON ordinaire ;preview --selection --jsonetpreview --context --jsonsont des exceptions en mode requête. -
doctor --jsonse termine toujours par zéro. Conditionnez-vous sur sa charge utile :npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Le mode non-TTY est automatique.
initnécessite--examplelà-bas ; utilisez--non-interactivepour forcer un comportement déterministe sur un TTY. -
Utilisez un
HYPERFRAMES_RUN_IDpour toutes les commandes dans la même boucle de vérification. -
Utilisez
--strict,--strict-all, et--strict-variableslorsque les avertissements, variables ou conditions CI correspondants doivent conditionner le rendu. -
Les chemins JSON masquent le répertoire personnel en tant que
$HOME; n'essayez pas d'inverser le 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 le Studio
Lorsque l'utilisateur fait référence à « cet élément » ou à la sélection en cours, interrogez le 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 rapporte 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 modifiables. 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 lots local piloté par variables | npx hyperframes render --batch rows.json --output "renders/{nom}.mp4" |
| Rendu 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 une exigence. Utilisez Cloud Run uniquement lorsque la propriété GCP est une exigence. Lisez la référence correspondante avant d'exécuter un 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 que l'utilisateur s'est désisté :
npx hyperframes feedback --rating <0-10> --comment "<résultat ou friction spécifique>"
Gardez les feedbacks pour une exécution propre concis. Pour tout bogue 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 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. Si le problème ne s'est pas reproduit, dites-le et incluez quand même la dernière commande ayant échoué et les logs. Utilisez --file-issue uniquement avec consentement : il publie une reproduction minimale sur une URL publique. Le format requis 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 suivantes et les compétences propriétaires 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, side-cars 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 du Studio d'un projet existant | references/beats.md |
preview, play, render, publish, contexte du Studio, feedback | references/preview-render.md |
doctor, gestion du navigateur | references/doctor-browser.md |
auth, rendu cloud hébergé par 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 aussi /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 la TTS, la transcription, les sous-titres ou les choix de 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 audience. beats est l'utilitaire autonome de grille de beats du Studio défini dans references/beats.md. keyframes expose des diagnostics de détection et de chemin de mouvement pour l'animation.