Communitygithub.com

Tour de Repositório GitHub — Vídeo de Rolagem com Narração Sinc…

Gere um vídeo de rolagem de 15 a 30 segundos de qualquer página de repositório GitHub, com narração por IA ElevenLabs e sincronização palavra por palavra das legendas. Captura uma captura de tela de página inteira em viewport móvel, rola de cima para baixo com GSAP e grava legendas sincronizadas no MP4 final usando a CLI HyperFrames.

O que é Tour de Repositório GitHub — Vídeo de Rolagem com Narração Sinc…?

Esta skill (Agente de IA) é especializada em criar vídeos curtos e envolventes no formato Instagram Reels (1080x1920) que mostram um tour rolável por uma página de repositório GitHub. O fluxo de trabalho começa capturando metadados do repositório e uma captura de tela de página inteira em modo escuro com viewport móvel. Um script de narração é escrito descrevendo o conteúdo à medida que a rolagem avança, que é então convertido em áudio usando a API ElevenLabs. O áudio é transcrito com timestamps no nível da palavra (via ElevenLabs ou Whisper) para permitir legendas karaokê perfeitamente sincronizadas. Uma composição HTML/JavaScript usando GSAP (GreenSock Animation Platform) e HyperFrames é construída, animando a rolagem da captura de tela, destacando cada palavra da legenda conforme é falada e culminando em uma sobreposição de chamada para ação no final. A renderização final do MP4 é feita via CLI HyperFrames. A habilidade suporta plataformas como Anthropic Claude (Agente de IA), Cursor (Agente de IA), Codex (Agente de IA) e qualquer ferramenta de agente de IA que possa executar skills de arquivos SKILL.md. A saída é um vídeo de alta qualidade, perfeitamente cronometrado, ideal para promoção em redes sociais.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

Tour de Repositório GitHub — Vídeo de Rolagem com Narração Sinc… preview

Documentação

Tour de Repositório GitHub — Vídeo de Rolagem com Narração Sincronizada e Legendas

Depende de: website-to-hyperframes — carregue-o antes de começar. Seu fluxo de trabalho de 6 etapas e arquivos de referência se aplicam aqui. Esta skill especializa esse fluxo de trabalho para tours de rolagem de página única com narração e legendas visíveis.


O Que Esta Skill Produz

Um vídeo vertical 1080x1920 (formato Instagram Reels) que:

  1. Mostra uma página de repositório GitHub — captura de tela de página inteira em modo celular, rolando suavemente de cima para baixo por 15–30 segundos.
  2. Narra o tour — Voz AI ElevenLabs descrevendo o que está na tela, sincronizada com a posição da rolagem.
  3. Grava legendas na tela — sobreposição de legendas palavra por palavra que destaca cada palavra conforme o narrador a fala. O espectador lê junto enquanto ouve.
  4. Termina com um CTA — "Star no GitHub" ou "Siga para mais" chamada para ação.

Decisões Principais

DecisãoValorPorquê
Dimensões1080x1920Formato principal do Instagram Reels
Duração15–30 segundosPonto ideal para engajamento em Shorts/Reels
NarraçãoControla o tempoVelocidade de rolagem, duração das batidas e tempo das legendas derivam do áudio
LegendasDestaque palavra por palavraCada palavra acende conforme o narrador a diz — Legendas estilo Karaokê
Viewport do celularRolagem em tela cheia, sem molduraA página GitHub preenche toda a tela 1080x1920
Pasta de saídagithub-promos/<repo>-tour/Ao lado de projetos de promoção de repositório GitHub

Estrutura de Diretórios

github-promos/
  <repo>-tour/
    index.html              ← composição principal do HyperFrames
    package.json            ← de hyperframes init
    hyperframes.config.json ← Config do HyperFrames
    SCRIPT.md               ← Roteiro de narração com timestamps
    assets/
      repo-page.png         ← Captura de tela GitHub em página inteira (modo escuro, viewport móvel)
      narration.mp3         ← Narração ElevenLabs
    renders/                ← MP4s gerados

Fluxo de Trabalho

Etapa 0: Capturar Informações do Repositório e Captura de Tela

Use web-search ou fetch_url para obter metadados do repositório:

  • Estrelas, forks, watchers, issues abertas
  • Linguagem primária, descrição, tópicos
  • Resumo do README (o que o projeto faz, principais recursos)

Em seguida, use a skill screenshot para capturar uma captura de tela de página inteira, modo escuro, viewport móvel:

use_skill("screenshot")
// URL: https://github.com/{owner}/{repo}
// Full page, dark mode
// Viewport: 390px width (iPhone 14 mobile) — a captura de tela deve
//   capturar a altura total da página na largura móvel
// Save as: github-promos/<repo>-tour/assets/repo-page.png

Obtenha as dimensões da captura de tela (você precisa da altura em pixels para o cálculo da rolagem):

sips -g pixelHeight github-promos/<repo>-tour/assets/repo-page.png
sips -g pixelWidth github-promos/<repo>-tour/assets/repo-page.png

Etapa 1: Escrever o Roteiro de Narração

Escreva um roteiro de 15–30 segundos que descreva o que o espectador vê conforme a rolagem avança. O narrador guia o espectador pela página:

[0s–4s]  "Este é {repositório}. {descrição em uma linha}."
[4s–8s]  "Aqui está o README — a instalação é um único comando."
[8s–13s] "Rolando pela lista de recursos — {mencione 2-3 recursos visíveis}."
[13s–18s] "{estrelas} estrelas, {forks} forks e uma comunidade crescente."
[18s–23s] "Dê uma estrela no GitHub. Link na bio."
[23s–25s] "Siga para mais."

Regras para o roteiro:

  • O narrador faz referência ao que está atualmente na tela em cada posição de rolagem.
  • Contagem total de palavras: 50–75 palavras (ritmo confortável para 15–30 segundos).
  • Sem enchimento ("hum", "é", "deixe-me mostrar"). Cada palavra merece seu lugar.
  • Termine com um CTA claro.

Etapa 2: Gerar Narração 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": "FULL_SCRIPT_HERE",
    "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

Verifique se o arquivo existe e tem tamanho > 0.

Etapa 3: Transcrever e Mapear o Tempo

Após gerar o áudio, extraia os timestamps no nível da palavra:

Opção A: Timestamps ElevenLabs (retornados com a resposta da API se output_format: "mp3" não for a única saída — consulte a documentação da API para aligned output).

Opção B: Use ffmpeg + Whisper (transcrição local com timestamps de palavras):

# Instale o whisper se necessário
pip install openai-whisper

# Transcreva com timestamps de palavras
whisper github-promos/<repo>-tour/assets/narration.mp3 \
  --model base \
  --output_format json \
  --output_dir github-promos/<repo>-tour/assets/ \
  --word_timestamps True

A saída fornece words[] com timestamps start e end para cada palavra. Mapeie esses timestamps para as posições de rolagem.

Etapa 4: Construir a Composição HyperFrames

Crie index.html seguindo a arquitetura de composição HyperFrames:

<!DOCTYPE html>
<html lang="pt">
<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>
  /* ── Raiz e Canvas ── */
  * { margin: 0; padding: 0; box-sizing: border-box; }
  #root {
    position: relative;
    width: 1080px;
    height: 1920px;
    background: #0d1117;
    font-family: 'Inter', sans-serif;
    overflow: hidden;
  }

  /* ── Captura de Tela Rolável ── */
  .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;   /* altura real da captura de tela */
  }

  /* ── Sobreposição de Legendas ── */
  .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);
  }

  /* ── Barra de Progresso da Rolagem ── */
  .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;
  }

  /* ── Sobreposição de CTA (Batidas 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>

  <!-- Captura de tela rolável (tela cheia) -->
  <div class="scroll-container">
    <img class="scroll-content" src="assets/repo-page.png" />
  </div>

  <!-- Barra de progresso da rolagem -->
  <div class="scroll-progress-track">
    <div class="scroll-progress-thumb" id="scroll-thumb"></div>
  </div>

  <!-- Sobreposição de legendas -->
  <div class="subtitle-bar" id="subtitle-bar">
    <!-- Palavras injetadas por JS, um <span class="subtitle-word"> por palavra -->
  </div>

  <!-- Sobreposição de CTA (5s finais) -->
  <div class="cta-overlay" id="cta-overlay">
    <div class="cta-title">Dê uma Estrela no GitHub</div>
    <div class="cta-subtitle">{descrição do repositório}</div>
    <div class="cta-button">github.com/{owner}/{repo}</div>
    <div class="follow-pill">@githubprojects</div>
  </div>
</div>

<script>
// ── Cálculo da Rolagem ──────────────────────────────────────────
var IMG_H = /* altura real da captura de tela */;
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;
}

// ── Timestamps de Palavras ─────────────────────────────────────
// Cole os timestamps no nível da palavra da Etapa 3 aqui.
// Formato: [palavra, startSeconds, endSeconds]
var WORDS = [
  // ["Este", 0.0, 0.3],
  // ["é", 0.3, 0.5],
  // ["mercury-skills", 0.5, 1.0],
  // ...
];

var TOTAL_DURATION = /* segundos totais do áudio */;

// ── Construir Spans de Legendas ────────────────────────────────
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);
});

// ── Linha do Tempo GSAP ───────────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});

// Fase 1: Rolagem (0s a ~80% da duração total)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;

// Rolar do topo para o fundo com easing
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);

// Fase 2: Destaque palavra por palavra
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
  tl.call(function() {
    // Desativar palavra anterior
    if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
      wordSpans[currentWordIndex].classList.remove("active");
      wordSpans[currentWordIndex].classList.add("past");
    }
    // Ativar palavra atual
    wordSpans[i].classList.add("active");
    currentWordIndex = i;
  }, null, w[1]);
});

// Fase 3: Sobreposição de CTA aparece em 80%
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);

// Fase 4: Escurecer barra de legendas durante CTA
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);

// Fase 5: Barra de progresso da rolagem desaparece
tl.to(".scroll-progress-track", { opacity: 0, duration: 0.3 }, ctaStart);

window.__timelines["{repo}-tour"] = tl;
</script>
</body>
</html>

Etapa 5: Renderizar

cd github-promos/<repo>-tour

# Se não existir nenhuma configuração de projeto HyperFrames:
npx hyperframes init --example blank --non-interactive

# Verificar
npx hyperframes lint

# Captura de tela para verificação visual
npx hyperframes snapshot

# Renderização de rascunho
npx hyperframes render --quality draft

# Verificar o MP4 de saída em renders/
ls -la renders/

# Se tudo parecer bom, renderizar final
npx hyperframes render --quality standard

Etapa 6: Entregar

Envie o MP4 final para o usuário. Pergunte se ele deseja:

  • Renderização de alta qualidade (--quality high)
  • Proporção de aspecto diferente (paisagem 1920x1080)
  • Revisões do roteiro

Sistema de Legendas — Como Funciona

O sistema de legendas é o principal diferencial desta skill. Veja como a sincronização palavra por palavra funciona:

Timestamps no Nível da Palavra

O áudio da narração é transcrito com timestamps no nível da palavra (do ElevenLabs ou Whisper). Cada palavra recebe uma entrada [palavra, startSeconds, endSeconds] no array WORDS.

Três Estados Visuais

Cada palavra na barra de legendas tem três estados CSS:

EstadoClasseVisual
Futuro.subtitle-wordBranco fraco rgba(255,255,255,0.35)
Ativo.subtitle-word.activeBranco brilhante #FFFFFF, levemente escalado 1.08
Passado.subtitle-word.pastBranco médio rgba(255,255,255,0.65)

A linha do tempo GSAP chama uma função no startSeconds de cada palavra para fazer a transição de palavraAtual → ativo e palavraAnterior → passado. Isso cria um destaque palavra por palavra estilo Karaokê perfeitamente sincronizado com o áudio.

Tipografia

  • Fonte: Inter 700, 42px
  • Posição: Fundo 180px, centralizado, 1000px de largura máxima
  • Fundo: Sem caixa de fundo — as palavras flutuam sobre o conteúdo da rolagem com o gradiente fraco/brilhante/fraco tornando-as legíveis contra qualquer conteúdo
  • Z-index: 100 (acima do conteúdo de rolagem no z-index 1, abaixo da sobreposição de CTA no z-index 200)

Considerações de Layout

As palavras são dispostas com display: inline-block e quebra de texto natural. Para roteiros mais longos (20+ segundos), considere dividir em 2–3 grupos de linha que aparecem/desaparecem entre segmentos de rolagem:

// Agrupar palavras por segmento de rolagem
var SEGMENTS = [
  { start: 0, end: 5, words: [0, 12] },     // Batida 1: Herói
  { start: 5, end: 15, words: [13, 35] },   // Batida 2: Rolagem
  { start: 15, end: 20, words: [36, 50] },   // Batida 3: Estatísticas
  // ...
];

Individual skills in this repo

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

Habilidades Relacionadas