AntlersSam/kit-video-lancement-saas

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.

CLI HyperFrames

Exécutez les commandes sous la forme npx hyperframes ..., sauf si les instructions du projet fournissent un wrapper. Obéissez au wrapper s'il est présent. La CLI nécessite Node.js 22 ou plus récent et FFmpeg.

Cycle de développement

1. Scaffolding : npx hyperframes init <projet> (vide centré). Ou capturez un site. Passez --example=<nom> uniquement pour démarrer à partir d'un exemple nommé.
2. Trouver le mouvement : si la demande nomme un élément, un son, une image, une voix ou une modification visuelle rapide, résolvez-la via /media-use avant 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 ligne par ligne". Demandez l'effet que vous souhaitez plutôt que le mécanisme auquel vous pensez. Installez avec npx hyperframes add <nom> (voir /hyperframes-registry). Écrivez à la main uniquement si rien ne correspond.
3. Écrire : écrivez 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 lu), exécutez npx hyperframes timeline --json au lieu de lire index.html et chaque fichier de sous-composition : les lignes imbriquées contiennent les 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 toute la sortie.
4. Obtenez un retour rapide pendant l'édition : exécutez npx hyperframes lint après le premier passage HTML et après les modifications structurelles.
5. 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 avant. Ajoutez --snapshots pour obtenir des images d'aperçu annotées et trouver les 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 rendre. Gardez-le actif jusqu'à la fin de la révision.
8. Rendez uniquement après approbation : utilisez --quality draft pendant l'itération, --quality looks pour le premier encodage réel (valeur par défaut de la 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 sous Linux est le chemin lent. Utilisez ffprobe -v error -show_format -show_streams et comparez la durée (et les fps si le cahier des charges les a définis) avec la 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 uniquement, 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. Construisez sur leurs modifications ; ne les écrasez jamais.
• Une vérification a échoué, ou la personne dit que c'est devenu pire : npx hyperframes history undo --who <votre-nom> annule votre tour le plus récent et laisse les modifications de la personne intactes. Ne modifiez pas manuellement en arrière. En cas de conflit, il se termine par le code 2 et affiche les deux choix.

Terminez chaque tour avec npx hyperframes history end, afin que vos écritures soient lues comme les vôtres, et non comme "Modifié en dehors de l'application". Pendant qu'un tour est ouvert, chaque écriture dans le projet vous est attribuée 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-é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 révèle les trajectoires d'animation et ne diagnostique pas les coupures de clip.
• Pour une coupe, un rognage, une jonction, une réorganisation ou une modification de la synchronisation source, lisez /hyperframes-core et 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 insertion de voix off ou des effets sur un fichier audio placé, lisez /hyperframes-audio. Chargez le noyau en même temps lorsque le placement du clip ou la synchronisation de l'image changent également.
• Une demande nommant un élément, un son, une image, une voix ou une modification visuelle rapide est résolue via /media-use avant qu'un plan ne soit proposé. Copiez le balisage d'édition du créateur à partir de /hyperframes-core → references/creator-editing-recipes.md.

# Itération de vérification rapide ; répétez si nécessaire pendant l'écriture.
npx hyperframes lint

# Porte finale obligatoire ; 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 seul passage de recherche pour auditer les erreurs d'exécution, les échecs de requête, la mise en page, les assertions *.motion.json et le contraste WCAG. Les constatations persistantes bloquent le code de sortie ; les constatations transitoires d'entrée ou de sortie sont informatives. 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.

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 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épassements de délai 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 agents

• Recherchez dans le catalogue avant d'écrire un mouvement à la main. npx hyperframes catalog --query "<le beat, en français 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 balises 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 sens à la place (voir le niveau hors ligne ci-dessous).

• Interrogez en anglais même lorsque 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 de recherche 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ête 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 porte 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 retourné et qu'un meilleur niveau attend toujours le consentement de quelqu'un. Un résultat faible sur words est attendu ; le même résultat sur on-device est un bogue. top_score est propre au niveau on-device et n'a pas de seuil derrière lui : le classeur renvoie l'ensemble du catalogue dans un certain ordre pour chaque requête, alors lisez-le 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 on-device, et reformuler la requête ne résout 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. L'actualisation du registre n'est la réponse à aucun des deux : son manifeste a un TTL de 24 h 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-device récupère 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 portent sur des noms plutôt que sur des résultats, donc l'un ou l'autre 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 comme 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 distincte précisément pour que le simple 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 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'agent — 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 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 en silence. Un téléchargement unique d'environ 33 Mo (une construction 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/, aucun n'ajouté au projet ou à un 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 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 dans warnings, alors 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 sa charge utile :

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

• Le mode non-TTY est automatique et génère le squelette vide centré. Passez --example uniquement pour démarrer à partir d'un exemple nommé. Utilisez --non-interactive pour forcer le mode uniquement par drapeau 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 plein, 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, jamais les sorties, les 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-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 élément 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 Studio

Lorsque l'utilisateur fait référence à "cet élément" ou à la sélection actuelle, interrogez Studio au lieu de deviner :

npx hyperframes preview --context --json --context-fields selection

Utilisez selection.target.hfId lorsque 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 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 lot local piloté par variables	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Rendu HeyGen hébergé sans infrastructure	npx hyperframes cloud render
Rendu AWS distribué auto-géré	npx hyperframes lambda render --function <nom> --payload payload.json
Rendu Google Cloud Run sans serveur	npx hyperframes cloudrun render --service <nom> --payload payload.json

Problèmes connus et alternatives

Zone	Problème	Solution de contournement ou alternative
Transcodage matériel	L'accélération GPU peut ne pas être disponible dans tous les environnements.	Utilisez --software pour forcer le transcodage logiciel ; l'encodeur matériel n'est pas requis.
Rendu cloud (cloud, lambda, cloudrun)	Nécessite un compte et des identifiants HeyGen.	Voir hyperframes/references/cloud.md pour la configuration. Les identifiants sont lus à partir des variables d'environnement HEYGEN_API_KEY et HEYGEN_SECRET.
Mode --json	Certaines commandes (par exemple, render, preview, play en mode serveur) ne produisent pas de JSON.	Utilisez les drapeaux --json sous-commandes (par exemple, preview --context --json) ou utilisez doctor --json pour l'état du système.
Recherche dans le catalogue	Les requêtes non anglaises ne renvoient rien.	Décrivez le mouvement en anglais ; le texte vidéo peut être dans n'importe quelle langue. Utilisez --on-device pour la recherche sémantique après consentement.
Historique du projet	Les tours de plus de 10 minutes sans écriture se ferment automatiquement.	Terminez explicitement chaque tour avec npx hyperframes history end pour un contrôle précis.
Limite de téléchargement cloud	Les projets approchant 200 Mo peuvent échouer.	Utilisez cloud render --dry-run --json et inspectez la taille du paquet. Utilisez le fichier .hyperframesignore pour exclure les éléments non essentiels.

Références et ressources supplémentaires

• Documentation du noyau HyperFrames : conventions de composition et de timeline.
• Guide de l'éditeur vidéo HyperFrames : animations et images clés.
• Guide audio HyperFrames : audio, volume et voix off.
• Guide de révision et d'approbation : processus d'approbation finale.
• Dépannage et mises à niveau : correctifs et modifications rapides.
• Recettes d'édition pour créateurs : exemples de balisage pour les modifications courantes.
• Gestion des sous-compositions : édition et dépannage des compositions imbriquées.
• Déploiement cloud : configuration et dépannage pour cloud, lambda et cloudrun.
• Aperçu et rendu : comportement détaillé de l'aperçu et codes d'échec.
• API de recherche de catalogue : détails de la recherche hors ligne et confidentialité.