heygen-com/hyperframes

Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution du plugin lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.

Tout d'abord, gardez cette compétence à jour — confirmez avec l'utilisateur avant d'exécuter : npx hyperframes skills update talking-head-recut. Une opération rapide sans effet si tout est à jour ; sinon, elle actualise cette compétence ainsi que les compétences de base du domaine dont elle dépend avant de les utiliser.

Recadrage d'Intervention

Le Recadrage d'Intervention prend une vidéo locale qui est lue en intégralité et y superpose une séquence de cartes graphiques minutées et conçues — titres, bandeaux inférieurs, appels de données, citations, panneaux latéraux, incrustations d'image dans l'image — synchronisées avec ce qui est dit. L'agent conçoit les cartes (minutage + contenu) et écrit le HTML de chaque carte directement dans la conversation, puis assemble une composition HTML unique et la rend en MP4 via hyperframes. Il n'y a pas de liste d'archétypes fixe ni de structure de carte prescrite — les superpositions émergent de ce que la transcription dit réellement.

La porte d'entrée est /hyperframes. Cette compétence habille un clip d'intervention existant avec des cartes graphiques conçues (titres, bandeaux inférieurs, appels de données, citations, panneaux latéraux, PiP) — pas de simples sous-titres (les paroles sous forme de texte). Le clip est lu sans modification. Toute autre intention — sous-titres simples, graphique autonome, vidéo créée de toutes pièces — ou toute incertitude → lisez d'abord /hyperframes : la couche d'intention possède chaque décision de routage.

Compagnon de l'habillage graphique de embedded-captions. Les sous-titres ajoutent les paroles sous forme de légende lisible ; celle-ci ajoute des graphiques conçus par-dessus la vidéo en cours de lecture. Sous-titres simples → embedded-captions. Créer une vidéo de toutes pièces → les workflows de création (product-launch-video / faceless-explainer / …).

Acheminée via /hyperframes, la couche d'intention confirme uniquement l'entrée (quel clip) et annonce les questions de stratégie de rendu comme des demandes différées — le format, le style, le groupe de styles et le nombre de cartes restent à l'étape 7, où les séquences analysées et la transcription fondent les recommandations ; les questions de forme d'exécution de la couche ne s'appliquent pas. Un BRIEF.md, lorsqu'il est présent, contient l'entrée confirmée et toutes les notes de l'utilisateur — lisez-le en premier.

Fichiers intermédiaires inspectables dans le répertoire de travail :

• metadata.json — durée / largeur / hauteur / images par seconde
• audio.mp3 — audio extrait
• transcript.json — un tableau de mots plat [{ text, start, end }, …] (Whisper ; pas de segments, pas d'enveloppe words)
• storyboard.json — aperçu léger des cartes (le plan de l'agent)
• public/cards/card-XX.html — un fragment HTML par carte
• public/index.html — composition finale assemblée
• output.mp4 — vidéo rendue

Résolution CLI

# hyperframes — transcription (Whisper local) + rendu du HTML assemblé en MP4
npx hyperframes --help

Cette compétence s'exécute entièrement sur la CLI hyperframes plus ffmpeg / ffprobe système. La transcription est locale Whisper via hyperframes transcribe — aucun service tiers, clé API ou proxy limité en débit.

Workflow

1. Vérifier l'Environnement

npx hyperframes doctor          # ffmpeg, navigateur sans tête, dépendances de rendu
# confirmer les ressources groupées :
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

Requis :

• ffmpeg / ffprobe (système)
• <SKILL_DIR>/assets/fonts/*.woff2, <SKILL_DIR>/assets/vendor/gsap.min.js (inclus dans cette compétence, placés dans le répertoire de travail à l'étape 9)

La transcription ne nécessite aucune clé — hyperframes transcribe exécute Whisper localement (étape 4).

Fortement recommandé sur macOS pour hyperframes render :

export PRODUCER_BROWSER_GPU_MODE=hardware

2. Créer un Répertoire de Travail

Tous les artefacts se trouvent sous videos/<nom-du-projet>/ — la même convention que les autres workflows vidéo (product-launch-video / faceless-explainer / pr-to-video). Gardez le répertoire de travail courant à la racine de l'espace de travail ; tout ce qui suit s'écrit sous ce sous-répertoire.

VIDEO_PATH="/chemin/absolu/entree.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. Extraire l'Audio et les Métadonnées

# métadonnées — durée / largeur / hauteur / images par seconde
ffprobe -v error -select_streams v:0 \
  -show_entries stream=width,height,r_frame_rate \
  -show_entries format=duration -of json "$VIDEO_PATH" > "$WORK_DIR/metadata.json"
# audio
ffmpeg -y -i "$VIDEO_PATH" -vn -acodec libmp3lame -q:a 2 "$WORK_DIR/audio.mp3"

Sorties : metadata.json (lire width/height/duration ; fps = la fraction r_frame_rate évaluée, p.ex. 30000/1001 → 29.97) + audio.mp3.

4. Transcrire

npx hyperframes transcribe "$WORK_DIR/audio.mp3" -d "$WORK_DIR" --json --model small.en

Whisper local — pas de clé API, pas de proxy, pas de limite de débit. Écrit un transcript.json au niveau des mots dans le répertoire de travail (text du mot + horodatages start/end). Lisez-le pour les horodatages des mots/phrases qui pilotent le minutage des cartes à l'étape 6 ; regroupez vous-même les mots en phrases à la ponctuation/aux pauses si vous avez besoin de segments par chapitre.

Limiter à la durée du média. Whisper peut retourner la end du dernier mot un peu au-delà de la durée réelle du clip — limitez chaque endSec de carte et composition.durationSeconds à la durée de metadata.json, sinon le rendu affichera une queue noire après la vidéo.

5. Corriger la Transcription

transcript.json est un tableau plat d'objets mot — [{ "text": "...", "start": s, "end": s }, …] (pas de tableau segments, pas d'enveloppe words ; la clé par mot est text). Lisez-le et corrigez les erreurs évidentes de RAP :

• Homophones, noms de produits, termes techniques, ponctuation
• Modifiez le text d'un mot sur place ; conservez ses horodatages start/end
• Il n'y a pas de tableau segments pré-groupé — regroupez les mots en phrases vous-même (divisez à la ponctuation terminale / aux pauses) lorsque vous avez besoin de segments par chapitre pour le minutage des cartes

6. Rédiger un Storyboard Léger (dans le chat)

Pas de CLI impliqué. Lisez transcript.json + metadata.json et concevez les cartes directement. storyboard.json est un artefact de planification interne à l'agent — aucune commande CLI ne le consomme ; il existe pour que vous puissiez réfléchir clairement au minutage et au contenu avant d'écrire le HTML de chaque carte. Gardez la forme cohérente avec l'exemple ci-dessous pour que le même plan puisse piloter la composition que vous rédigerez à l'étape 9 :

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42
  },
  "videoTrack": {
    "sourcePath": "video-entree.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "Accrocher avec la question angoissante du speaker à minuit",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "contentHints": {
        "kicker": "UNE QUESTION HONNÊTE",
        "title": "La question existentielle à 23h",
        "detail": "Message vocal de 60 secondes du client : 'Si le RMB s'apprécie, cela signifie-t-il que ma police en USD est une perte terrible ?'"
      }
    }
  ]
}

Champs de carte requis :

champ	type	but
id	chaîne	identifiant stable utilisé dans le HTML de la carte et les sélecteurs GSAP
intent	chaîne	description en langage naturel ; alimente la synthèse de la carte
startSec / endSec	nombre	temps en secondes (endSec > startSec)
accentIndex	0 | 1 | 2 | 3 | 4	laquelle des 5 couleurs d'accent du thème cette carte utilise
zone	énum (voir ci-dessous)	où sur le canevas la carte se trouve
contentHints	objet	sac libre ; l'agent met ici accroche/titre/détail/données/citation
archetype (optionnel)	chaîne	étiquette libre que vous pouvez joindre pour mémoriser le motif d'une carte ; absent = libre, par défaut
transition (optionnel)	énum : cut | fade | slide | wipe	transition déclarative de carte à carte

Cinq valeurs de zone :

zone	limites résolues	quand l'utiliser
fullscreen	couvre tout le canevas	moments héroïques, grands chiffres, mantras
whiteboard-area	marge de 40px (ou 45% de la hauteur portrait)	données denses / contenu annoté
lower-third	bande des 30% inférieurs	annotation sur vidéo visible
side-panel	42% à droite (paysage) ou 40% en bas (portrait)	données d'un côté, vidéo de l'autre
video-overlay	canevas complet, attend une carte largement transparente	annotations par-dessus la vidéo en plein écran

Lorsque vous assemblez la composition à l'étape 9, résolvez la zone de chaque carte en limites de pixels sur le conteneur hôte de la carte selon le tableau ci-dessus. Les limites de la vidéo sont définies une fois au niveau de la composition (videoTrack.bounds) ; pour faire apparaître la vidéo comme si elle « se déplaçait entre les cartes », rédigez des interpolations GSAP sur #video-wrap dans le <script> de la composition (voir étape 9).

Pas de rôles de carte prescrits, pas d'arc narratif prescrit. Les cartes émergent de ce que la vidéo dit réellement — il peut s'agir de toutes les citations ou de toutes les données, peut commencer par un chiffre ou par une histoire. Laissez la transcription piloter le rythme.

Combien de points clés ? — déduction automatique de la durée + densité. Pas de limite supérieure fixe. Choisissez un rythme de base à partir de la durée de la vidéo, puis ajustez en fonction de la densité d'informations. Seul le minimum est fixe : au moins 5 cartes pour que même les vidéos courtes aient un rythme.

Étape 1 — rythme de base par durée (le nombre naturel de secondes par carte pour une densité moyenne) :

durée vidéo	rythme de base (sec par carte)	justification
< 60s (courte vidéo)	6–8s	les spectateurs attendent des coupes rapides dans les formats courts
60s – 3 min	8–12s	rythme social normal
3 – 10 min	12–20s	laissez respirer ; chaque carte porte plus
10 – 30 min	20–35s	rythme de conférence / interview long
> 30 min	30–60s	épisodique, presque par chapitre

Étape 2 — multiplicateur de densité (multiplie le rythme de base) :

signal dans la transcription	multiplicateur	effet
Densité élevée — nombreux chiffres, affirmations distinctes, rythme saccadé, énumération, chaque 1–2 phrases est une nouvelle idée	× 0.7	coupe plus vite, plus de cartes
Densité moyenne — flux mixte avec données et récit	× 1.0	rythme de base
Densité faible — une seule histoire longue, reformulation répétée, rythme lent et réfléchi, un seul argument qui se dévoile	× 1.5	coupe plus lentement, moins de cartes

Étape 3 — calculer :

secParCarte = rythmeDeBase × multiplicateurDensité
nombreDeCartes = max(5, round(duréeVidéoSec / secParCarte))

Exemples (remarque — pas de limite supérieure ; les vidéos longues produisent naturellement plus de cartes) :

• Vidéo courte de 30s, un seul point clé (faible densité) → 7 × 1.5 = 10.5s/carte → round(30/10.5)=3 → plancher à 5 cartes
• Monologue réfléchi de 60s (faible densité) → 10 × 1.5 = 15s/carte → 4 → plancher à 5 cartes
• Intervention de 121s avec données riches (densité élevée) → 10 × 0.7 = 7s/carte → 17 cartes
• Interview de 5 min, densité mixte → 16 × 1.0 = 16s/carte → 19 cartes
• Analyse approfondie de 10 min, densité élevée → 16 × 0.7 = 11s/carte → 55 cartes
• Cours de 30 min, densité moyenne → 28 × 1.0 = 28s/carte → 64 cartes
• Podcast de 1 h, faible densité → 45 × 1.5 = 67.5s/carte → 53 cartes

Lorsqu'une carte dure plus de ~15s, prévoyez une carte plus riche (bloc de données, révélation en plusieurs étapes, plusieurs sous-points se déroulant avec des animations échelonnées) — un slogan statique devient ennuyeux après 8s. Pour les longs métrages où de nombreuses cartes dépassent 30s, envisagez de diviser la chronologie en sous-compositions (un .html par chapitre, monté avec data-composition-src) afin que la chronologie GSAP par fichier reste gérable — voir l'avertissement lint timeline_track_too_dense de HyperFrames.

content peut être une simple chaîne ("Titre : annualisé 5.69%\nNotes : …") ou toute forme JSON qui capture les données. L'agent décide de la forme par carte.

Sortie optionnelle. Cette compétence ne propose pas de sortie de marque fixe. Si l'utilisateur souhaite une carte de fin, concevez-en une vous-même de manière neutre (marque + slogan en une ligne, ~1.5–2s, fondu entrant -> courte pause -> fondu sortant), ajoutez-la à cards[] et prolongez composition.durationSec en conséquence. Bien que le moteur de rendu hyperframes prenne en charge les blocs de scène intégrés pour les sorties animées complexes, évitez de les utiliser dans le cadre de cette compétence sauf indication contraire de l'utilisateur — elles nécessitent une configuration que cette compétence ne couvre pas.

7. Affiner la Stratégie de Rendu avec l'Utilisateur

Avant d'écrire du HTML, confirmez quatre choix de rendu avec l'utilisateur. Présentez-les comme des décisions liées à la transcription que vous venez de lire — recommandez les meilleures options en fonction du rythme du locuteur et des indices visuels de la séquence d'ouverture :

1. Format (rapport hauteur/largeur) — Portrait (9:16) pour les Réels/TikTok/Shorts, Paysage (16:9) pour YouTube, Carré (4:5) pour les flux Facebook. Recommandez en fonction de la destination la plus probable de la vidéo.
2. Mise en page (disposition cartes sur la vidéo) — Plein écran (les cartes couvrent toute la vue ; la vidéo est en arrière-plan ou dans un petit encart), Paysage partagé (vidéo et cartes côte à côte, côte à côte), Portrait partagé (vidéo en haut, cartes en bas), Ancré (la vidéo occupe la majeure partie de l'écran ; les cartes sont en superposition flottante en bas).
3. Groupe de styles (palette visuelle) — Proposez des noms de style conceptuels basés sur le ton de la vidéo : Noir (haute définition, monochrome + une couleur d'accent), Élégant (arrière-plans subtils, typographie raffinée), Vibrant (couleurs vives, formes géométriques), Minimal (beaucoup d'espace blanc, cartes simples), ou tout autre groupe que vous concevez. Chaque groupe de style détermine un ensemble cohérent de polices, couleurs, dégradés, ombres portées et animations par défaut que vous utiliserez dans le HTML des cartes.
4. Nombre de cartes — Commencez par l'estimation basée sur la formule, mais ajustez en fonction de l'intuition humaine de l'utilisateur quant au rythme.

Important : Le nombre de cartes, le format, la mise en page et le thème de style sont déclarés dans storyboard.json au moment de la rédaction, pas en tant que commandes CLI distinctes — hyperframes render lit la composition et toutes les cartes à partir du répertoire de travail.

Si l'utilisateur préfère un contrôle plus fin sur le rythme visuel, proposez-lui de fournir des horodatages manuels ou des « points de chapitre » que vous utiliserez comme points d'ancrage pour les cartes.

Délégation de la configuration du groupe de styles. Si vous ne maîtrisez pas le HTML/CSS/GSAP nécessaire pour implémenter un groupe de styles, déléguez la tâche de conception à un autre agent ou à une invite d'IA générative spécialisée. Décrivez le groupe de style conceptuel et le format attendu (fichiers style.css + script.js qui définissent les animations d'entrée/sortie pour les cartes, les animations de transition, etc.) L'objectif est d'obtenir des ressources de style prêtes à l'emploi que vous pouvez placer dans votre répertoire de travail.

8. Écrire Chaque Carte Sous Forme de Fragment HTML

Pour chaque carte dans storyboard.json, écrivez un fichier HTML séparé dans public/cards/. Nommez-les card-01.html, card-02.html, etc. Chaque fragment est chargé dans le DOM principal via JavaScript — les fragments ne sont pas des pages autonomes.

Structure de chaque carte :

<div id="card-01" class="card"
     data-start="0.5"
     data-end="13.0"
     data-accent="0"
     data-zone="fullscreen"
     data-transition="fade">

  <div class="card-content">
    <!-- Contenu de la carte -- balisage sémantique, pas de présentation -->
    <p class="kicker">UNE QUESTION HONNÊTE</p>
    <h1 class="title">La question existentielle à 23h</h1>
    <p class="detail">"Si le RMB s'apprécie... perte terrible ?"</p>
  </div>

  <style>
    /* Styles propres à cette carte -- classes utilitaires, couleurs, polices */
  </style>
</div>

Règles de rédaction des fragments de carte :

• Chaque carte est une <div> autonome avec un id correspondant à storyboard.json et des attributs data-* pour le minutage et les métadonnées de zone.
• Le contenu doit être sémantique, pas de présentation — utilisez des titres (<h1>–<h3>), des paragraphes (<p>), des listes (<ul>/<ol>), blockquote pour les citations. Ne présumez pas des styles visuels appliqués globalement.
• Incluez un bloc <style> dans chaque fragment pour les polices, couleurs, marges, etc. propres à cette carte. Les styles globaux résident dans la composition <head>.
• Utilisez des classes et l'imbrication pour éviter les conflits de noms — chaque carte est chargée dans le DOM en même temps que les autres, donc les sélecteurs doivent être suffisamment spécifiques pour ne pas déborder sur les autres cartes.
• Animation. Ne mettez pas de code d'animation (GSAP) dans un fragment de carte. L'interpolation est orchestrée dans le <script> de la composition principale. Votre fragment de carte définit uniquement l'état statique (visible ou masqué).
• Attributs data-* :

attribut	but
data-start	heure de début en secondes
data-end	heure de fin en secondes
data-accent	index de la couleur d'accent (0–4)
data-zone	zone de mise en page (fullscreen, lower-third, …)
data-transition	transition d'entrée optionnelle (fade, slide, …)
data-archetype	étiquette de motif optionnelle (pour référence)

Validation du fragment. Avant de passer à l'étape 9, validez chaque fragment en vous assurant que :

• Tous les champs requis de storyboard.json sont présents
• Les horodatages sont cohérents avec la transcription (commence après le début du mot, se termine avant la fin du mot suivant)
• data-start et data-end sont dans les limites de durationSeconds de la composition
• data-accent est un entier entre 0 et 4
• data-zone est l'une des valeurs d'énumération connues

9. Assembler et Rendre

Écrivez public/index.html — un document HTML autonome qui charge toutes les cartes, définit les styles globaux et orchestre la chronologie d'animation GSAP. Le moteur de rendu hyperframes charge ce fichier dans un navigateur sans tête et en enregistre chaque image sous forme de trame vidéo.

Structure de l'assemblage :

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    /* Styles globaux : réinitialisation, définition de la scène, polices, thème */
    @font-face { font-family: 'Inter'; src: url('fonts/Inter-Regular.woff2') format('woff2'); }
    @font-face { font-family: 'Inter-Bold'; src: url('fonts/Inter-Bold.woff2') format('woff2'); }
    body {
      margin: 0; overflow: hidden;
      width: 1920px; height: 1080px;
      font-family: 'Inter', sans-serif;
    }
    #scene {
      position: relative; width: 100%; height: 100%;
      background: #000;
    }
    #video-wrap {
      position: absolute; top: 0; left: 0; width: 100%; height: 100%;
      /* Fond vidéo par défaut : ajustez la position/échelle de la vidéo ici */
    }
    .card {
      position: absolute; top: 0; left: 0; width: 100%; height: 100%;
      display: flex; align-items: center; justify-content: center;
      /* Style de zone par défaut à remplacer par carte */
    }
    /* Styles globaux de carte */
    .card-content { max-width: 80%; text-align: center; }
  </style>
</head>
<body>
  <div id="scene">
    <div id="video-wrap">
      <!-- La vidéo sera injectée par le moteur de rendu -->
    </div>
    <!-- Les fragments de carte sont chargés ici dynamiquement -->
    <div id="cards-container"></div>
  </div>

  <script src="vendor/gsap.min.js"></script>
  <script>
    // 1. Charger chaque fragment de carte depuis public/cards/card-XX.html
    // 2. Analyser les attributs data-* pour le minutage
    // 3. Configurer une chronologie GSAP :
    //    - À data-start : animer l'entrée de la carte (opacité, position, échelle)
    //    - À data-end : animer la sortie de la carte
    //    - Utiliser les interpolations GSAP (to, fromTo) — pas CSS transitions
    //    - Gérer les chevauchements (carte B qui commence avant que A ne soit terminée)
    // 4. S'assurer que la vidéo s'affiche correctement en arrière-plan via #video-wrap
    //
    // Conseil clé : la chronologie doit faire avancer le temps de manière absolue.
    // N'utilisez pas la lecture en temps réel de GSAP — définissez la timeline à la durée
    // de la composition et appelez .progress() ou .seek() pour chaque image.
    // Le moteur de rendu hyperframes fait avancer le temps image par image.
  </script>
</body>
</html>

Directives pour le <script> de la composition :

1. Chargement des cartes : Utilisez fetch() ou une boucle pour charger chaque fragment HTML et insérez leur contenu dans #cards-container.
2. Orchestration de la chronologie : Créez une chronologie GSAP principale (gsap.timeline()) et ajoutez des interpolations pour l'entrée et la sortie de chaque carte à leurs horodatages respectifs. Pour chaque carte :
   • À startSec, animez la carte visible (opacity: 1, y: 0, scale: 1, etc.)
   • À endSec, animez la carte masquée (opacity: 0, y: -20, scale: 0.95, etc.)
   • Pour les transitions de zone (ex. fade, slide), appliquez le type d'interpolation correspondant (fadeIn, slideFromLeft, etc.)
3. Gestion des chevauchements : Si les cartes se chevauchent, assurez-vous que l'ordre de superposition (z-index) est cohérent et que la carte sortante conserve sa visibilité jusqu'à ce que la carte entrante soit complètement visible.
4. Ancrage de la vidéo : Aucun élément vidéo réel n'est nécessaire dans le HTML — le moteur de rendu hyperframes injecte la vidéo source dans #video-wrap en tant qu'élément <video>. Si vous devez déplacer/redimensionner la vidéo entre les cartes (ex. passer du plein écran à l'incrustation image dans l'image), animez les propriétés CSS de #video-wrap (transformer, width, height, top, left) sur la chronologie principale.

Chargement des ressources : Au début de l'étape 9, copiez

• <SKILL_DIR>/assets/fonts/*.woff2 → $WORK_DIR/public/fonts/
• <SKILL_DIR>/assets/vendor/gsap.min.js → $WORK_DIR/public/vendor/gsap.min.js

Ensuite, dans index.html, référencez ces chemins comme .-relatifs à public/.

Validation de la composition. Avant le rendu :

• Tous les fragments de carte sont-ils présents dans public/cards/ ?
• Les horodatages sont-ils dans les limites de composition.durationSeconds ?
• data-transition est-il valide si présent ?
• La chronologie GSAP est-elle correctement initialisée ?

Pour le rendu, exécutez :

npx hyperframes render "$WORK_DIR" --config "$WORK_DIR/public/index.html" -o "$WORK_DIR/output.mp4"

Commentaires importants sur le rendu :

• Le mode GPU pour le rendu est fortement recommandé, en particulier sur macOS avec PRODUCER_BROWSER_GPU_MODE=hardware. Sans cela, le rendu peut être lent ou instable.
• Le rendu est une opération synchrone et gourmande en ressources. Assurez-vous que le système dispose de suffisamment de RAM et de CPU.
• Si le rendu échoue, vérifiez les journaux de la console du navigateur sans tête pour les erreurs JavaScript. Les problèmes courants sont les erreurs de syntaxe dans les fragments de carte, les chemins de polices manquants ou les erreurs de chronologie GSAP.

---

Commandes CLI de Référence Rapide

# Vérification de l'environnement
npx hyperframes doctor

# Transcription locale Whisper
npx hyperframes transcribe <audio.mp3> -d <work-dir> --json --model small.en

# Rendu de la composition en MP4
npx hyperframes render <work-dir> --config <work-dir>/public/index.html -o <work-dir>/output.mp4

# Mise à jour de la compétence (après confirmation de l'utilisateur)
npx hyperframes skills update talking-head-recut

# Extraire les métadonnées vidéo
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,r_frame_rate -show_entries format=duration -of json <video.mp4>

# Extraire l'audio de la vidéo
ffmpeg -y -i <video.mp4> -vn -acodec libmp3lame -q:a 2 <audio.mp3>

Dépendances

• hyperframes — CLI principale (transcription, rendu)
• ffmpeg/ffprobe — extraction audio, métadonnées
• Whisper (local, intégré à hyperframes) — transcription, aucune clé API nécessaire
• GSAP (GreenSock Animation Platform) — animations de carte (inclus dans les ressources de la compétence)
• Polices — fichiers .woff2 inclus dans les ressources de la compétence
• Navigateur sans tête — pour le rendu via hyperframes

Résolution des Problèmes

Problème	Cause probable	Solution
Queue noire à la fin de la sortie	Horodatages de carte dépassant la durée vidéo	Limitez tous les horodatages endSec et composition.durationSeconds à metadata.json durée
Rendu lent	Mode CPU par défaut	Définissez PRODUCER_BROWSER_GPU_MODE=hardware (macOS)
Carte manquante dans la sortie	Fragment HTML non chargé ou erreur de sélecteur	Vérifiez le chemin du fragment, les attributs data-*, le code de chargement JS
La vidéo ne s'affiche pas	Élément vidéo manquant ou chemin source erroné	Vérifiez que le chemin source de la vidéo est correct dans la configuration du rendu ; n'utilisez pas de balise <video> explicite — hyperframes render l'injecte
Erreur de transcription	Fichier audio manquant ou modèle Whisper non trouvé	Vérifiez que audio.mp3 existe et que la transcription s'exécute à partir du répertoire de travail correct

Avertissements

• Troncature : Ne dépasser jamais la durée vidéo réelle. Whisper peut générer un dernier horodatage de mot légèrement supérieur à la durée — réduisez-le toujours.
• Performances : Pour les vidéos de plus de 30 minutes avec de nombreuses cartes, envisagez de diviser en sous-compositions pour maintenir la chronologie GSAP gérable.
• Pas de vidéo d'entrée : Cette compétence n'accepte que les vidéos préexistantes. Pour une création à partir de zéro, utilisez les workflows de création de vidéo (product-launch-video / faceless-explainer).
• Pas de sous-titres : Pour les sous-titres simples des paroles, utilisez embedded-captions.

---

Documentation de compétence pour Talking Head Recut — version 3.0