/hyperframes-best-practices
Utilisez ce skill chaque fois que vous transformez un screencast brut, un enregistrement tête parlante ou une exportation OBS en une vidéo produit HyperFrames soignée. Il regroupe deux couches de connaissances :
- Les fondamentaux d'HyperFrames — les fichiers de règles en amont maintenus par HeyGen sur
github.com/heygen-com/hyperframes(création de compositions, timelines GSAP, attributsdata-*, CLI de boucle de développement). Installez vianpx vskill i heygen-com/hyperframes. - Les règles de production — leçons tirées d'un long cycle d'itération pour construire une véritable vidéo produit SpecWeave à partir d'un seul enregistrement OBS de 8:47. Ce sont les règles qui, si elles sont suivies, produisent une vidéo que l'utilisateur peut réellement distribuer — et, si elles sont enfreintes, laissent des bips, des coupures en milieu de mot, des scènes héroïques vides et des superpositions qui bloquent la caméra faciale de l'orateur.
Lisez les deux couches avant de créer.
Portée et applicabilité
Les règles de la couche 2 ci-dessous proviennent d'un projet spécifique : la transformation d'un enregistrement d'introduction SpecWeave de 8:47 (Anton Abyzov, capture OBS, tête parlante + partage d'écran, mai 2026) en une vidéo promotionnelle prête pour la production de 6:00. Elles reflètent l'apparence et la convivialité de ce produit — l'esthétique des cartes teintées Studio, la palette violette/verte de SpecWeave, un style de superposition de cartes iOS, et les réalités techniques des enregistrements OBS (ticks de démarrage/arrêt, artefacts transitoires de reprise d'enregistrement, prises en double suite à la ré-enregistrement de la même ligne trois fois).
Les constantes exactes sont spécifiques au projet — positions des superpositions pour cet emplacement de caméra faciale, le texte de correction
Boris Cherny / Anthropic, les statistiques600+/500+/3K+— traduisez, ne copiez pas.Utilisez cette couche comme référence pour la technique sous-jacente : l'algorithme de coupe intelligente basé sur la transcription, le fondu par clip pour la suppression des transitoires, le pipeline de rendu du filtre
concatqui évite les clics du démultiplexeur concat, le nettoyeur de bips par muet chirurgical, le modèle de superposition de cartes iOS, le mappage temps source → temps coupé, le piège de l'invalidation du cache de forme d'onde Studio — ceux-ci se généralisent.
Quand utiliser
Déclenchez ce skill lorsque L'UN de ces éléments s'applique :
- Un utilisateur a un screencast brut ou un enregistrement OBS et souhaite une vidéo resserrée, sous-titrée et avec une marque.
- La source comporte des blancs, des silences interrompus ou des prises en double "laissez-moi réessayer".
- La source comporte des clics, des bips ou des artefacts transitoires aux limites d'enregistrement.
- L'utilisateur souhaite des superpositions graphiques (annotations, cartes de statistiques, révélations de marque, logos d'outils) qui ne couvrent pas la caméra faciale de l'orateur.
- L'utilisateur a dit les mots "rendre ceci prêt pour la production" ou "prêt à distribuer".
- L'utilisateur a mentionné vouloir un "style keynote Apple" ou "cartes hover iOS" ou "verre givré".
Si L'UN de ces signaux est présent, suivez ce workflow. Si l'utilisateur souhaite simplement une carte de titre rapide sur une source propre, le skill amont hyperframes seul suffit.
Le pipeline (10 phases)
┌──────────────────────────────────────────────────────────────────┐
│ Phase 0 Inventaire des outils │
│ Phase 1 Sonder la source (durée, codec, taux d'échantillonnage audio)│
│ Phase 2 Transcrire avec Whisper (horodatages au mot près) │
│ Phase 3 Détecter les silences + changements de scène │
│ Phase 4 Construire la liste de coupe intelligente (avec tampons)│
│ Phase 5 Nettoyer les bips transitoires (muet chirurgical + adeclick)│
│ Phase 6 Rendre le master via le filtre concat (un seul passage) │
│ Phase 7 Générer l'imagerie héroïque (Gemini 3 Pro Image) │
│ Phase 8 Créer la composition HyperFrames (cartes iOS) │
│ Phase 9 Linter + vérifier dans Studio │
└──────────────────────────────────────────────────────────────────┘
Exécutez les phases séquentiellement. Itérez à l'intérieur d'une phase, pas entre les phases — une mauvaise liste de coupe casse chaque timing de superposition en aval, et vous passerez une heure à résoudre les ancres. Obtenez d'abord la liste de coupe correcte, puis rendez une fois, puis construisez les superpositions par rapport à la timeline finale.
Phase 0 — Inventaire des outils
Avant de commencer, confirmez que ceux-ci sont disponibles. Le skill suppose macOS / Linux ; sur Windows, utilisez WSL.
| Outil | Utilisé pour | Installation |
|---|---|---|
ffmpeg (>= 6.0) | Tout traitement vidéo/audio | brew install ffmpeg |
ffprobe | Inspection du flux | fourni avec ffmpeg |
whisper (paquet Python OpenAI) | Transcription avec horodatages au mot près | pip install openai-whisper |
python3 | Scripts de liste de coupe / nettoyeur de bips | système |
npx hyperframes@latest | CLI de composition (aperçu, rendu, lint) | npx hyperframes init <projet> |
| API Gemini 3 Pro Image | Images héroïques (optionnel) | variable d'environnement GEMINI_API_KEY |
vskill (>= 1.0) | Installation de skills | npm i -g vskill |
Si Whisper n'est pas installé, pip install openai-whisper l'installe. N'utilisez pas large-v3 ou large-v3-turbo sur CPU — ils prennent 10 à 15 minutes pour un audio de 8 minutes. Utilisez base.en pour un monologue technique en anglais : ~30s, suffisamment précis pour les limites de mots.
Si la machine d'un utilisateur a auto-editor installé, ignorez-le — il fait des coupes de silence mais pas de nettoyage de bips ou de tampons de limites de mots, et il génère des coupes de 50+ segments irrégulières. Nous faisons mieux à la main.
Phase 1 — Sonder la source
Avant de faire quoi que ce soit d'autre, apprenez la forme du fichier :
ffprobe -v error -show_entries stream=index,codec_type,codec_name,width,height,r_frame_rate,duration,sample_rate,channels \
-show_entries format=duration,size,bit_rate -of json "$SRC" | tee source_meta.json
Choses que vous devez savoir :
- Durée totale — conduit tous les calculs de coupe.
- Fréquence d'images — OBS enregistre souvent à 60 ips ; HyperFrames Studio lit à 30 ips en interne pour le défilement. Multipliez les secondes × 30 pour obtenir les numéros d'images Studio, pas les secondes × ips source. Cela induit les gens en erreur.
- Codec audio et taux d'échantillonnage — OBS enregistre couramment
pcm_s24leà 48 kHz. Réencodez en AAC 192k pour la livraison ; gardez 48 kHz pour correspondre à tous les outils en aval. - Conteneur —
.movde DaVinci,.mkvd'OBS — les deux conviennent, ffmpeg lit les deux.
Sauvegardez le sondage sur le disque pour que les phases ultérieures puissent le relire sans re-sonder.
Phase 2 — Transcrire avec Whisper
Les horodatages au mot près sont le fondement. Sans eux, vous ne pouvez pas :
- Accrocher les limites de coupe aux bords des mots (éviter les coupures en milieu de mot).
- Détecter les prises en double (même ligne dite 2 à 3 fois).
- Placer les ancres de superposition par rapport aux moments de parole plutôt qu'aux temps de coupe qui dérivent.
Extrayez d'abord l'audio pour que Whisper obtienne un WAV mono 16 kHz propre (économise 80% du CPU par rapport à la pleine qualité) :
mkdir -p .work
ffmpeg -hide_banner -y -i "$SRC" -vn -ac 1 -ar 16000 -c:a pcm_s16le .work/source.wav
Exécutez Whisper avec des horodatages de mots et une sortie JSON :
whisper .work/source.wav \
--model base.en \
--language en \
--word_timestamps True \
--output_dir .work \
--output_format json \
--verbose False
⚠️ Piège du CLI Whisper : passer --output_format json --output_format srt conserve uniquement le dernier indicateur dans les versions plus anciennes. Si vous avez besoin de plusieurs, utilisez --output_format all (écrit JSON + SRT + VTT + TSV + TXT).
Validez la sortie : .work/source.json doit contenir segments[].words[] avec start, end, word. Si words est vide, vous avez oublié --word_timestamps True.
Lisez la transcription complète à ce stade. Ne la sautez pas. Vous repérerez :
- Des erreurs de transcription de noms de marque. Whisper entend "Claude Code at Anthropic" comme "Cloud Code at Infropic" 90% du temps. "SpecWeave" devient "spec with" ou "specs". Ceux-ci nécessitent des corrections de superposition, pas un ré-enregistrement.
- Des prises en double. Recherchez la même phrase répétée textuellement. Dans notre projet, "And those systems cannot produce skills as you work" est apparu trois fois à 01:14, 01:30, 01:47. Supprimez-en deux.
- Des redémarrages de remplissage. Des fragments d'un seul mot comme "And…", "And…" précédant la phrase réelle. Le script de coupe les détecte comme des segments "fantômes" — nous les supprimons à la phase 4.
Phase 3 — Détecter les silences et les changements de scène
Deux détections parallèles alimentent l'algorithme de coupe :
3a. Détection de silence
ffmpeg -hide_banner -nostats -i "$SRC" -af "silencedetect=noise=-30dB:duration=1.2" -f null - 2>&1 \
| grep -E "silence_(start|end)"
-30 dB et 1,2s sont le point idéal. Plus lâche (-25 dB, 0,8s) attrape des pauses de respiration que vous ne voulez pas couper. Plus serré (-35 dB, 2s) manque les véritables blancs. Analysez les paires début/fin en [(s, e, dur), ...] et écrivez dans silences.json. Voir scripts/build_cuts.py.
3b. Détection de changement de scène
ffmpeg -hide_banner -nostats -i "$SRC" -filter:v "select='gt(scene,0.05)',showinfo" -f null - 2>&1 \
| grep "showinfo" | grep -oE "pts_time:[0-9.]+" | sed 's/pts_time://' > scenes.txt
scene>0.05 est suffisamment sensible pour détecter l'orateur ouvrant un nouvel onglet de navigateur, changeant d'application, défilant significativement. N'allez pas en dessous de 0.03 — vous aurez des faux positifs à cause des clignements de curseur.
Ces deux ensemble vous permettent de prendre la décision de coupe intelligente : silence + pas de changement de scène = pur blanc, coupez-le. Silence + changement de scène = l'orateur montre quelque chose à l'écran, gardez-le (le public est censé regarder l'écran, pas entendre la narration).
Phase 4 — Construire la liste de coupe intelligente
L'algorithme de coupe a 5 règles strictes acquises à la dure :
Règle 1 — Le pur blanc est coupé, mais pas entièrement
Pour chaque segment silencieux > MIN_CUT_LEN (1,5s) sans changement de scène à l'intérieur : coupez tout sauf une RESPIRATION de 0,30s. La respiration préserve le rythme naturel — éliminer 100% du silence rend le discours mécanique.
if not in_scenes and (cut_end - cut_start) > MIN_CUT_LEN:
cuts.append((cut_start + 0.30, cut_end, f"blanc {dur:.1f}s"))
Règle 2 — Les silences avec activité d'écran restent (plafonnés à 3,5s)
Si le silence a des changements de scène, l'orateur laisse le public lire. Gardez la fenêtre de première_scène - 0,4s à dernière_scène + 0,8s, mais jamais plus de 3,5s — fixer une même image au-delà de 3,5s perd les gens.
Règle 3 — Accrocher aux limites des mots
Après avoir calculé les plages approximatives à garder, accrochez chaque limite au bord de mot le plus proche de Whisper, avec une tolérance de 0,4s :
def snap(t, mots):
meilleur, bd = t, 0.4
for s, e, _ in mots:
for candidat in (s, e):
if abs(candidat - t) < bd:
meilleur, bd = candidat, abs(candidat - t)
return meilleur
C'est ce qui empêche les coupes de couper en milieu de mot. Sans cela, une coupe sur deux coupe un 's' final ou une consonne respiratoire.
Règle 4 — Ajouter des tampons de limites de mots (c'est celui que les utilisateurs remarquent)
Même avec l'accrochage aux bords de mots, les consonnes finales s'étendent légèrement au-delà de l'horodatage de fin de mot rapporté par Whisper. Whisper chronomètre le début de la voyelle à la fin de la voyelle, pas la queue de consonne. Donc une coupe littérale à mot.fin coupe le 's' final, la respiration ou le 'k'.
La correction : étendez chaque plage à conserver :
- Fin :
+ 0,30saprès la fin du dernier mot, plafonné à la moitié de l'écart jusqu'au prochain segment conservé. - Début :
- 0,10savant le début du premier mot, plafonné à la moitié de l'écart jusqu'au segment conservé précédent.
END_BUF, START_BUF = 0.30, 0.10
for i, (s, e) in enumerate(garder):
ecart_suivant = garder[i+1][0] - e if i+1 < len(garder) else TOTAL - e
ecart_prec = s - garder[i-1][1] if i > 0 else s
ajout_fin = min(END_BUF, max(0, ecart_suivant * 0.5))
ajout_debut = min(START_BUF, max(0, ecart_prec * 0.5))
if ecart_suivant < 0.6: ajout_fin = max(ajout_fin, ecart_suivant - 0.05)
if ecart_prec < 0.6: ajout_debut = max(ajout_debut, ecart_prec - 0.05)
final.append([s - ajout_debut, e + ajout_fin])
Le résultat : la coupe "trouver les tickets" s'étend de src 08:09.26 à 08:09.56 — le 's' final survit. Sans cela, l'utilisateur vous dira que l'audio "semble précipité" ou "avale les fins".
Règle 5 — Suppression manuelle des prises en double
La déduplication programmatique de n-grammes identiques est fragile et dangereuse (elle peut supprimer des répétitions légitimes). Au lieu de cela : lisez la transcription, trouvez vous-même les doublons textuels, et ajoutez des plages de suppression explicites en temps source :
DUP_RANGES = [
(78.86, 113.82), # 01:18.86 - 01:53.82 : 2 des 3 prises de "skills as you work"
]
for ds, de in DUP_RANGES:
# réduit chaque segment conservé qui chevauche cette plage
...
Réduit la coupe de 35% économisés à 32% économisés (les doublons sont des écarts silencieux + parole), mais le résultat se lit proprement.
Sortie
Le script écrit :
cuts.json— plages conservées + plages coupées + statistiques récapitulatives + mappage temps source (utilisé par la Phase 8 pour les ancres de superposition).edl.txt— EDL lisible par l'homme avec des extraits de transcription par segment conservé (vérifiez-le visuellement avant le rendu).
Voir scripts/build_cuts.py pour l'implémentation complète.
Phase 5 — Nettoyer les bips transitoires
Les enregistrements OBS contiennent souvent de courts artefacts transitoires — bips de démarrage, clics de commutation de touches, plosives de micro sur une entrée chaude. Ceux-ci traversent les décisions de coupe de silence parce qu'ils sont forts (donc la détection de silence les ignore) et qu'ils sont entourés de silence. Ils sonnent comme un "tic" dans la vidéo finale à 4:11 ou 0:52 ou ailleurs.
N'essayez pas de corriger cela avec un noise gate ou un débruitage global. Vous étalerez les consonnes et rendrez le discours comme sous l'eau. Au lieu de cela : détectez les transitoires et réduisez chirurgicalement au silence chaque fenêtre de 60 à 100 ms.
Algorithme de détection (celui qui ne réduit pas la parole au silence)
Un transitoire est un "bip" ssi :
RMS(fenêtre 5ms) > BEEP_RMS_MIN (par ex., > 800)
RMS(précédent 150ms) < PRE_QUIET (par ex., < 200)
RMS(suivant 200ms) < POST_QUIET (par ex., < 350)
La troisième condition est critique. Sans elle, vous attraperez les débuts de consonnes ('p', 't', 'k') de la parole, car ils ont la même apparence dans les 5 premières ms — mais la parole est suivie d'une voyelle soutenue, tandis qu'un bip revient au silence. Filtrez sur post_avg < 350 et vous ne réduisez au silence que les transitoires isolés.
Limitez également la durée réduite au silence à 0,30s — une mauvaise classification ne peut jamais effacer un mot.
Appliquer les mises en sourdine chirurgicales
Construisez une expression de filtre volume ffmpeg avec les plages ciblées :
volume=enable='between(t,52.110,52.180)+between(t,169.850,169.920)+between(t,251.245,251.295)':volume=0
Astuce adeclick
Après les muets chirurgicaux, appliquez un filtre adeclick doux pour reconstruire la forme d'onde traversant la transition muette — sans cela, les bords du muet sont des transitions instantanées qui elles-mêmes sonnent comme des clics :
ffmpeg -i cut_master.mp4 -af "adeclick=window=0.02:overlap=0.75:threshold=100" -c:v copy clean_master.mp4
window=0.02 (20ms) est suffisamment court pour éviter d'affecter les phonèmes adjacents. threshold=100 est agressif — testez sur votre master réel et augmentez à 200 si vous entendez des artefacts intermédiaires.
Phase 6 — Rendre le master via le filtre concat (un seul passage)
N'utilisez pas le démultiplexeur concat. Le démultiplexeur concat: nécessite que tous les segments aient exactement les mêmes codecs, profils, résolutions, et taux d'échantillonnage audio, et il introduit des clics aux limites de segment parce qu'il effectue une concaténation au niveau du paquet sans ré-échantillonnage de la forme d'onde. En utilisant le filtre concat, vous forcez un ré-échantillonnage audio cohérent.
Construire le script de rendu
Générez un script shell contenant l'ensemble des segments conservés en tant que flux d'entrée, enfilés dans un filtre concat :
#!/bin/bash
INPUTS=""
FILTERS=""
C=0
while IFS= read -r line; do
S=$(echo "$line" | cut -d' ' -f1)
E=$(echo "$line" | cut -d' ' -f2)
INPUTS+=" -ss $S -to $E -i \"$SRC\""
FILTERS+="[$C:v][$C:a]"
((C++))
done < derivation_keeps.txt
FILTERS+="concat=n=$C:v=1:a=1[outv][outa]"
eval ffmpeg -hide_banner $INPUTS -filter_complex "$FILTERS" -map "[outv]" -map "[outa]" cut_master.mp4
Points clés :
-ssavant-i(saut rapide) est correct ici — l'erreur d'image clé est inférieure à 0,5s et le filtre concat se synchronise sur les PTS, pas sur les horodatages précis.- Ne pas ré-encoder la vidéo. La vidéo passe par le filtre
concatavec recopie au niveau du paquet (pas de ré-encodage). Seul l'audio est ré-échantillonné. Donc la sortiecut_master.mp4est de la vidéo originale au niveau de qualité en termes de codec. - Vérifiez la sortie audio. Si vous entendez des clics entre les segments conservés, votre
concatperd la synchronisation de la forme d'onde — augmentez la taille de la fenêtre d'étalonnage du filtre (peu de gens le font).
Phase 7 — Générer l'imagerie héroïque (Gemini 3 Pro Image)
Les prises de contrôle à fond perdu ou les scènes héroïques nécessitent une image générée sur mesure. Nous utilisons Gemini 3 Pro Image plutôt qu'une requête de recherche d'actifs, car les images générées par IA correspondent à la palette de couleurs/esthétique sans nécessiter de retouche. Le prompt typique :
"Un diagramme abstrait de niveau conceptuel de nœuds de software engineering connectés par des lignes lumineuses, sur fond dégradé violet foncé à indigo, pas de texte, style épuré à la Apple keynote, 16:9"
Téléchargez l'image dans le projet :
curl -o assets/hero-concept.jpg "$IMAGE_URL"
Rappels importants :
- Taille de l'image : au moins 1920×1080, de préférence 3840×2160 pour permettre un léger zoom/pan de Ken Burns.
- Pas de texte dans l'image. Le texte doit être dans vos calques de texte HTML/CSS HyperFrames. Le texte généré par IA dans les images a des artefacts et n'est pas accessible.
- Palette de couleurs : les images doivent correspondre à l'éclairage de votre maquette — une palette claire pour un produit de consommation, une palette sombre pour un outil de développeur. Notre projet SpecWeave a utilisé une palette sombre (violet foncé → indigo) parce que le screencast de démonstration était un IDE avec un thème sombre.
Phase 8 — Créer la composition HyperFrames (cartes iOS)
C'est ici que la vidéo passe de "screencast brut" à "vidéo produit". La composition est un document HTML sur lequel HyperFrames s'appuie pour le rendu. Une composition typique de notre projet :
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Video produit SpecWeave</title>
<script src="https://unpkg.com/hyperframes-studio@latest/dist/hf-standalone.js"></script>
</head>
<body>
<hf-composition>
<!-- Prise de contrôle héroïque -->
<hf-scene id="hero" duration="5.0" background="#0d0f1a">
<hf-image src="/assets/hero-concept.jpg" fit="cover"></hf-image>
<hf-text class="hero-title" position="center" font-size="80" color="#f0f0ff">
SpecWeave — Skills d'IA, versionnés
</hf-text>
<hf-text class="hero-sub" position="center" y="100" font-size="32" color="#a0a0bb">
Skills reproductibles pour des agents d'ingénierie
</hf-text>
</hf-scene>
<!-- Carte en verre givré avec icône de marque -->
<hf-scene id="card-stat-1" duration="4.0">
<hf-video src="/cuts/cut_master.mp4" volume="1.0"></hf-video>
<hf-overlay class="glass-card ios-card top-right">
<div class="card-inner">
<img src="/icons/github-logo.svg" class="brand-icon" />
<p class="stat-main">600+</p>
<p class="stat-sub">skills publiés</p>
</div>
</hf-overlay>
</hf-scene>
<!-- Carte de métrique avec icône personnalisée -->
<hf-scene id="card-stat-2" duration="2.5">
<hf-video src="/cuts/cut_master.mp4" volume="1.0" offset="00:00:12.34"></hf-video>
<hf-overlay class="glass-card ios-card bottom-left">
<div class="card-inner">
<img src="/icons/anthropic-logo.svg" class="brand-icon" />
<p class="stat-main text-gradient">Anthropic</p>
<p class="stat-sub">construit sur Claude</p>
</div>
</hf-overlay>
</hf-scene>
</hf-composition>
<style>
.glass-card {
background: rgba(255,255,255,0.08);
backdrop-filter: blur(8px);
border-radius: 16px;
padding: 16px 24px;
border: 0.5px solid rgba(255,255,255,0.12);
color: white;
font-family: 'SF Pro Display', system-ui, sans-serif;
transition: all 0.2s ease;
box-shadow: 0 4px 30px rgba(0,0,0,0.4);
}
.glass-card:hover { backdrop-filter: blur(12px); background: rgba(255,255,255,0.12); }
.card-inner { display: flex; align-items: center; gap: 12px; }
.brand-icon { width: 32px; height: 32px; }
.stat-main { font-size: 24px; font-weight: 700; margin: 0; }
.stat-sub { font-size: 14px; color: rgba(255,255,255,0.6); margin: 0; }
.text-gradient {
background: linear-gradient(135deg, #a855f7, #6366f1);
-webkit-background-clip: text;
-webkit-text-fill-color: transparent;
}
.top-right { position: fixed; top: 20px; right: 20px; }
.bottom-left { position: fixed; bottom: 20px; left: 20px; }
</style>
<script>
// Animations GSAP facultatives — initialisées par HyperFrames automatiquement
</script>
</body>
</html>
Règles de superposition :
- Les cartes flottent sur le dessus de la vidéo plein écran — la vidéo est la scène de fond, les cartes sont placées en superposition avec
position: fixed. - La caméra faciale (coin inférieur gauche) n'est jamais masquée. Si la composition a un emplacement de caméra faciale, les cartes se positionnent en haut à droite ou en haut à gauche. Si la superposition est en bas, centrez-la ou décalez-la vers la droite. Dans notre projet, cela signifiait : pas de cartes en bas à gauche (là où se trouvait le flux de la caméra faciale).
- Utilisez les vraies icônes de marque — SVG vectoriel, pas de PNG. Cela donne un aspect professionnel et cohérent avec les directives de marque. Extrayez les SVG des sites web des marques ou des kits de marque.
- Le verre givré (backdrop-filter: blur) n'est pas disponible dans tous les environnements d'exécution. Testez dans le Studio lui-même. Si la superposition semble opaque (pas de flou), le Studio applique un
background-color: rgba(0,0,0,0.7)de secours. Acceptez-le.
Mappage temps source → temps coupé
Lorsque vous placez une superposition sur un extrait vidéo, vous devez apparier le temps source (horodatage dans l'enregistrement OBS original) au temps coupé (car l'extrait a été raccourci). Le script de coupe génère ce mappage dans cuts.json :
{
"mapping": [
{"src_s": 0.0, "cut_s": 0.0},
{"src_s": 15.2, "cut_s": 14.7},
...
]
}
Pour chaque superposition, trouvez le temps source que vous souhaitez et lisez le temps coupé correspondant. Passez offset à la balise <hf-video> (en format HH:MM:SS.ms).
Animations GSAP
Ajoutez de subtiles animations GSAP pour faire entrer/sortir les cartes avec fondu et léger décalage :
// Dans la section <script> de la composition
hf.onReady(() => {
gsap.from(".glass-card", {
opacity: 0, y: 30, duration: 0.8, ease: "power2.out",
stagger: 0.15
});
});
Ne surchargez pas. Un fondu de 0,8s avec un décalage de 15% entre les cartes est suffisant. Des animations plus longues donnent l'impression que la vidéo est "lente".
Phase 9 — Linter et vérifier dans Studio
Avant de rendre la composition finale, exécutez le lint HyperFrames :
npx hyperframes lint composition.html
Pièges courants du lint (appris à la dure) :
-
Cache de forme d'onde Studio. Studio met en cache les formes d'onde audio analysées. Si vous remplacez
cut_master.mp4par une nouvelle version, Studio affiche toujours l'ancienne forme d'onde, donc la superposition semble décalée. Solution : effacez le cache manuellement :rm -rf node_modules/.cache/hyperframesou, dans Studio, cliquez sur le menu ⋮ de la piste audio et sélectionnez "Re-analyser". -
Incompatibilité du taux d'échantillonnage audio. Si votre OBS source était à 48 kHz mais que vous avez ré-encodé en 44.1 kHz à un moment donné, HyperFrames Studio peut jouer l'audio avec des artefacts (vitesse/pitch). Gardez le 48 kHz d'un bout à l'autre.
-
Texte de superposition coupé. Les superpositions avec
position: fixedet les coins arrondis (border-radius) peuvent couper le texte si le conteneur de la carte n'a pas depaddingadéquat. Nous utilisonspadding: 16px 24pxdans toutes les cartes. -
Animations GSAP non initialisées. Si GSAP n'est pas chargé avant l'appel
hf.onReady, l'animation échoue silencieusement. Chargez GSAP depuis un CDN avant le script de composition :<script src="https://unpkg.com/[email protected]/dist/gsap.min.js"></script>. -
Chemin vidéo original. Le chemin dans
<hf-video src="...">doit être un chemin relatif ou absolu accessible par le serveur de développement Studio. Si vous utilisezsrc="/cuts/cut_master.mp4", assurez-vous que le dossiercuts/se trouve à la racine du projet. Studio sert le répertoire de travail comme racine du serveur de fichiers.
Vérification finale :
- Jouez l'intégralité de la composition dans Studio, pas seulement les premières 30s. Les bips transitoires apparaissent souvent plus tard.
- Vérifiez chaque superposition de marque : l'icône s'affiche-t-elle ? Le texte se lit-il correctement ? L'icône de la marque est-elle une image SVG vectorielle (pas un PNG flou) ?
- Vérifiez les bords de coupe : chaque coupe correspond-elle à une fin de mot naturelle ? Si vous entendez des clips de début/fin de mot, votre logique de tampon est désactivée.
- Vérifiez la durée par rapport à la cible. La longueur cible de notre projet était de 6:00 ; le rendu final était de 5:58 — suffisamment proche.
Scripts de référence
Deux scripts Python complets sont inclus dans ce dépôt de skill :
- scripts/build_cuts.py — Implémente la Phase 4 (construction de la liste de coupe intelligente avec tampons) + la Phase 5 (détection et muet des bips). Comprend toute la logique : analyse des silences, détection de scène, accrochage aux limites de mots, tampons, déduplication manuelle, mappage temps source → temps coupé, et génération EDL. Exécutez :
python3 scripts/build_cuts.py. - scripts/render_cuts.sh — Implémente la Phase 6 (rendu via le filtre concat en un seul passage). Lit les plages conservées depuis
derivation_keeps.txtet exécute la commande ffmpeg. Exécutez :bash scripts/render_cuts.sh. - scripts/render_pipeline.sh — Orchestre les phases 0 à 6 d'un coup pour une exécution CI/CD. Optionnel — les phases 0 à 6 conviennent également à l'exécution manuelle.
Références du skill
| Ressource | Emplacement |
|---|---|
| Base de connaissances HyperFrames | github.com/heygen-com/hyperframes |
| Dépôt de ce skill (avec scripts) | github.com/anton-abyzov/hyperframes-best-practices |
| Documentation du package Whisper | github.com/openai/whisper |
| Documentation de l'API Gemini 3 Pro Image | https://ai.google.dev/gemini-api/docs/image-generation |
| Documentation du filtre concat ffmpeg | ffmpeg.org/ffmpeg-filters.html#concat |
Licence
MIT — utilisez, adaptez, distribuez. Soyez attentif à la couche 2 si vous appliquez les règles de production à un projet d'apparence très différente. Les algorithmes sont robustes ; les constantes esthétiques ne le sont pas.