Pour commencer, vérifiez que cette compétence est à jour avec l'utilisateur avant de l'exécuter :
npx hyperframes skills update talking-head-recut. Une opération rapide (no-op) si tout est à jour ; sinon, elle met à jour cette compétence ainsi que les compétences de domaine principales dont elle dépend avant de vous y fier.
Recadrage de Tête Parlante
Le Recadrage de Tête Parlante prend une vidéo locale qui joue intégralement et superpose une séquence de cartes graphiques chronométrées et conçues — titres, tiers-inférieurs, encarts de données, citations, panneaux latéraux, incrustation image-dans-l'image — synchronisées avec ce qui est dit. L'agent conçoit les cartes (temporisation et contenu) et écrit le HTML de chaque carte directement dans la conversation, puis assemble un fichier HTML de composition unique et le rend en MP4 via hyperframes. Il n'y a pas de liste d'archétypes fixes ni de structure de carte imposée — les visuels émergent de ce que dit la transcription.
La porte d'entrée est
/hyperframes. Cette compétence habille un clip vidéo de tête parlante existant avec des cartes graphiques conçues (titres, tiers-inférieurs, encarts de données, citations, panneaux latéraux, PiP) — pas de simples légendes (le texte des paroles). Le clip reste intact. Toute autre intention — simples sous-titres, graphique autonome, vidéo créée de zéro — ou toute incertitude → lisez d'abord/hyperframes: la couche d'intention décide de chaque route.
Jumeau graphique de
embedded-captions. Les légendes ajoutent les paroles sous forme de sous-titres lisibles ; celui-ci ajoute des graphiques conçus par-dessus la vidéo. Sous-titres simples →embedded-captions. Construire une vidéo de zéro → les workflows de création (product-launch-video/faceless-explainer/ …).
Acheminé via /hyperframes, la couche d'intention ne confirme que l'entrée (quel clip) et annonce les questions de stratégie de rendu comme des demandes différées — l'aspect, la disposition, le groupe de style, 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 les notes de l'utilisateur — lisez-le d'abord.
Fichiers intermédiaires inspectables dans le répertoire de travail :
metadata.json— durée / largeur / hauteur / images par secondeaudio.mp3— audio extraittranscript.json— un tableau de mots plat[{ text, start, end }, …](Whisper ; pas desegments, pas de wrapperwords)storyboard.json— plan léger des cartes (le plan de l'agent)public/cards/card-XX.html— un fragment HTML par cartepublic/index.html— composition finale assembléeoutput.mp4— vidéo rendue
Résolution CLI
# hyperframes — transcription (Whisper local) + rendu du HTML assemblé en MP4
npx hyperframes --help
Cette compétence fonctionne entièrement avec la CLI hyperframes plus ffmpeg / ffprobe système.
La transcription est Whisper locale via hyperframes transcribe — aucun service tiers, clé API, ou proxy limité.
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(distribué avec cette compétence, placé dans le répertoire de travail à l'Étape 9)
La transcription n'a besoin d'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 actuel à la racine de l'espace de travail ; tout ce qui suit s'écrit sous ce sous-répertoire.
VIDEO_PATH="/chemin/absolu/input.mp4"
WORK_DIR="videos/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"
3. Extraire l'Audio et les Métadonnées
# metadataené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 ; images par seconde = la fraction r_frame_rate évaluée, 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 une transcript.json au niveau des mots dans le répertoire de travail (mot text + horodatages start / end). Lisez-la pour les temporisations des mots/phrases qui pilotent le timing des cartes à l'Étape 6 ; regroupez vous-même les mots en phrases aux signes de ponctuation/pauses si vous avez besoin de segments de niveau phrase.
Limiter à la durée du média. Whisper peut renvoyer le end du dernier mot légèrement après la longueur réelle du clip — limitez chaque endSec de carte et composition.durationSeconds à la durée dans 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 mots — [{ "text": "...", "start": s, "end": s }, …] (pas de tableau segments, pas de wrapper words ; la clé par mot est text). Lisez-la et corrigez les erreurs évidentes de reconnaissance vocale :
- Homophones, noms de produits, termes techniques, ponctuation
- Modifiez le
textd'un mot sur place ; conservez ses horodatagesstart/end - Il n'y a pas de tableau
segmentspré-groupé — regroupez vous-même les mots en phrases (séparez à la ponctuation terminale / pauses) lorsque vous avez besoin de segments au niveau des phrases pour le timing des cartes
6. Ébaucher un Storyboard Léger (dans la discussion)
Pas de CLI impliquée. Lisez transcript.json + metadata.json et concevez directement les cartes. 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 timing et au contenu avant d'écrire le HTML de chaque carte. Gardez la structure cohérente avec l'exemple ci-dessous afin 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": "input-video.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 angoissée de minuit de l'intervenant",
"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 | lequel des 5 couleurs d'accent du thème cette carte utilise |
zone | énumération (voir ci-dessous) | où sur le canevas la carte se trouve |
contentHints | objet | conteneur libre ; l'agent met accroche/titre/détail/données/citation ici |
archetype (optionnel) | chaîne | étiquette libre que vous pouvez attacher pour mémoriser le motif d'une carte ; absent = libre, ce qui est le défaut |
transition (optionnel) | énumération : cut | fade | slide | wipe | transition déclarative entre cartes |
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 intérieure de 40px (ou 45% de la hauteur portrait) | contenu dense / annoté |
lower-third | bande inférieure de 30% | 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 majoritairement transparente | annotations superposées sur vidéo 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 en suivant le tableau ci-dessus. Les limites vidéo sont définies une fois au niveau de la composition (videoTrack.bounds) ; pour faire apparaître la vidéo « bouger entre les cartes », créez 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 — cela pourrait être uniquement des citations ou uniquement des données, cela pourrait commencer par un chiffre ou par une histoire. Laissez la transcription piloter le rythme.
Combien d'accroches ? — auto-déduction à partir 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'information. Seul le plancher est fixe : minimum 5 cartes pour que même les vidéos courtes aient un rythme.
Étape 1 — rythme de base par durée (le temps naturel par carte pour une densité moyenne) :
| durée vidéo | rythme de base (secondes par carte) | justification |
|---|---|---|
| < 60s (court métrage) | 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 de l'espace ; chaque carte porte plus |
| 10 – 30 min | 20–35s | rythme de cours / interview longue |
| > 30 min | 30–60s | épisodique, aspect quasi-chapitres |
Étape 2 — multiplicateur de densité (multiplie le rythme de base) :
| signal dans la transcription | multiplicateur | effet |
|---|---|---|
| Haute densité — nombreux chiffres, affirmations distinctes, rythme saccadé, énumération, une nouvelle idée toutes les 1 à 2 phrases | × 0.7 | coupes plus rapides, plus de cartes |
| Densité moyenne — flux mixte avec données et narration | × 1.0 | rythme de base |
| Faible densité — une histoire prolongée, reformulation répétée, rythme lent et réfléchi, un seul argument se déroulant | × 1.5 | coupes plus lentes, moins de cartes |
Étape 3 — calcul :
secPerCard = rythmeDeBase × multiplicateurDensité
cardCount = max(5, round(duréeVidéoSec / secPerCard))
Exemples (notez — pas de limite supérieure ; les vidéos longues produisent naturellement plus de cartes) :
- 30s de court métrage, une seule punchline (faible densité) → 7 × 1.5 = 10.5s/carte → round(30/10.5)=3 → plancher de 5 cartes
- 60s de monologue réfléchi (faible densité) → 10 × 1.5 = 15s/carte → 4 → plancher de 5 cartes
- 121s de tête parlante avec données riches (haute densité) → 10 × 0.7 = 7s/carte → 17 cartes
- 5 min d'interview, densité mixte → 16 × 1.0 = 16s/carte → 19 cartes
- 10 min d'analyse approfondie, haute densité → 16 × 0.7 = 11s/carte → 55 cartes
- 30 min de cours magistral, densité moyenne → 28 × 1.0 = 28s/carte → 64 cartes
- 1 h de podcast, faible densité → 45 × 1.5 = 67.5s/carte → 53 cartes
Lorsqu'une carte dure plus d'environ 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 décalées) — une phrase statique unique devient ennuyeuse après 8s. Pour les longues pièces où de nombreuses cartes dépassent 30s, envisagez de segmenter 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 de lint timeline_track_too_dense d'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.
Fin optionnelle. Cette compétence ne fournit pas de fin de marque fixe. Si l'utilisateur souhaite une carte de conclusion, concevez-en une vous-même (marque nominative + slogan d'une ligne, ~1.5-2s, fondu entrant -> court maintien -> fondu sortant), ajoutez-la à cards[], et étendez composition.durationSeconds à son endSec. Sinon, terminez sur la dernière carte de contenu.
7. Décider de la Stratégie de Rendu
Confirmer l'Orientation Visuelle avec l'Utilisateur (FAITES CECI D'ABORD)
Avant de commencer à concevoir des cartes ou à décider des limites, **demandez à l'utilisateur de choisir le format de sortie