hyperframes-cli

Installation des plugins : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution des plugins lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.

HyperFrames CLI

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. Le CLI nécessite Node.js 22 ou plus récent et FFmpeg.

Boucle de développement

1. Scaffold : npx hyperframes init <projet> (vierge centré). Ou capturez un site. Passez --example=<nom> uniquement pour partir d'un exemple nommé.
2. Trouver le mouvement : si la demande nomme un asset, un son, une image, une voix ou une édition visuelle rapide, résolvez-la via /media-use avant de proposer un plan. Sinon, avant d'écrire un mouvement à la main, cherchez une primitive qui le fait déjà : npx hyperframes catalog --query "révéler un titre ligne par ligne". Demandez l'effet que vous souhaitez plutôt que le mécanisme que vous avez en tête. Installez avec npx hyperframes add <nom> (voir /hyperframes-registry). Écrivez à la main uniquement si rien ne correspond.
3. É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écutez npx hyperframes timeline --json au lieu de lire index.html et chaque fichier de sous-composition : les lignes imbriquées portent absStart/absEnd absolus de la timeline principale et leur file propriétaire, pas seulement leur temps local par sous-composition. Préférez --json à la forme texte ; cela coûte moins de tokens pour une exactitude identique ou meilleure. Voir references/upgrade-info-misc.md pour des one-liners qui répondent aux questions courantes sans lire l'intégralité de la sortie.
4. Obtenez un retour rapide lors de l'édition : exécutez npx hyperframes lint après le premier passage HTML et après les changements structurels.
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 redondant et indépendant. Ajoutez --snapshots pour des images de synthèse annotées et le recadrage.
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 final Studio : exécutez npx hyperframes preview --background, vérifiez que l'URL renvoie un code HTTP 200, donnez l'URL du projet timeline à l'utilisateur, et demandez s'il faut réviser ou rendre. Gardez-le actif jusqu'à la fin de la révision.
8. Rendre uniquement après approbation : utilisez --quality draft pendant l'itération, --quality looks pour le premier encodage réel (par défaut du CLI), et --quality delivery pour la livraison finale.
9. Vérifiez la sortie : confirmez que le fichier existe et n'est pas vide. Lisez la deuxième ligne du résumé du rendu (beginframe vs screenshot, GPU, timings des étapes). screenshot + software gpu sur Linux est le chemin lent. ffprobe -v error -show_format -show_streams et comparez la durée (et fps si le brief l'a défini) à data-duration racine.

Historique du projet dans votre tour

Chaque écriture dans le projet est conservée comme une entrée qui peut être annulée. Utilisez-la à deux moments seulement, jamais à chaque étape :

• Début d'un tour : npx hyperframes history begin --who <votre-nom> --label "<ce que vous allez faire>", puis npx hyperframes history --since mine --who <votre-nom> pour voir ce que la personne a changé depuis votre dernier tour. Basez-vous sur leurs modifications ; ne les écrasez jamais.
• Une vérification a échoué, ou la personne dit que ça s'est aggravé : npx hyperframes history undo --who <votre-nom> annule votre tour le plus récent et laisse les modifications de la personne intactes. Ne reconfigurez pas manuellement. En cas de conflit, il se termine avec le code 2 et affiche les deux choix.

Terminez chaque tour avec npx hyperframes history end, afin que vos écritures soient considérées comme vôtres et non comme "Modifié en dehors de l'application". Tant qu'un tour est ouvert, chaque écriture dans le projet est comptée comme vôtre jusqu'à ce que 10 minutes s'écoulent sans aucune écriture ; après cela, le tour se termine automatiquement.

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 d'abord /hyperframes-keyframes.
• Avant hyperframes keyframes, lisez /hyperframes-keyframes ; la commande affiche les trajectoires d'animation et ne diagnostique pas les coupures de clip.
• Pour une coupe, un rognage, un réassemblage, ou une modification temporelle de 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 effets sur l'audio placé, lisez /hyperframes-audio. Chargez core en parallèle lorsque le placement du clip ou le timing de l'image change également.
• Une demande nommant un asset, un son, une image, une voix ou une édition visuelle rapide est résolue via /media-use avant qu'un plan ne soit proposé. Copiez le markup d'édition créateur depuis /hyperframes-core → references/creator-editing-recipes.md.

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

# Porte 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 en premier, puis utilise une session navigateur et un seul 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 résultats persistants bloquent le code de sortie ; les résultats 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 de 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 constituent 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 de sous-composition

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 stylé, les icônes de taille canvas, les éléments hero 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 d'agent

• Cherchez dans le catalogue avant d'écrire un mouvement à la main. npx hyperframes catalog --query "<le beat, 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, il 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 vocabulaire du catalogue. Ajoutez --on-device pour classer par signification (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 consultable 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, ou lorsqu'une recherche n'a rien renvoyé et qu'un meilleur niveau attend encore le consentement de quelqu'un. Un résultat faible sur words est attendu ; le même résultat sur on-device est un bug. top_score est spécifique à on-device et n'a pas de seuil derrière : le classeur renvoie le catalogue entier dans un certain ordre pour chaque requête, donc lisez-le comme une preuve plutôt que comme une réussite 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 cet index lorsque unindexed est supérieur à zéro, c'est donc le remède à donner à l'utilisateur. Un pur biais de sur-couverture (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 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 à assembler cette ligne : catalog --query l'affiche 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 quelque part, et c'est une commande délibérée distincte précisément pour que catalog --query simple 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'agent — 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 signification 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 souhaitiez, pas le nom d'élément que vous imaginiez. 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ée à 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 signification 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. Sous --json, il n'y a pas d'invite, mais une recherche qui n'a rien trouvé place la même demande dans warnings, 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, dirigez-la vers https://hyperframes.heygen.com/developers/catalog-search.

• 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 par zéro. Filtrez sur son payload :

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

• Le mode non-TTY est automatique et scaffold le modèle vierge centré. Passez --example uniquement pour partir d'un exemple nommé. Utilisez --non-interactive pour forcer le mode uniquement par indicateur sur un TTY.

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

• Lorsque le disque est saturé, exécutez npx hyperframes clean (--dry-run pour lister d'abord) ; il supprime ce que les rendus morts ont laissé et les caches inactifs qui se reconstruisent eux-mêmes, jamais les sorties, les sources ou quoi que ce soit qu'un rendu en cours utilise. Écrivez les images de contrôle qualité dans un répertoire temporaire, pas dans le projet.

• 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 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 --json et suivez l'investigation .hyperframesignore dans references/cloud.md. N'ignorez jamais un asset simplement parce qu'il est volumineux.

• Ne rendez jamais simplement parce que les vérifications passent. Faites une pause à l'aperçu final et attendez l'approbation.

Éditions 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
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 piloté par 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 l

…

[tronqué pour la traduction]