CLI HyperFrames
Enveloppe npx hyperframes pour le pipeline d'ingénierie marketing. Nécessite Node.js >= 22 et FFmpeg sur le PATH (npx hyperframes doctor vérifie). Toutes les commandes s'exécutent en mode DRY_RUN-safe par défaut — les passes lint/inspect n'effectuent aucun appel externe ; seul render écrit un MP4.
Quand l'invoquer
- Immédiatement après que
hyperframes-prompt-builderait produit un projet dansoutputs/<client>/<date>/<piece-id>/. - Chaque fois qu'une composition nécessite une validation avant publication (
lint+inspect). - Pour un aperçu local lors de l'itération sur un élément (
preview). - Pour le rendu final qui produit l'artefact récupéré par l'étape de publication (
render). - Pour le dépannage de l'environnement lorsque le rendu échoue (
doctor,browser,info).
Entrées
project_path: chaîne. Chemin vers le projet HyperFrames (doit contenirindex.htmletcomposition.json).mode:"lint" | "inspect" | "preview" | "render" | "doctor".render_opts: objet, optionnel, uniquement pourmode = "render". Clés reconnues :fps: 24 | 30 | 60 (défaut 30).quality:"draft" | "standard" | "high"(défaut"standard"; utiliser"draft"pendant l'itération).format:"mp4" | "webm"(défaut"mp4").variables: objet. Objet JSON indexé par identifiant de variable, remplace les valeurs par défaut dedata-composition-variables.strict: booléen. Correspond à--strict(par défauttruedans le pipeline — échec du rendu en cas d'erreurs de lint).strict_variables: booléen. Correspond à--strict-variables(par défauttruepour les exécutions d'éléments).workers: entier 1-8 ou"auto"(défaut"auto").output: chaîne. Chemin du fichier de sortie dansoutputs/<client>/<date>/<piece-id>/.
Processus
- Vérifier l'environnement lors de la première exécution d'une session :
npx hyperframes doctor. Signaler l'absence de FFmpeg ou Chrome comme un blocage dur — ne pas tenter de rendre. - Lint.
npx hyperframes lint <project_path> --json. Traiter toutes les constatations de niveauerrorcomme des bloqueurs. Les avertissements sont transmis à l'orchestrateur ; laissez l'opérateur décider. - Inspect.
npx hyperframes inspect <project_path> --json. Résoudre tout débordement de texte ou échappement de zone signalé avant le rendu. Si le débordement est intentionnel pour une entrée/sortie, marquer l'élément avecdata-layout-allow-overflow(ou l'ancêtre avecdata-layout-ignorepour les éléments décoratifs) — ne pas désactiver la règle globalement. - Preview (opérateur uniquement).
npx hyperframes preview <project_path> --port <port>. Renvoyer l'URL du projet Studio (http://localhost:<port>/#project/<nom-du-projet>), pas le chemin sourceindex.html. - Render.
npx hyperframes render <project_path>avec les indicateurs résolus à partir derender_opts. Construire l'argument--variablesà partir derender_opts.variablesen utilisant une chaîne JSON sur une seule ligne. Toujours passer--strictet--strict-variablespour les exécutions d'éléments. - Vérifier la sortie. Après le rendu, vérifier que le MP4 existe et n'est pas nul. Journaliser dans
data/video-usage.jsonlavec{ ts, provider: "hyperframes", composition_id, render_args, duration_seconds, file_bytes, latency_ms }.
Sorties
lint:{ pass: boolean, errors: [...], warnings: [...] }.inspect:{ pass: boolean, findings: [...] }.render:{ artifact_path: string, duration_s: number, file_bytes: number, render_ms: number }.preview:{ url: string }.
Aide-mémoire des commandes
npx hyperframes init <nom> # échafaudage (utilisé une fois par élément par le générateur d'invite)
npx hyperframes lint <chemin> # valider le balisage
npx hyperframes inspect <chemin> # audit de mise en page/débordement
npx hyperframes preview <chemin> --port 3017 # développement local
npx hyperframes render <chemin> \
--fps 30 --quality standard --strict --strict-variables \
--variables '{"leads":42,"delta_pct":12}' \
--output outputs/<client>/<date>/<piece-id>/final.mp4
npx hyperframes doctor # vérification de l'environnement
npx hyperframes info # détails de version/environnement
Règles non négociables
- Ne jamais rendre sans une passe
lintetinspectréussie. Le pipeline n'a pas de chemin de récupération pour une composition malformée. - Ne jamais désactiver une constatation de lint ou inspect globalement — corriger le balisage, ou autoriser l'élément spécifique avec
data-layout-allow-overflow/data-layout-ignore. - Pour les éléments avec des variables déclarées, toujours passer
--strict-variables. Une faute de frappe dans un identifiant de variable doit échouer bruyamment, pas passer silencieusement à la valeur par défaut. - Pour les rendus de livraison finale,
--quality high. Pour les boucles d'itération,--quality draftpour économiser du calcul. - Le prétraitement des ressources (
tts,transcribe,remove-background) est hors de portée pour cette compétence — les invoquer via une future compétencehyperframes-mediaplutôt que de les intégrer ici.
Modes de défaillance
doctorsignale l'absence de FFmpeg ou Chrome : installer via les instructions de configuration du projet ; ne pas contourner.renderéchoue avecunknown variable: une clé passée via--variablesn'est pas déclarée dansdata-composition-variables. Corriger le balisage ou supprimer la surcharge.renderdépasse le budget de temps réel : abaisser--qualityàstandard, ou diviser la composition en sous-compositions et paralléliser via--workers.- Le MP4 de sortie a zéro octet : réexécuter
doctor; il s'agit presque toujours d'un crash de Chrome en cours de capture.
Compétences connexes
hyperframes: règles de création de compositions ; produit le projet que cette compétence valide et rend.hyperframes-prompt-builder: bref → spécification de composition ; s'exécute avant cette compétence.qa-tech-specs: s'exécute après cette compétence sur le MP4 rendu pour valider les spécifications de la plateforme.
Référence en amont
Compétence en amont complète (tous les indicateurs, matrice de dépannage, rendus paramétrés) : https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes-cli