Pont Hyperframes
Orchestré par : SKILL. Wrapper de dépendance externe. Le monorepo Hyperframes se trouve dans
../../external/hyperframes/(cloné par/amw-initétape 6 si l'utilisateur accepte, OU par ce skill lors du premier rendu en secours). Ce skill documente le modèle d'appel shell ; il ne contient PAS le monorepo.
Aperçu
Rend des compositions HTML en vidéo MP4 en appelant le monorepo Hyperframes (external/hyperframes/). Accepte un seul fichier HTML ou un dossier de projet Hyperframes complet. Exécute la séquence de pré-rendu obligatoire (lint → validate → inspect → render) avant d'appeler npx hyperframes render --output <mp4>. Retourne le chemin du MP4 et un rapport d'achèvement. Pas de réimplémentation du pipeline Hyperframes dans le plugin — uniquement des appels shell.
Instructions
- Vérifier le repo externe avec deux contrôles :
external/hyperframes/package.jsondoit exister, etnpx hyperframes render --helpdoit répondre ; échouer immédiatement si l'un des deux échoue. - Résoudre le répertoire du projet : utiliser
project_dirs'il est fourni, ou créer un projet temporaire à partir dehtml_scene_path; échouer immédiatement si aucun n'est fourni. - Exécuter la séquence de pré-rendu dans l'ordre :
lint → validate → inspect → render(abandonner si une étape retourne un code non nul). - Exécuter
cd "$HF_PROJ_DIR" && npx hyperframes render --output <mp4>; collecter le chemin de sortie. - Confirmer que le fichier MP4 existe et n'est pas vide ; signaler le chemin de sortie et les éventuels avertissements d'
inspect. - Voir la section
## Modèle d'appelci-dessous pour les étapes d'exécution faisant autorité.
Activation
Pas de commande slash dédiée — ce skill n'a pas de raccourci /amw-* correspondant. Invoqué par l'orchestrateur design-principles comme dernière étape de la Phase B en mode Agent Principal lorsque la conception approuvée nécessite une sortie vidéo MP4. L'orchestrateur peut appliquer l'ensemble du pipeline d'appel Hyperframes et les techniques de composition de ce skill sans restriction de couche de commande.
Ce skill est autonome et auto-suffisant — n'importe quel agent (l'agent principal, un sous-agent ou un orchestrateur externe) peut l'utiliser en lisant ce SKILL.md et ses références. Les techniques du skill ne sont PAS limitées à ce que les commandes correspondantes exposent.
Position dans le flux
SORTIE (Phase B — terminale). Pipeline de rendu HTML vers MP4. Déclenché uniquement lorsque l'utilisateur souhaite explicitement rasteriser une composition HTML en fichier vidéo. S'exécute en dernier, une fois la composition terminée.
Conditions de déclenchement
Invoquer ce skill UNIQUEMENT lorsque la requête correspond à l'un des cas suivants :
- « rendre ce HTML en vidéo » / « rendre en MP4 »
- « HTML vers MP4 » / « site web en vidéo » / « page en vidéo »
- « créer une vidéo à partir de cette composition HTML »
- « rasteriser la composition en vidéo »
- Mention explicite d'Hyperframes /
hyperframes render/.hf.html
Ne PAS invoquer sur les mentions génériques d'« animation », « mouvement », « lecture vidéo » ou « composant animé » — celles-ci relèvent de :
../amw-design-principles/starter-components/animations.html(timeline Stage + Sprite dans le navigateur)../amw-pretext/(mouvement typographique —pretext-art/est une redirection obsolète)- Le propre pipeline de l'utilisateur
Prérequis
-
binaires d'exécution (prérequis système) : Node.js >= 22, git
-
binaires d'exécution (installés par
/amw-init) : Bun (gestionnaire de paquets d'Hyperframes), FFmpeg. Chrome est géré par Hyperframes lui-même viahyperframes browser ensure(utilise Puppeteer +@puppeteer/browsersen interne — PAS Playwright). -
source externe :
../../external/hyperframes/— le monorepo Hyperframes cloné depuishttps://github.com/heygen-com/hyperframes. Cibler v0.4.30 ou ultérieur pour le support d'inspect,--hdretdata-variable-values. Si le dossier n'existe pas,/amw-initou ce skill DOIVENT le cloner avant de continuer :git clone --branch v0.4.30 --depth 1 https://github.com/heygen-com/hyperframes.git external/hyperframes cd external/hyperframes && bun install
Contrat d'entrée
Le pont accepte deux entrées mutuellement exclusives. Fournir exactement une :
| Champ | Type | Description |
|---|---|---|
html_scene_path | string (optionnel) | Chemin absolu vers un fichier HTML unique. Le pont crée un répertoire de projet Hyperframes temporaire via mktemp -d -t hf-XXXXXX (portable POSIX), y écrit le HTML comme index.html, effectue le rendu, puis nettoie après avoir écrit le rapport. |
project_dir | string (optionnel) | Chemin absolu vers un répertoire de projet Hyperframes existant (contient index.html et éventuellement compositions/, assets/). Le pont se place directement dedans — pas de création de structure. Prend en charge les sous-compositions, l'audio et les ressources externes. |
Si les deux sont fournis, project_dir l'emporte. Si aucun n'est fourni, échouer immédiatement.
Modèle d'appel
-
Vérifier le repo externe — deux contrôles requis :
# Contrôle 1 — package.json présent (monorepo cloné) test -f "external/hyperframes/package.json" || exit-fail "monorepo introuvable" # Contrôle 2 — CLI répond (installation fonctionnelle) # @hyperframes/cli n'est PAS publié sur npm — doit être exécuté depuis l'espace de travail du monorepo (cd external/hyperframes && npx hyperframes render --help) >/dev/null 2>&1 || exit-fail "CLI hyperframes non fonctionnelle — exécutez bun install dans external/hyperframes/"Si l'un des contrôles échoue, échouer immédiatement. Ne pas continuer.
-
Résoudre le répertoire du projet.
- Si
project_direst fourni : l'utiliser directement. DéfinirHF_PROJ_DIR="$project_dir". - Si
html_scene_pathest fourni : créer un projet temporaire :HF_PROJ_DIR="$(mktemp -d -t hf-XXXXXX)" cp "$html_scene_path" "$HF_PROJ_DIR/index.html" - Sinon : échouer immédiatement.
- Si
-
Exécuter la séquence de pré-rendu :
lint → validate → inspect → render.cd "$HF_PROJ_DIR" npx hyperframes lint npx hyperframes validate npx hyperframes inspect --json # abandonner en cas d'erreurs (sortie non nulle avec --strict)Voir TECH-hyperframes-cli-lint, TECH-hyperframes-cli-validate, TECH-hyperframes-cli-inspect.
[TECH-hyperframes-cli-inspect.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Drapeaux · Sortie (mode JSON) · Exemple minimal · Attributs d'exclusion · Pièges · Références croisées [TECH-hyperframes-cli-validate.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Sortie · Quand les avertissements apparaissent · Exemple minimal · Pièges · Références croisées [TECH-hyperframes-cli-lint.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Exemple minimal · Pièges · Références croisées
Note sur la séquence de vérification : La séquence du pont (
lint → validate → inspect → render) étend intentionnellement celle en amont (lint → inspect → preview → render— voir le SKILL.md de la CLI Hyperframes dans le monorepoexternal/hyperframes/) en ajoutantvalidatepour les pipelines Phase B non supervisés et en supprimantpreview(une primitive de boucle de développeur).
- Rendu. Depuis le répertoire du projet résolu :
Drapeaux supplémentaires si nécessaire (cd "$HF_PROJ_DIR" npx hyperframes render --output <chemin-abs-mp4>--fps,--quality,--format,--hdr, etc.) — voir TECH-hyperframes-cli-render.
[TECH-hyperframes-cli-render.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Drapeaux · Conseils qualité · Vidéo transparente · Exemple minimal · Réglage des workers · Pièges · Références croisées
- Retourner le chemin du MP4 à l'appelant. Si le répertoire du projet était temporaire (
html_scene_path), le supprimer après avoir écrit le rapport.
Règles de composition HTML (spécifiques à Hyperframes)
Les compositions utilisent du HTML simple avec des attributs data-* de timeline sur une racine #stage et ses enfants (pistes / clips / superpositions). C'est le même modèle mental Stage + Sprite que ../amw-design-principles/starter-components/animations.html — Hyperframes l'étend avec le mixage audio/vidéo multi-pistes et le rendu déterministe hors écran.
Attributs clés (le schéma faisant autorité se trouve dans external/hyperframes/packages/core/ une fois cloné) :
data-composition-id— identifiant au niveau de la scènedata-start,data-duration— secondes, par clipdata-track-index— ordre des calques (pistes vidéo / superposition / audio)data-width,data-height— dimensions du canevas au niveau de la scène
N'introduisez PAS Framer Motion, GSAP en tant que dépendance, ou tout autre moteur d'animation tiers dans le pont. Hyperframes a son propre modèle d'adaptateur de trame ; si l'utilisateur souhaite GSAP dans une composition, c'est le problème d'Hyperframes, pas celui du pont.
Références
Index complet des références : INDEX.md — 32 fichiers TECH-*.md regroupés par pipeline Capture (7 étapes), commandes CLI (12), rédaction de composition (7), Registre (4). Chaque fichier a sa propre table des matières ; chargez uniquement celui dont vous avez besoin.
Exemples
Voir les exemples travaillés dans les fichiers de référence par étape sous ./references/TECH-hyperframes-capture-step-*.md (pipeline site-web-vers-vidéo en 7 étapes) et le guide de rédaction de composition à TECH-hyperframes-composition-core.
[TECH-hyperframes-composition-core.md] Ce qu'il fait · Quand l'utiliser · Comment il fonctionne · Approche (ordre narratif) · Squelette d'un seul fichier · Porte d'identité visuelle (OBLIGATOIRE — avant d'écrire le HTML) · Pièges · Références croisées
Sortie
Un fichier vidéo MP4 rendu plus un rapport d'achèvement de tâche. Le MP4 est produit par npx hyperframes render --output <mp4> depuis le répertoire du projet résolu ; le pont confirme que le fichier existe et n'est pas vide avant de signaler le succès. Contrat complet ci-dessous.
Sortie et liste de vérification d'achèvement
Le contrat de sortie complet (règles d'inférence des chemins d'artefacts, forme du rapport d'achèvement, liste de vérification obligatoire) se trouve dans TECH-output-contract. Deux sorties sont obligatoires :
- Artefacts — dossier du projet Hyperframes + MP4 rendu. Le chemin est déduit du projet (chemin utilisateur → convention du framework →
./design/<sous-type>/→ solution de repli./design/videos/). - Rapport d'achèvement de tâche à
$MAIN_ROOT/reports/webdesigner/<ts±tz>-amw-video-producer-<slug>-<8-char-hash>.mdlistant chaque artefact + le verdict par élément de la liste.
Avant de signaler l'achèvement : chaque élément de la liste dans TECH-output-contract DOIT être PASS ou N/A. Tout FAIL déclenche une boucle de correction.
Ressources
../amw-design-principles/starter-components/animations.html— le moteur de timeline Stage + Sprite d'environ 50 lignes utilisé pour les aperçus dans le navigateur ; Hyperframes partage le même rythme.../../bin/amw-html-export.py— PAS un substitut.html-exportrend une seule image en PNG/PDF ; Hyperframes rend une vidéo MP4 multi-images en utilisant Puppeteer + Chrome (géré parhyperframes browser ensure) + FFmpeg.../amw-dev-browser/— PAS un substitut.dev-browserest destiné à l'entrée/l'automatisation ; Hyperframes est le rasteriseur de sortie./amw-init— installe Bun, FFmpeg et cloneexternal/hyperframes/lors de la première utilisation. Chrome pour le rendu est provisionné par Hyperframes lui-même viahyperframes browser ensure.- Dépôt externe :
https://github.com/heygen-com/hyperframes
Non-négociables
- Utiliser le monorepo externe via appel shell. Ne PAS réimplémenter son pipeline dans le plugin.
- Ne PAS vendre la source d'Hyperframes dans
skills/— 500+ fichiers est une portée trop large pour un skill. - Ne PAS substituer
dev-browserà Hyperframes — ils résolvent des problèmes opposés (entrée vs. sortie). - Ne PAS substituer
html-export.py— une image PNG unique n'est pas une vidéo. - L'utilisateur DOIT exécuter
/amw-initavant la première utilisation pour installer Bun + FFmpeg et cloner le repo externe. Chrome est provisionné en exécutant(cd external/hyperframes && npx hyperframes browser ensure)une fois après le clonage.
Gestion des erreurs
Les modes de défaillance courants et les mesures correctives se trouvent dans TECH-error-handling. Couvre : repo externe manquant, provisionnement de Bun/FFmpeg/Chrome, erreurs d'analyse des attributs HTML, échecs d'encodage vidéo, clones obsolètes.