Tour de Repo en GitHub — Video con Desplazamiento, Narración Sincronizada y Subtítulos
Depende de: website-to-hyperframes — cárgalo antes de empezar. Su flujo de trabajo de 6 pasos y archivos de referencia aplican aquí. Esta habilidad especializa ese flujo para tours de una sola página con desplazamiento, narración y subtítulos visibles.
Qué Produce Esta Habilidad
Un video vertical de 1080x1920 (formato Instagram Reels) que:
- Muestra una página de repositorio de GitHub — captura de pantalla móvil de página completa, desplazándose suavemente de arriba a abajo durante 15–30 segundos.
- Narra el tour — voz IA de ElevenLabs describiendo lo que se ve en pantalla, sincronizada con la posición de desplazamiento.
- Incorpora subtítulos en pantalla — superposición de subtítulos palabra por palabra que resalta cada palabra mientras el narrador la dice. El espectador lee mientras escucha.
- Termina con una CTA — "Star en GitHub" o "Sígueme para más" como llamada a la acción.
Decisiones Clave
| Decisión | Valor | Por qué |
|---|---|---|
| Dimensiones | 1080x1920 | Formato principal de Instagram Reels |
| Duración | 15–30 segundos | Punto óptimo para engagement en Shorts/Reels |
| Narración | Marca el ritmo | La velocidad de desplazamiento, duración de los beats y la sincronización de subtítulos se derivan del audio |
| Subtítulos | Resaltado palabra por palabra | Cada palabra se ilumina cuando el narrador la dice — Subtítulos estilo karaoke |
| Viewport de teléfono | Desplazamiento a pantalla completa, sin bisel | La página de GitHub llena todo el lienzo de 1080x1920 |
| Carpeta de salida | github-promos/<repo>-tour/ | Hermana de proyectos github-repo-promo |
Estructura de Directorios
github-promos/
<repo>-tour/
index.html ← composición principal de HyperFrames
package.json ← de `hyperframes init`
hyperframes.config.json ← configuración de HyperFrames
SCRIPT.md ← guión de narración con marcas de tiempo
assets/
repo-page.png ← Captura de pantalla completa de GitHub (modo oscuro, viewport móvil)
narration.mp3 ← Locución de ElevenLabs
renders/ ← MP4 generados
Flujo de Trabajo
Paso 0: Capturar Información del Repo y Captura de Pantalla
Usa web-search o fetch_url para obtener metadatos del repositorio:
- Estrellas, forks, watchers, issues abiertos
- Lenguaje principal, descripción, temas
- Resumen del README (qué hace el proyecto, características clave)
Luego usa la habilidad screenshot para capturar una captura de pantalla de página completa, en modo oscuro y viewport móvil:
use_skill("screenshot")
// URL: https://github.com/{owner}/{repo}
// Página completa, modo oscuro
// Viewport: 390px de ancho (iPhone 14 móvil) — la captura debe
// abarcar toda la altura de la página en ancho móvil
// Guardar como: github-promos/<repo>-tour/assets/repo-page.png
Obtén las dimensiones de la captura (necesitas la altura en píxeles para los cálculos de desplazamiento):
sips -g pixelHeight github-promos/<repo>-tour/assets/repo-page.png
sips -g pixelWidth github-promos/<repo>-tour/assets/repo-page.png
Paso 1: Escribir el Guión de Narración
Escribe un guión de 15–30 segundos que describa lo que el espectador ve a medida que avanza el desplazamiento. El narrador guía al espectador a través de la página:
[0s–4s] "Este es {repo}. {descripción en una línea}."
[4s–8s] "Aquí está el README — la instalación es un solo comando."
[8s–13s] "Desplazándonos por la lista de funciones — {menciona 2-3 funciones visibles}."
[13s–18s] "{stars} estrellas, {forks} forks, y una comunidad en crecimiento."
[18s–23s] "Dale estrella en GitHub. Enlace en la biografía."
[23s–25s] "Sígueme para más."
Reglas para el guión:
- El narrador hace referencia a lo que está actualmente en pantalla en cada posición de desplazamiento.
- Recuento total de palabras: 50–75 palabras (ritmo cómodo para 15–30 segundos).
- Sin relleno ("um", "eh", "déjame mostrarte"). Cada palabra gana su lugar.
- Termina con una CTA clara.
Paso 2: Generar Locución a través de 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": "GUIÓN_COMPLETO_AQUÍ",
"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
Verifica que el archivo exista y tenga tamaño > 0.
Paso 3: Transcribir y Mapear Tiempos
Después de generar el audio, extrae las marcas de tiempo a nivel de palabra:
Opción A: Marcas de tiempo de ElevenLabs (devueltas con la respuesta de la API si output_format: "mp3" no es la única salida — consulta la documentación de la API para salida aligned).
Opción B: Usa ffmpeg + Whisper (transcripción local con marcas de tiempo por palabra):
# Instala whisper si es necesario
pip install openai-whisper
# Transcribe con marcas de tiempo por palabra
whisper github-promos/<repo>-tour/assets/narration.mp3 \
--model base \
--output_format json \
--output_dir github-promos/<repo>-tour/assets/ \
--word_timestamps True
La salida te da words[] con marcas de tiempo start y end para cada palabra. Asigna estas marcas de tiempo a las posiciones de desplazamiento.
Paso 4: Construir la Composición HyperFrames
Crea index.html siguiendo la arquitectura de composición HyperFrames:
<!DOCTYPE html>
<html lang="es">
<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>
/* ── Raíz y Lienzo ── */
* { 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 Pantalla con Desplazamiento ── */
.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 de la captura */
}
/* ── Superposición de Subtítulos ── */
.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 Progreso de Desplazamiento ── */
.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;
}
/* ── Superposición de CTA (Beat 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 pantalla con desplazamiento (lienzo completo) -->
<div class="scroll-container">
<img class="scroll-content" src="assets/repo-page.png" />
</div>
<!-- Barra de progreso de desplazamiento -->
<div class="scroll-progress-track">
<div class="scroll-progress-thumb" id="scroll-thumb"></div>
</div>
<!-- Superposición de subtítulos -->
<div class="subtitle-bar" id="subtitle-bar">
<!-- Palabras inyectadas por JS, un <span class="subtitle-word"> por palabra -->
</div>
<!-- Superposición de CTA (últimos 5s) -->
<div class="cta-overlay" id="cta-overlay">
<div class="cta-title">Dale estrella en GitHub</div>
<div class="cta-subtitle">{descripción del repo}</div>
<div class="cta-button">github.com/{owner}/{repo}</div>
<div class="follow-pill">@githubprojects</div>
</div>
</div>
<script>
// ── Cálculos de Desplazamiento ──────────────────────────
var IMG_H = /* altura real de la captura */;
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;
}
// ── Marcas de Tiempo de Palabras ────────────────────────
// Pega las marcas de tiempo a nivel de palabra del Paso 3 aquí.
// Formato: [palabra, segundosInicio, segundosFin]
var WORDS = [
// ["Este", 0.0, 0.3],
// ["es", 0.3, 0.5],
// ["mercury-skills", 0.5, 1.0],
// ...
];
var TOTAL_DURATION = /* segundos totales del audio */;
// ── Construir Spans de Subtítulos ───────────────────────
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);
});
// ── Línea de Tiempo GSAP ────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});
// Fase 1: Desplazamiento (0s a ~80% de la duración total)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;
// Desplazamiento de arriba a abajo con easing
$.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: Resaltado de subtítulos palabra por palabra
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
tl.call(function() {
// Desactivar palabra anterior
if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
wordSpans[currentWordIndex].classList.remove("active");
wordSpans[currentWordIndex].classList.add("past");
}
// Activar palabra actual
wordSpans[i].classList.add("active");
currentWordIndex = i;
}, null, w[1]);
});
// Fase 3: La superposición de CTA aparece al 80%
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);
// Fase 4: Atenuar la barra de subtítulos durante la CTA
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);
// Fase 5: La barra de progreso de desplazamiento se desvanece
tl.to(".scroll-progress-track", { opacity: 0, duration: 0.3 }, ctaStart);
window.__timelines["{repo}-tour"] = tl;
</script>
</body>
</html>
Paso 5: Renderizar
cd github-promos/<repo>-tour
# Si no existe configuración del proyecto HyperFrames:
npx hyperframes init --example blank --non-interactive
# Lint
npx hyperframes lint
# Instantánea para verificar visualmente
npx hyperframes snapshot
# Renderizado borrador
npx hyperframes render --quality draft
# Verifica el MP4 de salida en renders/
ls -la renders/
# Si todo se ve bien, renderiza el final
npx hyperframes render --quality standard
Paso 6: Entregar
Envía el MP4 final al usuario. Pregunta si desea:
- Renderizado de alta calidad (
--quality high) - Relación de aspecto diferente (horizontal 1920x1080)
- Revisiones del guión
Sistema de Subtítulos — Cómo Funciona
El sistema de subtítulos es el diferenciador principal de esta habilidad. Así funciona la sincronización palabra por palabra:
Marcas de Tiempo a Nivel de Palabra
El audio de la narración se transcribe con marcas de tiempo a nivel de palabra (de ElevenLabs o Whisper). Cada palabra obtiene una entrada [palabra, segundosInicio, segundosFin] en el array WORDS.
Tres Estados Visuales
Cada palabra en la barra de subtítulos tiene tres estados CSS:
| Estado | Clase | Visual |
|---|---|---|
| Próximo | .subtitle-word | Blanco tenue rgba(255,255,255,0.35) |
| Activo | .subtitle-word.active | Blanco brillante #FFFFFF, ligeramente escalado 1.08 |
| Pasado | .subtitle-word.past | Blanco medio rgba(255,255,255,0.65) |
La línea de tiempo de GSAP llama a una función en el segundosInicio de cada palabra para transicionar palabraActual → activo y palabraAnterior → pasado. Esto crea un resaltado palabra por palabra estilo karaoke perfectamente sincronizado con el audio.
Tipografía
- Fuente: Inter 700, 42px
- Posición: Parte inferior 180px, centrada, 1000px de ancho máximo
- Fondo: Sin caja de fondo — las palabras flotan sobre el contenido de desplazamiento con el degradado tenue/brillante/tenue que las hace legibles sobre cualquier contenido
- Z-index: 100 (por encima del contenido de desplazamiento en z-index 1, por debajo de la superposición de CTA en z-index 200)
Consideraciones de Diseño
Las palabras se distribuyen con display: inline-block y ajuste de texto natural. Para guiones más largos (más de 20 segundos), considera dividir en 2–3 grupos de líneas que aparecen/desaparecen entre segmentos de desplazamiento:
// Agrupar palabras por segmento de desplazamiento
var SEGMENTS = [
{ start: 0, end: 5, words: [0, 12] }, // Beat 1: Hero
{ start: 5, end: 15, words: [13, 35] }, // Beat 2: Desplazamiento
{ start: 15, end: 20, words: [36, 50] }, // Beat 3: Estadísticas
{ ...
