Communitygithub.com

cosmicstack-labs/mercury-agent-skills

Générez une vidéo de visite défilante de 15 à 30 secondes de n'importe quelle page de dépôt GitHub, avec narration IA ElevenLabs et sous-titres synchronisés mot par mot.

Qu'est-ce que mercury-agent-skills ?

Cette compétence permet de créer automatiquement une vidéo portrait 1080x1920 (format Instagram Reels) qui défile visuellement du haut en bas d'une page de dépôt GitHub, avec une narration générée par ElevenLabs et des sous-titres synchronisés mot par mot. Elle capture une capture d'écran plein écran en mode mobile (390px de large), anime le défilement avec GSAP, et grave les sous-titres sur la vidéo finale via HyperFrames CLI. Idéale pour les développeurs, créateurs de contenu technique ou mainteneurs open source qui veulent promouvoir un dépôt GitHub sur les réseaux sociaux avec un visuel dynamique et accessible. La compétence inclut la génération de script narratif, la transcription audio avec Whisper, la construction d'une composition HyperFrames, et le rendu final MP4. Le résultat est une vidéo engageante qui met en valeur le README, les fonctionnalités, les statistiques et inclut un appel à l'action final.

Compatible avec✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/cosmicstack-labs/mercury-agent-skills/tree/HEAD/categories/media-download/github-repo-tour

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Aperçu

Depuis le README du skill

mercury-agent-skills preview

Documentation

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 :

  1. 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.
  2. Narre la visite — voix IA ElevenLabs décrivant ce qui est à l'écran, synchronisée avec la position de défilement.
  3. 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.
  4. Se termine par un CTA — appel à l'action « Star on GitHub » ou « Follow for more ».

Décisions Clés

DécisionValeurPourquoi
Dimensions1080x1920Format principal Instagram Reels
Durée15–30 secondesZone idéale pour l'engagement Shorts/Reels
NarrationDicte le rythmeLa vitesse de défilement, les durées des segments et le timing des sous-titres dérivent tous de l'audio
Sous-titresSurbrillance mot par motChaque mot s'illumine lorsque le narrateur le dit — style Karaoké
Vue téléphonePlein écran défilant, sans bordureLa page GitHub remplit tout le canevas 1080x1920
Dossier de sortiegithub-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 :

ÉtatClasseVisuel
À venir.subtitle-wordBlanc atténué rgba(255,255,255,0.35)
Actif.subtitle-word.activeBlanc vif #FFFFFF, légèrement agrandi 1.08
Passé.subtitle-word.pastBlanc 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
];

Références

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés