Installation du plugin : Avant les commandes de configuration ou de fraîcheur, suivez les règles d'exécution du plugin lorsque cette compétence se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
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 version ultérieure et FFmpeg.
Boucle de développement
- Échafauder :
npx hyperframes init <projet>(vide centré). Ou capturez un site. Passez--example=<nom>uniquement pour démarrer à partir d'un exemple nommé. - Trouver le mouvement : si la demande nomme un actif, un son, une image, une voix ou une modification visuelle rapide, résolvez-le 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èle 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 portentabsStart/absEndde la timeline principale et leurfilepropriétaire, pas seulement leur temps local par sous-composition. Préférez--jsonà la forme texte ; cela coûte moins de jetons pour une correction identique ou meilleure. Voirreferences/upgrade-info-misc.mdpour des commandes courtes qui répondent aux questions courantes sans lire l'intégralité de la sortie. - Obtenez des retours rapides pendant l'édition : exécutez
npx hyperframes lintaprès le premier passage HTML et après les modifications structurelles. - 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. - Inspecter les sous-compositions : lorsque
index.htmlmontedata-composition-src, capturez les instantanés au milieu et inspectez chaque scène montée. - Ouvrez l'aperçu Studio final : exécutez
npx hyperframes preview --background, vérifiez que l'URL renvoie HTTP 200, remettez l'URL du projet de timeline à l'utilisateur et demandez s'il faut réviser ou rendre. Gardez-le actif jusqu'à la fin de la révision. - Rendre uniquement après approbation : utilisez
--quality draftpendant l'itération,--quality lookspour le premier encodage réel (valeur par défaut de la CLI) et--quality deliverypour la livraison finale. - Remettre le projet à l'application de bureau (si proposé) : lorsque la ligne Framy du rendu se termine par
hyperframes open …, proposeznpx hyperframes open [dossier]. Cela ouvre le projet dans l'application de bureau HyperFrames et l'ajoute à l'Accueil ; sous Claude Code ou Codex, son chat reprend cette conversation. Sans l'application, il se termine avec le code 1 et imprime le lien de téléchargement.--jsonpour les agents. - Vérifier la sortie : confirmez que le fichier existe et n'est pas vide. Lisez la deuxième ligne du résumé du rendu (
beginframevsscreenshot, GPU, timing des étapes).screenshot+software gpusous Linux est le chemin lent.ffprobe -v error -show_format -show_streamset comparez la durée (et les fps si le brief les a définis) àdata-durationracine.
Historique du projet dans votre tour
Chaque écriture dans le projet est conservée comme une entrée pouvant être annulée. Utilisez-la à seulement deux moments, jamais à chaque étape :
- Début d'un tour :
npx hyperframes history begin --who <votre-nom> --label "<ce que vous allez faire>", puisnpx hyperframes history --since mine --who <votre-nom>pour voir ce que la personne a changé depuis votre dernier tour. Construisez sur leurs modifications ; ne les écrasez jamais. - Un échec de check, ou la personne dit que c'est devenu pire :
npx hyperframes history undo --who <votre-nom>annule votre dernier tour et laisse les modifications de la personne intactes. Ne modifiez pas manuellement en arrière. 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". Pendant qu'un tour est ouvert, chaque écriture dans le projet compte comme vôtre jusqu'à ce que 10 minutes s'écoulent sans écriture ; après cela, le tour se termine de lui-même.
Références croisées obligatoires créateur-modification
- Avant d'écrire ou de diagnostiquer un zoom, un punch-in/punch-out, un recadrage, un mouvement de caméra, ou tout mouvement avec keyframes, lisez
/hyperframes-keyframesd'abord. - 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, une jonction, un réordonnancement ou une modification de timing de source, lisez
/hyperframes-coreet utilisez son contrat clip/timeline. - Pour un fondu d'entrée/sortie, un fondu enchaîné, un gain de piste, une automatisation de volume, un ducking, une découpe de voix off ou un FX sur un fichier audio placé, lisez
/hyperframes-audio. Chargez core en parallèle si le placement du clip ou le timing de l'image change également. - Une demande nommant un actif, 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 de modification 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
# 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 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 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 compatibilité mais ne doivent pas apparaître dans les nouvelles instructions ou scripts.
Aperçu avant rendu
Ouvrez l'aperçu de la composition finale (#project/<nom>) uniquement après la réussite de check, pour examiner la timeline assemblée. Le plan dans le chat et la feuille d'esquisse 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 chaque échec de montage. Lorsque le projet utilise des sous-compositions, capturez au moins un point milieu 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 héros manquants ou les dépassements de délai 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
-
Recherchez dans le catalogue avant d'écrire un mouvement à la main.
npx hyperframes catalog --query "<le beat, en anglais courant>". 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é. Par défaut, il classe en fonction du vocabulaire partagé avec le nom, le titre, la description et les étiquettes de l'élément, ce qui manque toute formulation qui ne réutilise pas le propre vocabulaire du catalogue. Ajoutez--on-devicepour classer par signification à 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 en anglais, donc une requête dans une autre écriture ne produit aucun terme de recherche et ne renvoie rien. Décrivez le mouvement en anglais ; le texte à l'écran reste dans la langue de la vidéo.
Aucun mot de recherche 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 etwarningslorsque le 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 pour le mode on-device et n'a pas de seuil derrière lui : le classeur renvoie l'ensemble du catalogue dans un ordre quelconque pour chaque requête, donc lisez-le comme une indication plutôt que comme une réussite ou un échec. -
droppedetunindexedsont des distorsions opposées entre le registre et l'index on-device, et reformuler la requête ne résout aucun des deux.droppedcompte les noms classés que ce registre ne peut pas installer, donc les correspondances les plus fortes sont celles perdues.unindexedcompte les mouvements du registre que l'index ne peut pas voir du tout, qu'aucune requête ne peut jamais renvoyer. Actualiser le registre n'est la réponse à aucun des deux : son manifeste a une TTL de 24 heures 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-devicerefetch cet index lorsqueunindexedest supérieur à zéro, c'est donc le remède à donner à l'utilisateur. Une distorsion de pure sur-couverture (dropped> 0 tandis queunindexed= 0) ne déclenche pas le refetch ; vider~/.hyperframes/catalog/est le seul moyen de s'en sortir. Les deux comptent des noms plutôt que des résultats, donc l'un ou l'autre peut dépassertotal. -
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 --queryl'imprime 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 quelque part, et c'est une commande délibérée séparée précisément pour quecatalog --queryseul tienne sa promesse de n'envoyer rien. Signalez sur l'un ou l'autre niveau, chaque fois que les résultats ne font pas le travail ; n'attendez pas le niveau on-device, 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 une erreur de vocabulaire reste distinguable d'une erreur de sens sans que vous ayez à juger laquelle vous avez rencontrée. 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.5plus son tokenizer, lié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-ypour 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 danswarnings, donc lisez ce tableau et mettez la décision devant 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
--jsonpour les appels d'agents et CI. Lesrender,previewetplayen mode serveur ne fournissent pas de sortie JSON ordinaire ;preview --selection --jsonetpreview --context --jsonsont des exceptions en mode requête. -
doctor --jsonse termine toujours avec le code 0. Vérifiez sa charge utile :npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
Le mode non-TTY est automatique et échafaude le vide centré. Passez
--exampleuniquement pour démarrer à partir d'un exemple nommé. Utilisez--non-interactivepour forcer le mode uniquement par drapeaux sur un TTY. -
Utilisez un seul
HYPERFRAMES_RUN_IDpour toutes les commandes dans la même boucle de vérification. -
Lorsque le disque est saturé, exécutez
npx hyperframes clean(--dry-runpour 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, sources ou quoi que ce soit qu'un rendu en cours utilise. Écrivez les images QC dans un répertoire temporaire, pas dans le projet. -
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 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 actif simplement parce qu'il est volumineux. -
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 courante, 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 éditables. 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 --... |
[suite tronquée pour la traduction]