CLI HyperFrames
Tout s'exécute via npx hyperframes sauf si les instructions du projet spécifient un wrapper local. Respectez exactement le wrapper local. Nécessite Node.js >= 22 et FFmpeg.
Flux de travail
- Scaffolding —
npx hyperframes init my-video(oucaptureà partir d'une URL).initvérifie également les compétences installées par rapport aux dernières versions sur GitHub et met à jour l'ensemble global si certaines sont obsolètes. Le flag--skip-skillsest actuellement neutralisé (temporairement, en attendant que le registre skills.sh rattrape son retard), donc chaqueinitexécute cette vérification et récupère nos dernières compétences quoi qu'il arrive. - Écrire — rédiger la composition HTML (voir la compétence
hyperframes-core) - Lint —
npx hyperframes lint(statique, rapide — exécutez-le tôt pendant l'itération) - Check —
npx hyperframes check(la passerelle navigateur ; ajoutez--snapshotspour des images annotées + des recadrages par constat) - Prévisualiser / éditer —
npx hyperframes previewouvre Studio, l'éditeur de timeline où l'utilisateur peut éditer manuellement n'importe quoi (pas seulement regarder). Révisez-y, puis demandez avant de rendre. - Rendre — choisissez la variante :
- Itérer :
npx hyperframes render --quality draft - Livrer :
npx hyperframes render --quality high --output out.mp4 - CI / reproduction cross-plateforme :
npx hyperframes render --docker --strict --output out.mp4 - Cloud, zéro infrastructure :
npx hyperframes cloud render(HeyGen héberge le rendu ; pas de Chrome/FFmpeg/AWS local, voir Cloud ci-dessous) - Cloud, apportez votre propre AWS :
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait(voir Lambda ci-dessous)
- Itérer :
- Signaler un retour — après avoir vérifié la sortie,
npx hyperframes feedback --rating <1-5> --comment "..."une fois par tâche (voir Conventions de l'agent).
Exécutez check avant la prévisualisation. Il exécute d'abord le linter (et ignore complètement le navigateur en cas d'erreurs de lint), puis fait tout ce que l'ancienne séquence validate → inspect → snapshot faisait en une session navigateur et une passe de recherche : erreurs de console runtime et requêtes échouées, défauts de mise en page (texte débordant des bulles/conteneurs ou du canevas, chevauchements maintenus, occlusion), vérification du side-car de mouvement (*.motion.json — entrées sous recherche, ordre de stagger, dans le cadre, vivacité) et contraste WCAG. Les échecs de contraste sont des erreurs et portent les couleurs fg/bg échantillonnées, le rapport mesuré vs requis, et une couleur conforme suggérée, donc la plupart des corrections de contraste n'ont pas besoin de capture d'écran. Chaque constat porte un sélecteur, une identité data-*, un fichier source de composition, un bbox et un temps d'échantillonnage — accédez directement au HTML. Les transitoires à un seul échantillon sont rétrogradés en info ; les constats maintenus sur plusieurs échantillons conditionnent le code de sortie (--strict conditionne aussi les avertissements). validate, inspect et layout fonctionnent encore mais sont des alias obsolètes de parties de check.
Pour les travaux à forte composante de mouvement, préférez une itération basée sur les instantanés et un side-car *.motion.json — voir references/lint-validate-inspect.md pour la discipline et la spécification de vérification du mouvement. Pour comparer des variantes candidates rédigées par l'agent, utilisez npx hyperframes compare <chemin...> [--at <sec>] [--labels a,b,c] [--out compare.png] [--cols n] [--json] pour rendre chaque composition via son propre runtime, assembler une feuille étiquetée, l'inspecter côte à côte et choisir. Pour la sélection d'étalonnage, utilisez la commande spécifique aux couleurs npx hyperframes grade-compare --for <frame> --grades grades.json (ou --luts a.cube,b.cube) pour rendre chaque candidat d'étalonnage via le runtime d'étalonnage WebGL réel en une seule PNG étiquetée avant de choisir le gagnant.
Conventions de l'agent
Règles transversales qui s'appliquent à chaque commande :
--jsonest disponible sur toutes les commandes saufrender,previewetplayen mode serveur. Utilisez-le pour toute invocation agent / CI des commandes prises en charge ; la sortie inclut une enveloppe_meta(version CLI, dernière version disponible, conseil de mise à jour).rendersignale son statut via stdout + code de sortie uniquement — vérifiez le succès avec la vérification post-rendu ci-dessous.preview --selection --jsonetpreview --context --jsonsont les exceptions de prévisualisation : ils ne démarrent pas de serveur, ils interrogent la session Studio en cours de l'utilisateur et se terminent.doctor --jsonse termine toujours par 0, même lorsque l'environnement est cassé. Vérifiez le champokdu payload :npx hyperframes doctor --json | jq -e '.ok' > /dev/null. Cela isole les pipelines des changements de version de la CLI.- Le mode non-TTY est détecté automatiquement. Lorsque
stdoutn'est pas un TTY (CI, agents, sortie redirigée), la CLI passe automatiquement en mode non interactif ;initnécessite alors--example. Passez--non-interactivepour forcer ce mode même sur un TTY. - CI gating sur le rendu :
--strictéchoue sur les erreurs de lint,--strict-alléchoue aussi sur les avertissements,--strict-variableséchoue sur les clés--variablesnon déclarées. - Corréler une boucle de vérification avec
HYPERFRAMES_RUN_ID. Les orchestrateurs qui pilotent la CLI par tâche/élément de conception doivent définir cette variable d'environnement une fois par unité de travail ; chaque invocation de commande l'attache à la télémétrie, etcheckémet une répartition par passerelle, rendant les allers-retours par tâche mesurables. - Les chemins dans
--jsonsont masqués —$HOMEdevient le littéral$HOMEpour que la sortie puisse être collée en toute sécurité dans les rapports de bugs et les contextes d'agent. - Le rendu est verrouillé par l'utilisateur. Ne rendez jamais automatiquement une fois les vérifications passées. Arrêtez-vous à
preview, dites à l'utilisateur que la vidéo est modifiable dans Studio, et ne rendez qu'après son approbation. - Utilisez le contexte Studio pour les modifications dirigées par l'utilisateur. Lorsque l'utilisateur dit "cet élément sélectionné", "la chose sur laquelle j'ai cliqué", "sélection actuelle" ou similaire, demandez-lui de la sélectionner dans Studio, puis exécutez
npx hyperframes preview --context --json --context-fields selection. Utilisez leselection.target.hfId/selector,selection.sourceFile,selection.currentTimeetselection.thumbnailUrlretournés pour ancrer la modification. Siselectionestnulleterrors.selection.codeestno-selection, demandez à l'utilisateur de cliquer sur l'élément et de réexécuter ; ne devinez pas à partir de captures d'écran. - Gardez le contexte Studio compact.
preview --context --jsonretourne une sélection compacte par défaut. Ajoutez--context-fields selection,--context-fields selection,lintou--context-fields lintpour éviter de gonfler le contexte de l'agent. Utilisez--context-detail fulluniquement lorsque vous avez besoin de champs lourds comme les styles calculés, les styles en ligne ou les métadonnées de champ de texte. - Vérification post-rendu. Après que
rendera retourné le code de sortie 0, confirmez que le fichier de sortie existe et a une taille plausible avant de signaler le succès :[ -s "$OUTPUT" ] || echo "le rendu n'a produit aucune sortie". La CLI imprime◇ <chemin>en cas de succès ; pour les rendus longs, vérifiez aussi la durée avecffprobe -i "$OUTPUT" -show_format -v error. - Signalez un retour après un rendu réussi. Une fois la sortie vérifiée, exécutez
npx hyperframes feedback --rating <1-5> --comment "..."une fois par tâche pour signaler comment le déroulement s'est passé —5pour propre, plus bas lorsque vous rencontrez des frictions. Mettez tout bug, contournement, fonctionnalité manquante ou comportement déroutant que vous avez rencontré dans--comment. C'est le principal canal de signalisation du projet ; les rendus qui restent silencieux laissent les mainteneurs aveugles. Sautez uniquement lorsque la télémétrie est désactivée ou que l'utilisateur a refusé.- Pour un bug reproductible, ajoutez
--file-issue— il publie une reproduction minimale du projet à une URL publique et ouvre un problème GitHub pré-rempli avec votre commentaire + environnement. Un commentaire seul ne permet presque jamais à un mainteneur de reproduire ; la composition publiée est ce qui rend le rapport actionnable. Pointez--dir <projet>vers la composition défaillante si ce n'est pas le répertoire actuel. - Rédigez des commentaires de bug qu'un mainteneur peut reproduire — une paraphrase sur laquelle il ne peut pas agir gaspille le rapport. La CLI attache déjà os/arch/mem/ffmpeg/CLI-version, donc ne les répétez pas ; consacrez le commentaire à ce que vous seul avez vu. Pour un bug, incluez chacun des éléments suivants qui s'appliquent :
- Chaîne d'erreur exacte, textuellement (copiez-la, ne la résumez pas) — et si le rendu a quand même produit un fichier de sortie, est discrètement revenu en arrière (cherchez une ligne de log
[Render] … re-rendering via screenshot/falling back), ou le processus s'est arrêté brutalement sans erreur (Killed: 9,FATAL … heap,Target closed). "Quel timeout / quel mode d'échec" est le fait le plus utile. - Une reproduction minimale : la plus petite composition (ou juste l'élément problématique + son CSS) qui le montre encore — intégrez-la dans le commentaire ou notez le fichier. Nommez le déclencheur que vous avez isolé (par exemple "uniquement lorsque le nœud de texte utilise
font-family: 苹方", "uniquement en 4K", "uniquement avec une<video>présente"). - La commande exacte + les flags que vous avez exécutés, et toutes les variables d'environnement définies (
HF_*/PRODUCER_*). - Ce qui ne va pas et où : le numéro de frame ou le timestamp, et le défaut visuel (texte vide, bande noire en bas, mauvais glyphes, canevas figé) par rapport à ce que vous attendiez. Un chemin de capture d'écran si vous en avez sauvegardé une.
- Si cela ne se reproduit que parfois, dites-le et donnez le taux de succès.
- Chaîne d'erreur exacte, textuellement (copiez-la, ne la résumez pas) — et si le rendu a quand même produit un fichier de sortie, est discrètement revenu en arrière (cherchez une ligne de log
- Pour un bug reproductible, ajoutez
Routage
| Vous voulez… | Lire |
|---|---|
Créer un projet (init, capture, skills) | references/init-and-scaffold.md |
Vérifier l'exactitude (lint, check, snapshot, obsolètes validate/inspect) | references/lint-validate-inspect.md |
Prévisualiser ou rendre (preview, play, render, publish) | references/preview-render.md |
Diagnostiquer l'environnement (doctor, browser) | references/doctor-browser.md |
Rendu cloud, zéro infrastructure hébergé par HeyGen (cloud render / list / get / delete, auth) | references/cloud.md |
Rendu cloud sur votre propre AWS Lambda (lambda deploy / sites / render / progress / destroy / policies) | references/lambda.md |
Paramétrer / templater les rendus (--variables, --variables-file, --strict-variables, --batch) | references/cloud.md + hyperframes-core (variables-and-media.md) |
Tout le reste (info, upgrade, compositions, docs, benchmark, telemetry, prétraitement d'actifs) | references/upgrade-info-misc.md |
Passerelles entre compétences
- Projets Tailwind (
init --tailwind) → utilisezhyperframes-core(référence Tailwind) avant de modifier les classes ou les tokens de thème. - Blocs/composants du registre (
hyperframes add,hyperframes catalog) → utilisezhyperframes-registrypour les chemins d'installation, le câblage de sous-compositions et la fusion d'extraits. - Prétraitement d'actifs (
tts,transcribe,remove-background) → utilisezmedia-usepour la sélection de voix, les règles du modèle Whisper, les sous-titres et la chaîne TTS-vers-sous-titres. - Rendus paramétrés (
--variables) → déclarés viadata-composition-variablessur<html>; voirhyperframes-corepour le schéma complet.
Cloud (rendu hébergé HeyGen)
hyperframes cloud render est le chemin de rendu zéro infrastructure : la CLI compresse votre projet, le télécharge, le rend sur le cloud HeyGen et télécharge le mp4. Pas de Chrome, pas de FFmpeg, pas d'AWS, et vous payez par crédit. C'est la réponse par défaut à "rendre ceci dans le cloud" ; recourez à Lambda uniquement si vous possédez déjà AWS et avez besoin d'un rendu distribué/découpé.
npx hyperframes auth login # connexion unique (partagée avec la CLI `heygen`)
npx hyperframes cloud render # compression, téléchargement, rendu, téléchargement vers renders/<id>.mp4
Flags courants : --composition <html>, --output <chemin>, --quality draft|standard|high, --fps, --resolution 1080p|4k, --format mp4|webm|mov, --aspect-ratio (détecté automatiquement depuis data-width/data-height). Utilisez --no-wait + --callback-url pour le "fire-and-forget" ; sécurisez les reprises avec --idempotency-key "$(uuidgen)". Gérez les jobs avec cloud list / cloud get <id> / cloud delete <id>.
Le flux de travail de template idiomatique est "téléchargez une fois, re-rendez plusieurs fois" : rendez un projet local une fois pour obtenir son asset_id, puis soumettez à nouveau contre cet actif avec différents --variables (saute la compression + le téléchargement). Voir references/cloud.md pour l'ensemble complet des flags, le modèle d'authentification, les webhooks et la boucle de template.
Variables (rendus paramétrés / templates)
Tout rendu (local, cloud ou Lambda) peut remplir des emplacements de template déclarés au moment du rendu. Les déclarations se trouvent sur la composition (data-composition-variables) ; la surface de la CLI est :
npx hyperframes render --variables '{"title":"Récapitulatif T4","theme":"dark"}' --output q4.mp4
npx hyperframes render --variables-file ./vars.json --output out.mp4
npx hyperframes render --batch rows.json --output "renders/{name}.mp4" --strict-variables
npx hyperframes cloud render --asset-id asst_abc123 --variables '{"name":"Ada"}'
--strict-variables fait échouer le rendu en cas de clé non déclarée ou de type mismatch (à utiliser en CI). --batch <rows.json> rend une sortie par ligne de données avec des placeholders de chemin {key}/{index} et écrit un manifest.json. Pour le schéma complet (déclaration des types, liaisons déclaratives data-var-src/data-var-text, data-variable-values par instance pour les sous-compositions, et précédence), utilisez la compétence hyperframes-core (references/variables-and-media.md). La boucle de template cloud se trouve dans references/cloud.md.
Lambda (Rendu cloud)
hyperframes lambda déploie le rendu distribué sur AWS Lambda et pilote les rendus depuis votre ordinateur portable ou CI. De bout en bout, cela nécessite trois commandes :
npx hyperframes lambda deploy # provisionner la pile SAM (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy # démanteler (S3 bucket)
...
[section tronquée pour la traduction... suite dans le skill original complet]
[Note de l'éditeur : Les sections restantes (Lambda complète, Prétraitement d'actifs, etc.) suivent la même structure que l'original. Le skill complet doit être livré en français avec la même fidélité structurelle et terminologique.]