Que fait ak:hyperframes ?
Enveloppe l'interface en ligne de commande hyperframes de HeyGen
pour la génération programmatique de vidéos HTML-first. Cette compétence est uniquement constituée de documentation et d'encapsulation —
ni code source HeyGen fourni, ni compétences d'agent HeyGen copiées. Chaque commande ci-dessous
utilise le package npm publié via npx, épinglé à une version connue.
Quand l'utiliser
- Vidéos courtes verticales/réseaux sociaux (1080×1920, 9:16) rendues à partir de HTML/CSS.
- Clips de lancement de produit, boucles promotionnelles, animations graphiques créées en HTML plutôt qu'avec des composants React ou des éditeurs de timeline.
- Toute tâche où la source de vérité de la composition est du balisage HTML avec
les attributs temporels
data-composition-id/data-start(voir references/composition-basics.md).
Ne convient pas pour les compositions React-first, les courbes d'interpolation image par image, ou l'écosystème audio/sous-titres de Remotion — voir aussi la compétence remotion installée pour cette alternative (vidéo programmatique basée sur React). Ne convient pas pour les tâches d'encodage pur avec FFmpeg/ImageMagick — voir aussi la compétence ak-media-processing.
Prérequis
- Node.js 22+
- FFmpeg dans le PATH
- Optionnel : une clé API HeyGen cloud/lambda (
HEYGEN_API_KEY) pour le rendu à distance ; le rendu local fonctionne sans.
Exécutez le vérificateur fourni avant de commencer tout travail de rendu :
node scripts/verify-prereqs.mjs
# ou, pour une sortie lisible par machine :
node scripts/verify-prereqs.mjs --json
Voir references/env-and-deps.md pour les instructions d'installation par plateforme et la note de vérification de version épinglée.
Version épinglée de la CLI
Chaque appel ci-dessous épingle [email protected] — la dernière version
publiée au 2026-08-07 (npm view hyperframes version). Mettez à jour cet épingleur
à un seul endroit (ce fichier + references/render-workflow.md) lors d'une mise à niveau ;
n'utilisez pas un npx -y hyperframes ... non épinglé dans des scripts ou de la documentation.
Workflow
La boucle standard est init → éditer HTML → prévisualiser → lint → rendre. Les
invocations concrètes complètes pour chaque étape se trouvent dans
references/render-workflow.md ; la forme abrégée :
# 1. Créer un nouveau projet de composition.
npx -y [email protected] init my-composition --resolution portrait
# 2. Éditer la composition HTML générée (voir composition-basics.md pour le
# contrat data-composition-id / data-start / data-width / data-height).
# 3. Prévisualiser dans un serveur de développement local.
npx -y [email protected] preview my-composition
# 4. Linter la composition avant le rendu (détecte les attributs temporels malformés).
npx -y [email protected] lint my-composition
# 5. Rendre en MP4.
npx -y [email protected] render my-composition --output ./assets/videos/my-composition.mp4
Exécutez toujours lint avant render — une composition qui passe le lint sans erreur
échoue bien moins souvent à l'étape de rendu qu'une composition qui passe directement au rendu.
Contrat de composition
Les compositions HyperFrames sont des fichiers HTML simples annotés avec
les attributs data-composition-id, data-start, data-width et data-height
sur les éléments racine. Voir
references/composition-basics.md pour la référence
complète des attributs et un exemple vertical complet en 1080×1920.
Documentation de référence
- references/heygen-skills.md — les 25 compétences d'agent
HeyGen auxquelles cet encapsuleur se réfère au lieu de les réimplémenter ; installez-les
via
npx -y [email protected] skillslorsqu'une expertise plus approfondie spécifique à HyperFrames (animation, images clés, sous-titres, modèles de lancement de produit, etc.) est nécessaire. - references/composition-basics.md — contrat des attributs de composition HTML avec un exemple complet en mode portrait.
- references/render-workflow.md — le flux complet
init → éditer → prévisualiser → lint → rendreavec chaque invocation épinglée. - references/env-and-deps.md — configuration de Node/FFmpeg/clé API par plateforme.
Dépannage
| Symptôme | Action |
|---|---|
command not found: ffmpeg | Exécutez node scripts/verify-prereqs.mjs pour la solution exacte pour votre plateforme. |
npx hyperframes signale un indicateur inconnu | La version épinglée dans ce fichier est peut-être en retard sur la version amont ; exécutez npx -y [email protected] --help pour confirmer les indicateurs actuels avant de mettre à jour l'épingleur. |
render échoue avec un MP4 vide/court | Exécutez d'abord lint ; la plupart des échecs de rendu sont dus à des attributs data-start/data-composition-id mal formés qui sont détectés par lint. |
| Rendu à distance/cloud nécessaire | Définissez HEYGEN_API_KEY selon references/env-and-deps.md, puis utilisez hyperframes cloud render (une commande distincte de premier niveau, pas un indicateur de render) — voir references/render-workflow.md. |
Voir aussi
- La compétence remotion installée (
ak-remotion) — génération de vidéo programmatique basée sur React ; utilisez-la lorsque la composition est naturellement un arbre de composants React plutôt qu'un balisage HTML. - La compétence ak-html-video — un autre encapsuleur HTML vers MP4
(
nexu-io/html-video) avec son propre workflow de modèle/Studio ; utilisez ak-hyperframes spécifiquement lorsque la tâche est une composition HeyGen HyperFrames. - La compétence ak-motion-graphics — routeur entre toutes les compétences vidéo/motion du dépôt ainsi que les packs de compétences motion externes.