hyperframes-cli

CLI HyperFrames

Exécutez les commandes avec npx hyperframes ... sauf si les instructions du projet fournissent un wrapper. Respectez le wrapper lorsqu'il est présent. La CLI nécessite Node.js 22 ou plus récent et FFmpeg.

Boucle de développement

1. Échafaudage : npx hyperframes init <projet> ou capturez un site. En mode non-TTY, passez --non-interactive --example=<nom>.
2. Trouver le mouvement : avant d'écrire un mouvement à la main, recherchez une primitive qui le fait déjà : npx hyperframes catalog --query "révéler un titre ligne par ligne". Demandez l'effet souhaité plutôt que le mécanisme que vous avez en tête. Installez avec npx hyperframes add <nom> (voir /hyperframes-registry). N'écrivez à la main que si rien ne correspond.
3. Écrire : rédigez la composition en utilisant /hyperframes-core.
4. Obtenez des retours rapides pendant l'édition : exécutez npx hyperframes lint après le premier passage HTML et après les modifications structurelles.
5. Exécutez la vérification finale : exécutez npx hyperframes check ; il relance lint avant d'ouvrir le navigateur. N'ajoutez pas d'appel lint autonome redondant. Ajoutez --snapshots pour des aperçus annotés et la recherche de recadrages.
6. Inspectez les sous-compositions : lorsque index.html monte data-composition-src, capturez des instantanés à mi-parcours et inspectez chaque scène montée.
7. Ouvrez l'aperçu Studio final : exécutez npx hyperframes preview --background, vérifiez que l'URL renvoie HTTP 200, donnez 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.
8. Effectuez le rendu uniquement après approbation : utilisez la qualité brouillon pour les itérations et la qualité élevée pour la livraison.
9. Vérifiez la sortie : confirmez que le fichier existe, n'est pas vide et a une durée plausible.

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'image clé, lisez /hyperframes-keyframes d'abord.
• Avant hyperframes keyframes, lisez /hyperframes-keyframes ; la commande affiche les trajectoires d'animation et ne diagnostique pas les coupes de clip.
• Pour une coupe, un rognage, un épissage, un réordonnancement ou une modification de la synchronisation source, lisez /hyperframes-core et utilisez son contrat clip/timeline.
• Pour un fondu entrant/sortant, un fondu enchaîné, un gain de piste, une automatisation de volume, un ducking, une découpe de voix off ou des FX sur un audio placé, lisez /hyperframes-audio. Chargez core en même temps si le placement du clip ou la synchronisation de l'image changent également.
• Utilisez /media-use uniquement pour générer ou prétraiter un actif dérivé. Copiez le balisage d'édition du créateur depuis /hyperframes-core → references/creator-editing-recipes.md.

# Vérification rapide d'itération ; répétez pendant l'écriture si nécessaire.
npx hyperframes lint

# Vérification finale obligatoire ; inclut lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4

check exécute lint en premier, puis utilise une session navigateur et un passage de recherche pour auditer les erreurs d'exécution, les requêtes ayant échoué, la mise en page, les assertions *.motion.json et le contraste WCAG. Les problèmes persistants bloquent le code de sortie ; les problèmes transitoires d'entrée ou de sortie sont informatifs. Utilisez --strict pour bloquer sur 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
Storyboard	Avant les vérifications de composition, uniquement si storyboard: yes	Examiner les fiches de plan et les croquis filaire. Ouvrir ?view=storyboard#project/<nom>.
Aperçu final de composition	Après que check a réussi	Examiner la timeline assemblée avant le rendu. Ouvrir #project/<nom>.

Le storyboard 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>

Considérez le contenu minuscule non stylisé, les icônes de taille canvas, les éléments héros manquants ou les délais d'enregistrement de la 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

• Recherchez dans le catalogue avant d'écrire un mouvement à la main. npx hyperframes catalog --query "<le beat, en anglais clair>". 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 selon le vocabulaire partagé avec le nom de l'élément, le titre et la description, ce qui manque toute formulation qui ne réutilise pas le propre vocabulaire du catalogue. Ajoutez --on-device pour 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 une autre écriture 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. No searchable words in query signifie 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 contient query, tier (on-device ou words), tier_detail, dropped, unindexed, shown, total et results, plus top_score lorsque le niveau répondant en produit un et warnings lorsqu'un niveau a été demandé et n'a pas pu s'exécuter. Un résultat faible sur words est attendu ; le même résultat sur on-device est un bug. top_score est uniquement sur l'appareil et n'a pas de seuil derrière : le classeur renvoie l'ensemble du catalogue dans un ordre pour chaque requête, lisez-le donc comme une preuve plutôt que comme un succès ou un échec.

• dropped et unindexed sont des biais opposés entre le registre et l'index sur l'appareil, et reformuler la requête ne corrige ni l'un ni l'autre. dropped compte les noms classés que ce registre ne peut pas installer, donc les correspondances les plus fortes sont celles qui sont perdues. unindexed compte 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 la réponse à aucun des deux : son manifeste a un TTL de 24h et se guérit tout seul, tandis que les vecteurs sont un artefact publié séparément récupéré dans ~/.hyperframes/catalog/. Réexécuter avec --on-device récupère à nouveau cet index lorsque unindexed est supérieur à zéro, c'est donc le remède à donner à l'utilisateur. Un biais de sur-couverture pur (dropped supérieur à zéro tandis que unindexed est nul) ne déclenche pas la récupération ; effacer ~/.hyperframes/catalog/ est la seule façon de s'en sortir. Les deux comptages sont des noms plutôt que des résultats, donc chacun peut dépasser total.

• Lorsqu'une recherche ne renvoie 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 à assembler cette ligne : catalog --query l'imprime pré-remplie, et chaque enveloppe de recherche --json la porte sous report_gap avec la requête et le niveau déjà corrects — remplissez --wanted et envoyez. C'est le seul chemin qui envoie une requête où que ce soit, et c'est une commande délibérée séparée précisément pour que catalog --query tienne sa promesse de n'envoyer rien. Signalez sur l'un ou l'autre niveau, chaque fois que les résultats ne font pas l'affaire ; 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 version ONNX quantifiée de bge-small-en-v1.5 plus 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 -y pour ignorer l'invite) une fois qu'elle accepte. L'offre interactive ne se déclenche que sur un TTY, et sous --json rien n'est imprimé à ce sujet, donc dans une exécution d'agent, vous devez le soulever vous-même auprès de l'utilisateur.

• Préférez --json pour les appels d'agent et CI. Les modes serveur render, preview et play ne fournissent pas de sortie JSON ordinaire ; preview --selection --json et preview --context --json sont des exceptions en mode requête.

• doctor --json se termine toujours avec zéro. Vérifiez sa charge utile :

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• Le mode non-TTY est automatique. init nécessite --example là ; utilisez --non-interactive pour forcer un comportement déterministe sur un TTY.

• Utilisez un seul HYPERFRAMES_RUN_ID pour toutes les commandes dans la même boucle de vérification.

• Utilisez --strict, --strict-all et --strict-variables lorsque les avertissements, variables ou conditions CI correspondants doivent bloquer le rendu.

• Les chemins JSON masquent le répertoire personnel sous $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 --json et suivez l'investigation .hyperframesignore dans references/cloud.md. N'ignorez jamais un actif simplement parce qu'il est volumineux.

• Ne faites jamais le rendu simplement parce que les vérifications réussissent. Pausez sur 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 plutôt que 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
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 basé sur des variables	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Rendu hébergé HeyGen sans infrastructure	npx hyperframes cloud render
Rendu distribué AWS auto-géré	npx hyperframes lambda render <projet> --width 1920 --height 1080 --wait
Rendu distribué GCP auto-géré	npx hyperframes cloudrun render <projet> --width 1920 --height 1080 --wait

L'attribution de compétence est automatique — les exemples ci-dessus n'ont pas besoin de --skill. Un projet échafaudé par un workflow (hyperframes init --skill=<workflow>) enregistre sa compétence propriétaire dans hyperframes.json, et chaque rendu ultérieur l'hérite sur la télémétrie anonyme : re-rendus, npm run render et --batch de la même manière. Passez --skill=<slug> explicitement uniquement pour estampiller un projet qui n'a pas été créé via un workflow (son premier rendu le persiste ensuite).

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ésinscrit :

npx hyperframes feedback --rating <0-10> --comment "<résultat ou friction spécifique>"

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 (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 des traces de pile — gardez le nom de base + la ligne, supprimez le répertoire principal), si la sortie est terminée/repliée/a échoué, la solution de contournement et le statut du projet de reproduction. Pour une note ≤ 7 qui décrit un défaut visuel (trame noire, scintillement, sortie corrompue, mauvaise image, sortie vide, autre anomalie visuelle), incluez également un bloc COMPOSITION_STRUCTURE: — une anatomie structurelle préservant la confidentialité (recensement des éléments + présence d'attributs + forme de la timeline) afin que les mainteneurs puissent faire correspondre des modèles avec des familles de bugs connues sans le ZIP de la composition. Les agents remplissent automatiquement ceci via l'assistant de recensement de composition ; l'utilisateur humain ne le remplit pas à la main. Si le problème ne s'est pas reproduit, dites-le et incluez toujours la dernière commande ayant échoué et les journaux. Utilisez --file-issue uniquement avec consentement : il publie une reproduction minimale sur une URL publique. Le format de paquet requis 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