Visite de Dépôt GitHub — Vidéo Défilante avec Narration Synchronisée & Sous-titres
Dépend de : website-to-hyperframes — chargez-le avant de commencer. Son workflow en 6 étapes et ses fichiers de référence s'appliquent ici. Cette compétence spécialise ce workflow pour les visites défilantes sur une seule page avec narration et sous-titres visibles.
Ce que Produit Cette Compétence
Une vidéo portrait 1080x1920 (format Instagram Reels) qui :
- Affiche une page de dépôt GitHub — capture d'écran plein écran en mode mobile, défilement fluide de haut en bas sur 15 à 30 secondes.
- Narre la visite — voix IA ElevenLabs décrivant ce qui est à l'écran, synchronisée avec la position de défilement.
- Grave les sous-titres à l'écran — superposition de légendes mot par mot qui met en évidence chaque mot au moment où le narrateur le prononce. Le spectateur lit en écoutant.
- Se termine par un CTA — appel à l'action « Star on GitHub » ou « Follow for more ».
Décisions Clés
| Décision | Valeur | Pourquoi |
|---|---|---|
| Dimensions | 1080x1920 | Format principal Instagram Reels |
| Durée | 15–30 secondes | Zone idéale pour l'engagement Shorts/Reels |
| Narration | Dicte le rythme | La vitesse de défilement, les durées des segments et le timing des sous-titres dérivent tous de l'audio |
| Sous-titres | Surbrillance mot par mot | Chaque mot s'illumine lorsque le narrateur le dit — style Karaoké |
| Vue téléphone | Plein écran défilant, sans bordure | La page GitHub remplit tout le canevas 1080x1920 |
| Dossier de sortie | github-promos/<repo>-tour/ | Au même niveau que les projets github-repo-promo |
Structure des Répertoires
github-promos/
<repo>-tour/
index.html ← Composition HyperFrames principale
package.json ← issu de hyperframes init
hyperframes.config.json ← Configuration HyperFrames
SCRIPT.md ← Script de narration avec horodatages
assets/
repo-page.png ← Capture d'écran GitHub plein écran (mode sombre, vue mobile)
narration.mp3 ← Voix off ElevenLabs
renders/ ← MP4 générés
Workflow
Étape 0 : Capturer les Infos du Dépôt & la Capture d'Écran
Utilisez web-search ou fetch_url pour obtenir les métadonnées du dépôt :
- Étoiles, forks, watchers, issues ouvertes
- Langage principal, description, sujets
- Résumé du README (ce que fait le projet, fonctionnalités clés)
Utilisez ensuite la compétence screenshot pour capturer une capture d'écran plein écran, mode sombre, vue mobile :
use_skill("screenshot")
// URL : https://github.com/{propriétaire}/{dépôt}
// Pleine page, mode sombre
// Viewport : 390px de large (mobile iPhone 14) — la capture doit
// capturer toute la hauteur de la page en largeur mobile
// Enregistrer sous : github-promos/<repo>-tour/assets/repo-page.png
Obtenez les dimensions de la capture (vous avez besoin de la hauteur en pixels pour le calcul du défilement) :
sips -g pixelHeight github-promos/<repo>-tour/assets/repo-page.png
sips -g pixelWidth github-promos/<repo>-tour/assets/repo-page.png
Étape 1 : Rédiger le Script de Narration
Rédigez un script de 15 à 30 secondes qui décrit ce que le spectateur voit au fur et à mesure que le défilement progresse. Le narrateur guide le spectateur à travers la page :
[0s–4s] "Ceci est {dépôt}. {description en une ligne}."
[4s–8s] "Voici le README — l'installation est une seule commande."
[8s–13s] "Parcourir la liste des fonctionnalités — {mentionner 2-3 fonctionnalités visibles}."
[13s–18s] "{étoiles} étoiles, {forks} forks, et une communauté grandissante."
[18s–23s] "Mettez une étoile sur GitHub. Lien dans la bio."
[23s–25s] "Suivez pour plus."
Règles pour le script :
- Le narrateur fait référence à ce qui est actuellement à l'écran à chaque position de défilement.
- Nombre total de mots : 50–75 mots (rythme confortable pour 15–30 secondes).
- Pas de remplissage (« euh », « hum », « laissez-moi vous montrer »). Chaque mot compte.
- Terminer par un CTA clair.
Étape 2 : Générer la Voix Off via ElevenLabs
curl -s -X POST "https://api.elevenlabs.io/v1/text-to-speech/AZnzlk1XvdvUeBnXmlld" \
-H "xi-api-key: $ELEVENLABS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "SCRIPT_COMPLET_ICI",
"model_id": "eleven_multilingual_v2",
"voice_settings": {
"stability": 0.35,
"similarity_boost": 0.8,
"style": 0.25,
"use_speaker_boost": true
}
}' \
--output github-promos/<repo>-tour/assets/narration.mp3
Vérifiez que le fichier existe et a une taille > 0.
Étape 3 : Transcrire & Cartographier le Temps
Après avoir généré l'audio, extrayez les horodatages au niveau du mot :
Option A : Horodatages ElevenLabs (renvoyés avec la réponse de l'API si output_format: "mp3" n'est pas le seul format de sortie — consultez la documentation de l'API pour la sortie aligned).
Option B : Utiliser ffmpeg + Whisper (transcription locale avec horodatages des mots) :
# Installer whisper si besoin
pip install openai-whisper
# Transcrire avec horodatages des mots
whisper github-promos/<repo>-tour/assets/narration.mp3 \
--model base \
--output_format json \
--output_dir github-promos/<repo>-tour/assets/ \
--word_timestamps True
La sortie vous donne words[] avec les horodatages start et end pour chaque mot. Associez ces horodatages aux positions de défilement.
Étape 4 : Construire la Composition HyperFrames
Créez index.html en suivant l'architecture de composition HyperFrames :
<!DOCTYPE html>
<html lang="fr">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=1080,height=1920"/>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800;900&display=swap" rel="stylesheet">
<style>
/* ── Racine & Canevas ── */
* { margin: 0; padding: 0; box-sizing: border-box; }
#root {
position: relative;
width: 1080px;
height: 1920px;
background: #0d1117;
font-family: 'Inter', sans-serif;
overflow: hidden;
}
/* ── Capture d'écran défilante ── */
.scroll-container {
position: absolute;
inset: 0;
width: 1080px;
height: 1920px;
overflow: hidden;
}
.scroll-content {
position: absolute;
top: 0;
left: 0;
width: 1080px;
height: VAR_IMG_H px; /* hauteur réelle de la capture d'écran */
}
/* ── Superposition de sous-titres ── */
.subtitle-bar {
position: absolute;
bottom: 180px;
left: 50%;
transform: translateX(-50%);
width: 1000px;
text-align: center;
z-index: 100;
}
.subtitle-word {
display: inline-block;
font-size: 42px;
font-weight: 700;
color: rgba(255,255,255,0.35);
padding: 0 4px;
transition: color 0.08s, transform 0.08s;
}
.subtitle-word.active {
color: #FFFFFF;
transform: scale(1.08);
}
.subtitle-word.past {
color: rgba(255,255,255,0.65);
}
/* ── Barre de progression du défilement ── */
.scroll-progress-track {
position: absolute;
right: 16px;
top: 100px;
width: 5px;
height: 1720px;
border-radius: 3px;
background: rgba(255,255,255,0.1);
z-index: 50;
}
.scroll-progress-thumb {
position: absolute;
top: 0;
left: 0;
width: 5px;
height: VAR_THUMB_H px;
border-radius: 3px;
background: linear-gradient(180deg, #58a6ff, #3fb950);
z-index: 51;
}
/* ── Superposition CTA (Segment 6-7) ── */
.cta-overlay {
position: absolute;
inset: 0;
display: flex;
flex-direction: column;
align-items: center;
justify-content: center;
background: rgba(13,17,23,0.92);
backdrop-filter: blur(8px);
z-index: 200;
opacity: 0;
}
.cta-title {
font-size: 56px;
font-weight: 800;
color: #e6edf3;
text-align: center;
}
.cta-subtitle {
font-size: 32px;
color: #8b949e;
margin-top: 16px;
}
.cta-button {
margin-top: 40px;
padding: 18px 48px;
background: #238636;
color: #e6edf3;
font-size: 28px;
font-weight: 700;
border-radius: 999px;
box-shadow: 0 0 30px rgba(35,134,54,0.5);
}
.follow-pill {
margin-top: 24px;
padding: 12px 28px;
background: rgba(22,27,34,0.8);
border: 1px solid #30363d;
border-radius: 999px;
font-size: 22px;
color: #e6edf3;
font-weight: 600;
}
</style>
</head>
<body>
<div id="root"
data-composition-id="{repo}-tour"
data-width="1080"
data-height="1920"
data-start="0"
data-duration="{total_seconds}">
<audio id="narration-audio"
src="assets/narration.mp3"
data-start="0"
data-duration="{total_seconds}"
preload="auto"></audio>
<!-- Capture d'écran défilante (plein canevas) -->
<div class="scroll-container">
<img class="scroll-content" src="assets/repo-page.png" />
</div>
<!-- Barre de progression du défilement -->
<div class="scroll-progress-track">
<div class="scroll-progress-thumb" id="scroll-thumb"></div>
</div>
<!-- Superposition de sous-titres -->
<div class="subtitle-bar" id="subtitle-bar">
<!-- Mots injectés par JS, un <span class="subtitle-word"> par mot -->
</div>
<!-- Superposition CTA (5 dernières secondes) -->
<div class="cta-overlay" id="cta-overlay">
<div class="cta-title">Star on GitHub</div>
<div class="cta-subtitle">{description du dépôt}</div>
<div class="cta-button">github.com/{propriétaire}/{dépôt}</div>
<div class="follow-pill">@githubprojects</div>
</div>
</div>
<script>
// ── Calcul du défilement ──────────────────────────────────────────
var IMG_H = /* hauteur réelle de la capture d'écran */;
var CANVAS_H = 1920;
var MAX_SCROLL = IMG_H - CANVAS_H;
var THUMB_TRACK = 1720;
var THUMB_H = Math.round(THUMB_TRACK * (CANVAS_H / IMG_H));
var THUMB_TRAVEL = THUMB_TRACK - THUMB_H;
function thumbTop(scrollY) {
return (Math.abs(scrollY) / MAX_SCROLL) * THUMB_TRAVEL;
}
// ── Horodatages des Mots ─────────────────────────────────────
// Collez les horodatages au niveau du mot de l'Étape 3 ici.
// Format : [mot, secondeDebut, secondeFin]
var WORDS = [
// ["Ceci", 0.0, 0.3],
// ["est", 0.3, 0.5],
// ["mercury-skills", 0.5, 1.0],
// ...
];
var TOTAL_DURATION = /* durée totale en secondes de l'audio */;
// ── Construire les Spans de Sous-titres ────────────────────────────────
var subtitleBar = document.getElementById("subtitle-bar");
var wordSpans = [];
WORDS.forEach(function(w, i) {
var span = document.createElement("span");
span.className = "subtitle-word";
span.textContent = w[0];
subtitleBar.appendChild(span);
wordSpans.push(span);
});
// ── Timeline GSAP ───────────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});
// Phase 1 : Défilement (0s à ~80% de la durée totale)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;
// Défilement de haut en bas avec atténuation
tl.to(".scroll-content", {
y: -MAX_SCROLL,
duration: scrollEnd,
ease: "none",
onUpdate: function() {
var progress = this.progress();
var thumbTop = progress * THUMB_TRAVEL;
gsap.set("#scroll-thumb", { top: thumbTop });
}
}, 0);
// Phase 2 : Surbrillance mot par mot des sous-titres
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
tl.call(function() {
// Désactiver le mot précédent
if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
wordSpans[currentWordIndex].classList.remove("active");
wordSpans[currentWordIndex].classList.add("past");
}
// Activer le mot actuel
wordSpans[i].classList.add("active");
currentWordIndex = i;
}, null, w[1]);
});
// Phase 3 : La superposition CTA apparaît à 80%
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);
// Phase 4 : Atténuer la barre de sous-titres pendant le CTA
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);
// Phase 5 : La barre de progression du défilement disparaît
tl.to(".scroll-progress-track", { opacity: 0, duration: 0.3 }, ctaStart);
window.__timelines["{repo}-tour"] = tl;
</script>
</body>
</html>
Étape 5 : Rendu
cd github-promos/<repo>-tour
# Si aucune configuration de projet HyperFrames n'existe :
npx hyperframes init --example blank --non-interactive
# Lint
npx hyperframes lint
# Instantané pour vérification visuelle
npx hyperframes snapshot
# Rendu brouillon
npx hyperframes render --quality draft
# Vérifier le MP4 de sortie dans renders/
ls -la renders/
# Si tout est correct, rendu final
npx hyperframes render --quality standard
Étape 6 : Livrer
Envoyez le MP4 final à l'utilisateur. Demandez s'il souhaite :
- Un rendu haute qualité (
--quality high) - Un rapport d'aspect différent (paysage 1920x1080)
- Des révisions du script
Système de Sous-titres — Comment ça Marche
Le système de sous-titres est le différenciateur principal de cette compétence. Voici comment fonctionne la synchronisation mot par mot :
Horodatages au Niveau du Mot
L'audio de narration est transcrit avec des horodatages au niveau du mot (depuis ElevenLabs ou Whisper). Chaque mot reçoit une entrée [mot, secondeDebut, secondeFin] dans le tableau WORDS.
Trois États Visuels
Chaque mot dans la barre de sous-titres a trois états CSS :
| État | Classe | Visuel |
|---|---|---|
| À venir | .subtitle-word | Blanc atténué rgba(255,255,255,0.35) |
| Actif | .subtitle-word.active | Blanc vif #FFFFFF, légèrement agrandi 1.08 |
| Passé | .subtitle-word.past | Blanc moyen rgba(255,255,255,0.65) |
La timeline GSAP appelle une fonction à startSeconds de chaque mot pour faire passer motCourant → actif et motPrécédent → passé. Cela crée une surbrillance mot par mot de style Karaoké parfaitement synchronisée avec l'audio.
Typographie
- Police : Inter 700, 42px
- Position : Bas 180px, centré, largeur max 1000px
- Arrière-plan : Pas de boîte d'arrière-plan — les mots flottent au-dessus du contenu défilant avec le dégradé atténué/vif/atténué les rendant lisibles sur tout contenu
- Z-index : 100 (au-dessus du contenu défilant à z-index 1, en dessous de la superposition CTA à z-index 200)
Considérations de Disposition
Les mots sont disposés avec display: inline-block et un retour à la ligne naturel. Pour les scripts plus longs (20+ secondes), envisagez de diviser en 2–3 groupes de lignes qui apparaissent/disparaissent entre les segments de défilement :
// Grouper les mots par segment de défilement
var SEGMENTS = [
{ start: 0, end: 5, words: [0, 12] }, // Segment 1 : Hero
{ start: 5, end: 15, words: [13, 35] }, // Segment 2 : Défilement
{ start: 15, end: 20, words: [36, 50] }, // Segment 3 : Statistiques
{ start: 20, end: 25, words: [51, 62] } // Segment 4 : CTA
];
