CLI HyperFrames
Exécutez les commandes comme 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
- Initialisation :
npx hyperframes init <projet>(vierge centrée). Ou capturez un site. Passez--example=<nom>uniquement pour partir d'un exemple nommé. - Trouver le mouvement : si la demande nomme un asset, un son, une image, une voix ou une modification visuelle rapide, résolvez-la via
/media-useavant de proposer un plan. Sinon, avant d'écrire un mouvement à la main, recherchez une primitive qui le fait déjà :npx hyperframes catalog --query "révéler un titre une ligne à la fois". Demandez l'effet que vous souhaitez plutôt que le mécanisme que vous avez en tête. Installez avecnpx hyperframes add <nom>(voir/hyperframes-registry). Écrivez à la main uniquement si rien ne correspond. - Écrire : rédigez la composition en utilisant
/hyperframes-core. Pour savoir ce qui se trouve sur la timeline d'un projet (pistes, clips, débuts, fins, ce qui est joué), exécuteznpx hyperframes timeline --jsonau lieu de lireindex.htmlet chaque fichier de sous-composition : les lignes imbriquées contiennent lesabsStart/absEndabsolus de la timeline principale et leurfilepropriétaire, pas seulement leur temps local par sous-composition. Préférez--jsonà la forme textuelle ; cela coûte moins de tokens pour une exactitude identique ou meilleure. Consultezreferences/upgrade-info-misc.mdpour des one-liners qui répondent aux questions courantes sans lire l'intégralité de la sortie. - Obtenez un feedback rapide pendant l'édition : exécutez
npx hyperframes lintaprès le premier passage HTML et après les modifications structurelles. - Exécutez la validation finale : exécutez
npx hyperframes check; il relance lint avant d'ouvrir le navigateur. N'ajoutez pas d'invocation lint indépendante redondante. Ajoutez--snapshotspour des vues d'ensemble 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 --background, vérifiez que l'URL renvoie un HTTP 200, remettez l'URL du projet de timeline à l'utilisateur et demandez s'il faut réviser ou effectuer le rendu. Gardez-le actif jusqu'à la fin de la révision. - Effectuez le rendu uniquement après approbation : utilisez
--quality draftpendant l'itération,--quality lookspour le premier encodage réel (par défaut de la CLI) et--quality deliverypour la livraison finale. - Vérifiez la sortie : confirmez que le fichier existe et n'est pas vide. Lisez la deuxième ligne du résumé du rendu (
beginframevsscreenshot, GPU, timings des étapes).screenshot+software gpusur Linux est le chemin lent.ffprobe -v error -show_format -show_streamset comparez la durée (et le fps si le brief l'a défini) à ladata-durationracine.
Références croisées obligatoires créateur-édition
- Avant d'écrire ou de diagnostiquer un zoom, un punch-in/punch-out, un recadrage, un mouvement de caméra ou tout mouvement d'images clés, lisez
/hyperframes-keyframesd'abord. - Avant
hyperframes keyframes, lisez/hyperframes-keyframes; la commande affiche les trajectoires d'animation et ne diagnostique pas les coupes de clips. - Pour une coupe, un recadrage, une jointure, un réordonnancement ou une modification de timing source, lisez
/hyperframes-coreet utilisez son contrat clip/timeline. - Pour un fondu entrant/sortant, un fondu enchaîné, un gain de piste, une automatisation de volume, un ducking, un découpage voix off ou des effets sur un audio placé, lisez
/hyperframes-audio. Chargez le core en même temps lorsque le placement du clip ou le timing de l'image changent également. - Une demande nommant un asset, un son, une image, une voix ou une modification visuelle rapide est résolue via
/media-useavant qu'un plan ne soit proposé. Copiez le balisage d'édition du créateur depuis/hyperframes-core→references/creator-editing-recipes.md.
# Vérification d'itération rapide ; répétez pendant l'écriture selon les besoins.
npx hyperframes lint
# Validation finale requise ; inclut lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams out.mp4
check exécute lint d'abord, puis utilise une session navigateur et un passage de recherche pour auditer les erreurs d'exécution, les demandes échouées, la mise en page, les assertions *.motion.json et le contraste WCAG. Les constats persistants bloquent le code de sortie ; les constats transitoires d'entrée ou de sortie sont informatifs. Utilisez --strict pour bloquer les avertissements. validate, inspect et layout restent des alias pour la compatibilité mais ne doivent pas apparaître dans les nouvelles instructions ou scripts.
Aperçu avant le rendu
Ouvrez l'aperçu de la composition finale (#project/<nom>) uniquement après que check a réussi, pour réviser la timeline assemblée. Le plan dans le chat et la feuille de croquis storyboard.html ne sont pas une approbation de la vidéo finale. Le rendu nécessite toujours l'approbation finale définie par hyperframes/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 stylisé, les icônes de taille canvas, les éléments héros manquants ou les timeouts d'enregistrement de timeline comme des défauts de montage bloquant le rendu. Consultez hyperframes-core/references/sub-compositions.md pour les correctifs correspondants.
Conventions de l'agent
-
Recherchez dans le catalogue avant d'écrire un mouvement à la main.
npx hyperframes catalog --query "<le mouvement, en anglais simple>". La recherche est entièrement locale : il n'y a pas de niveau hébergé, pas de compte, et le texte de la requête n'est jamais envoyé nulle part. Par défaut, elle classe en fonction du vocabulaire partagé avec le nom, le titre, la description et les tags de l'élément, ce qui manque toute formulation qui ne réutilise pas le propre wording du catalogue. Ajoutez--on-devicepour classer par sens à la place (voir le niveau hors ligne ci-dessous). -
Interrogez en anglais même si la vidéo ne l'est pas. Les deux niveaux indexent un catalogue anglais, donc une requête dans un autre script ne produit aucun terme recherchable et ne renvoie rien. Décrivez le mouvement en anglais ; le texte à l'écran reste dans la langue dont la vidéo a besoin.
Aucun mot recherchable dans la requêtesignifie exactement cela et n'est pas un composant manquant, donc ne le signalez pas comme une lacune du catalogue. -
Lisez quel niveau a répondu ; ne le déduisez jamais de l'apparition des résultats. Avec
--json, l'enveloppe contientquery,tier(on-deviceouwords),tier_detail,dropped,unindexed,shown,totaletresults, plustop_scorelorsque le niveau répondant en produit un etwarningslorsqu'un niveau a été demandé et n'a pas pu s'exécuter, ou lorsqu'une recherche n'a rien renvoyé et qu'un meilleur niveau attend encore le consentement de quelqu'un. Un résultat faible surwordsest attendu ; le même résultat suron-deviceest un bug.top_scoreest uniquement pouron-deviceet n'a pas de seuil derrière lui : le classeur renvoie l'ensemble du catalogue dans un certain ordre pour chaque requête, donc lisez-le comme une preuve plutôt que comme une réussite ou un échec. -
droppedetunindexedsont des biais opposés entre le registre et l'index sur l'appareil, et reformuler la requête ne résout ni l'un ni l'autre.droppedcompte les noms classés que ce registre ne peut pas installer, donc les correspondances les plus fortes sont celles qui sont perdues.unindexedcompte les mouvements du registre que l'index ne peut pas voir du tout, qu'aucune requête ne pourra jamais renvoyer. Actualiser le registre n'est pas la réponse à l'un ou l'autre : son manifeste a un TTL de 24h et se guérit tout seul, tandis que les vecteurs sont un artefact publié séparément et récupéré dans~/.hyperframes/catalog/. Réexécuter avec--on-devicerécupère cet index lorsqueunindexedest supérieur à zéro, c'est donc le remède à donner à l'utilisateur. Un biais de surcouverture pure (droppedsupérieur à zéro tandis queunindexedest nul) ne déclenche pas la récupération ; vider~/.hyperframes/catalog/est la seule façon de s'en sortir. Les deux comptages portent sur des noms plutôt que sur des résultats, donc l'un ou l'autre peut dépassertotal. -
Lorsqu'une recherche ne donne rien qui vaille la peine d'être installé, dites-le.
npx hyperframes feedback --search-miss "<la requête que vous avez exécutée>" --wanted "<le mouvement dont vous aviez besoin>" --tier <le niveau qui a répondu>. Vous n'avez pas besoin d'assembler cette ligne :catalog --queryl'affiche pré-remplie, et chaque enveloppe de recherche--jsonla porte commereport_gapavec la requête et le niveau déjà corrects — remplissez--wantedet envoyez. C'est le seul chemin qui envoie une requête où que ce soit, et c'est une commande délibérée distincte précisément pour que le simplecatalog --querytienne sa promesse de n'envoyer rien. Signalez sur l'un ou l'autre niveau, chaque fois que les résultats ne font pas ce qu'il faut ; n'attendez pas le niveau sur l'appareil, qui nécessite un téléchargement consenti de 33 Mo et est donc désactivé dans la plupart des exécutions d'agents — l'attendre signifie ne jamais signaler du tout. Le niveau est inclus dans le rapport, donc un échec de vocabulaire reste distinguable d'un échec de sens sans que vous ayez à juger lequel vous avez rencontré. Ce qui revient est une liste de mouvements que le catalogue n'a pas encore, lue directement plutôt que devinée à partir des comptes d'installation, donc la formulation qui compte est l'effet que vous vouliez, pas le nom d'élément que vous avez imaginé. Il ne porte aucune note et n'atterrit jamais dans la métrique de notation. -
Proposez le niveau hors ligne ; ne l'activez jamais silencieusement. Un téléchargement unique d'environ 33 Mo (une build ONNX quantifiée de
bge-small-en-v1.5plus son tokenizer, épinglé à une révision fixe) et les vecteurs du catalogue provenant du registre, tous deux mis en cache sous~/.hyperframes/, ni ajoutés au projet ni à aucun package. Une fois mis en cache, il classe par sens sans rien envoyer. Dites la taille à voix haute et laissez la personne décider, puis passez--on-device(avec-ypour ignorer l'invite) une fois qu'elle est d'accord. L'offre interactive ne se déclenche que sur un TTY. Sous--json, il n'y a pas d'invite, mais une recherche qui n'a rien trouvé place la même demande danswarnings, donc lisez ce tableau et soumettez la décision à l'utilisateur vous-même. Lorsque la personne demande ce qu'est le téléchargement, pourquoi ce modèle, ou ce qui quitte la machine, orientez-la vers https://hyperframes.heygen.com/developers/catalog-search. -
Préférez
--jsonpour les appels d'agent et de CI. Le mode serveurrender,previewetplayne fournissent pas de sortie JSON ordinaire ;preview --selection --jsonetpreview --context --jsonsont des exceptions en mode requête. -
doctor --jsonse termine toujours par zéro. Vérouillez sa charge utile :npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Le mode non-TTY est automatique et échafaude le blanc centré. Passez
--exampleuniquement pour partir d'un exemple nommé. Utilisez--non-interactivepour forcer le mode uniquement par drapeau sur un TTY. -
Utilisez un
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 en tant que
$HOME; n'essayez pas d'inverser le masquage. -
Lorsqu'un projet cloud hébergé approche ou dépasse la limite de téléchargement de 200 Mo, utilisez
cloud render --dry-run --jsonet suivez l'investigation.hyperframesignoredansreferences/cloud.md. N'ignorez jamais un asset simplement parce qu'il est volumineux. -
Ne faites jamais de rendu 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 actuelle, 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 signale no-selection, demandez à l'utilisateur de cliquer sur l'élément et de réexécuter. Demandez uniquement 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'erreur se trouvent dans references/preview-render.md.
Choix de rendu
| Besoin | Commande |
|---|---|
| Itération locale rapide | npx hyperframes render --quality draft |
| Premier encodage réel | npx hyperframes render --quality looks --output out.mp4 |
| Livraison locale finale | npx hyperframes render --quality delivery --output out.mp4 |
| Rendu conteneur reproductible | npx hyperframes render --docker --strict --output out.mp4 |
| Rendu par lots local basé sur variables | npx hyperframes render --batch rows.json --output "renders/{name}.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 |
L'attribution de skill est automatique — les exemples ci-dessus n'ont pas besoin de --skill. Un projet échafaudé par un workflow (hyperframes init --skill=<workflow>) enregistre son skill propriétaire dans hyperframes.json, et chaque rendu ultérieur l'hérite sur la télémétrie anonyme : ré-rendus, npm run render et --batch inclus. Passez --skill=<slug> explicitement uniquement pour marquer un projet qui n'a pas été créé via un workflow (son premier rendu le persiste alors).
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 si l'utilisateur s'est désabonné :
npx hyperframes feedback --rating <0-10> --comment "<résultat ou friction spécifique>"
Gardez le feedback pour les exécutions propres concis. Pour tout bug ou friction, capturez un packet de reproduction avant de soumettre ; n'envoyez pas seulement un résumé des symptômes. Incluez la commande ré-exécutable (relative au répertoire du projet — le feedback est soumis à un canal public, donc ne collez pas de chemins absolus, de préfixes de répertoire personnel ou d'identifiants d'utilisateur/machine), le comportement attendu par rapport au comportement réel, l'erreur exacte (supprimez également les chemins absolus…
[…tronqué pour la traduction]