GitHub 저장소 투어 — 동기화된 내레이션 및 자막이 있는 스크롤 비디오
의존성: website-to-hyperframes — 시작하기 전에 로드하세요. 6단계 워크플로우와 참조 파일이 여기에 적용됩니다. 이 스킬은 단일 페이지 스크롤 투어를 내레이션 및 가시적 자막과 함께 특화합니다.
이 스킬이 생성하는 것
1080x1920 세로 비디오(인스타그램 릴스 형식)로 다음을 수행합니다:
- GitHub 저장소 페이지 표시 — 전체 페이지 모바일 스크린샷, 15~30초에 걸쳐 상단에서 하단으로 부드럽게 스크롤.
- 투어 내레이션 — ElevenLabs AI 음성이 화면에 표시된 내용을 설명하고, 스크롤 위치와 동기화.
- 화면에 자막 표시 — 단어별 캡션 오버레이로, 내레이터가 말할 때 각 단어가 강조 표시됨. 시청자는 들으면서 함께 읽음.
- CTA로 종료 — "GitHub에서 별표" 또는 "더 보려면 팔로우"와 같은 행동 유도.
핵심 결정 사항
| 결정 | 값 | 이유 |
|---|---|---|
| 해상도 | 1080x1920 | 인스타그램 릴스 기본 형식 |
| 길이 | 15~30초 | 쇼츠/릴스 참여에 최적 |
| 내레이션 | 타이밍 결정 | 스크롤 속도, 비트 길이, 자막 타이밍이 모두 오디오에서 파생됨 |
| 자막 | 단어별 강조 | 내레이터가 말할 때 각 단어가 강조 표시됨 — 가라오케 스타일 자막 |
| 폰 뷰포트 | 전체 화면 스크롤, 베젤 없음 | GitHub 페이지가 전체 1080x1920 캔버스를 채움 |
| 출력 폴더 | github-promos/<repo>-tour/ | github-repo-promo 프로젝트와 같은 위치에 생성 |
디렉토리 구조
github-promos/
<repo>-tour/
index.html ← 메인 HyperFrames 컴포지션
package.json ← hyperframes init에서 생성
hyperframes.config.json ← HyperFrames 설정
SCRIPT.md ← 타임스탬프가 포함된 내레이션 스크립트
assets/
repo-page.png ← 전체 페이지 GitHub 스크린샷 (다크 모드, 모바일 뷰포트)
narration.mp3 ← ElevenLabs 음성 해설
renders/ ← 생성된 MP4 파일
워크플로우
0단계: 저장소 정보 및 스크린샷 캡처
web-search 또는 fetch_url을 사용하여 저장소 메타데이터를 가져옵니다:
- 별표, 포크, 시청자, 오픈 이슈
- 주요 언어, 설명, 주제
- README 요약 (프로젝트의 기능, 주요 특징)
그런 다음 screenshot 스킬을 사용하여 전체 페이지, 다크 모드, 모바일 뷰포트 스크린샷을 캡처합니다:
use_skill("screenshot")
// URL: https://github.com/{owner}/{repo}
// 전체 페이지, 다크 모드
// 뷰포트: 너비 390px (iPhone 14 모바일) — 스크린샷은
// 모바일 너비에서 페이지의 전체 높이를 캡처해야 함
// 저장 위치: github-promos/<repo>-tour/assets/repo-page.png
스크린샷 크기를 가져옵니다(스크롤 계산을 위해 픽셀 높이가 필요함):
sips -g pixelHeight github-promos/<repo>-tour/assets/repo-page.png
sips -g pixelWidth github-promos/<repo>-tour/assets/repo-page.png
1단계: 내레이션 스크립트 작성
15~30초 분량의 스크립트를 작성합니다. 스크립트는 스크롤이 진행됨에 따라 시청자가 보는 내용을 설명해야 합니다. 내레이터가 페이지를 안내합니다:
[0초~4초] "이것은 {repo}입니다. {한 줄 설명}."
[4초~8초] "여기가 README입니다 — 설치는 한 줄 명령어입니다."
[8초~13초] "기능 목록을 스크롤 중입니다 — {눈에 보이는 2~3가지 기능 언급}."
[13초~18초] "별표 {stars}개, 포크 {forks}개, 성장하는 커뮤니티입니다."
[18초~23초] "GitHub에서 별표를 눌러주세요. 링크는 프로필에 있습니다."
[23초~25초] "더 보려면 팔로우하세요."
스크립트 규칙:
- 내레이터는 각 스크롤 위치에서 현재 화면에 보이는 내용을 언급합니다.
- 총 단어 수: 50
75단어 (1530초에 적절한 속도). - 군더더기 없음("음", "어", "보여드리겠습니다"). 모든 단어는 의미가 있어야 합니다.
- 명확한 CTA로 끝납니다.
2단계: 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": "전체_스크립트_여기에",
"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
파일이 존재하고 크기가 0보다 큰지 확인합니다.
3단계: 전사 및 시간 매핑
오디오 생성 후, 단어 수준 타임스탬프를 추출합니다:
옵션 A: ElevenLabs 타임스탬프 (output_format: "mp3"만이 유일한 출력이 아닌 경우 API 응답과 함께 반환됨 — aligned 출력에 대한 API 문서 확인).
옵션 B: ffmpeg + Whisper 사용 (단어 타임스탬프가 포함된 로컬 전사):
# 필요한 경우 whisper 설치
pip install openai-whisper
# 단어 타임스탬프와 함께 전사
whisper github-promos/<repo>-tour/assets/narration.mp3 \
--model base \
--output_format json \
--output_dir github-promos/<repo>-tour/assets/ \
--word_timestamps True
출력은 각 단어에 start 및 end 타임스탬프가 있는 words[]를 제공합니다. 이러한 타임스탬프를 스크롤 위치에 매핑합니다.
4단계: HyperFrames 컴포지션 빌드
HyperFrames 컴포지션 아키텍처에 따라 index.html을 생성합니다:
<!DOCTYPE html>
<html lang="ko">
<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>
/* ── Root & 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;
}
/* ── Scrolling Screenshot ── */
.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; /* actual screenshot height */
}
/* ── Subtitle Overlay ── */
.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);
}
/* ── Scroll Progress Bar ── */
.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;
}
/* ── CTA Overlay (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>
<!-- Scrolling screenshot (full-canvas) -->
<div class="scroll-container">
<img class="scroll-content" src="assets/repo-page.png" />
</div>
<!-- Scroll progress bar -->
<div class="scroll-progress-track">
<div class="scroll-progress-thumb" id="scroll-thumb"></div>
</div>
<!-- Subtitle overlay -->
<div class="subtitle-bar" id="subtitle-bar">
<!-- Words injected by JS, one <span class="subtitle-word"> per word -->
</div>
<!-- CTA overlay (final 5s) -->
<div class="cta-overlay" id="cta-overlay">
<div class="cta-title">Star on GitHub</div>
<div class="cta-subtitle">{repo description}</div>
<div class="cta-button">github.com/{owner}/{repo}</div>
<div class="follow-pill">@githubprojects</div>
</div>
</div>
<script>
// ── Scroll Math ──────────────────────────────────────────
var IMG_H = /* actual screenshot height */;
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;
}
// ── Word Timestamps ─────────────────────────────────────
// Paste the word-level timestamps from Step 3 here.
// Format: [word, startSeconds, endSeconds]
var WORDS = [
// ["This", 0.0, 0.3],
// ["is", 0.3, 0.5],
// ["mercury-skills", 0.5, 1.0],
// ...
];
var TOTAL_DURATION = /* total seconds from audio */;
// ── Build Subtitle Spans ────────────────────────────────
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);
});
// ── GSAP Timeline ───────────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});
// Phase 1: Scroll (0s to ~80% of total duration)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;
// Scroll from top to bottom with 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);
// Phase 2: Word-by-word subtitle highlighting
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
tl.call(function() {
// Deactivate previous word
if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
wordSpans[currentWordIndex].classList.remove("active");
wordSpans[currentWordIndex].classList.add("past");
}
// Activate current word
wordSpans[i].classList.add("active");
currentWordIndex = i;
}, null, w[1]);
});
// Phase 3: CTA overlay fades in at 80%
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);
// Phase 4: Dim subtitle bar during CTA
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);
// Phase 5: Scroll progress bar fades out
tl.to(".scroll-progress-track", { opacity: 0, duration: 0.3 }, ctaStart);
window.__timelines["{repo}-tour"] = tl;
</script>
</body>
</html>
5단계: 렌더링
cd github-promos/<repo>-tour
# HyperFrames 프로젝트 설정이 없는 경우:
npx hyperframes init --example blank --non-interactive
# 린트
npx hyperframes lint
# 시각적 확인을 위한 스냅샷
npx hyperframes snapshot
# 드래프트 렌더
npx hyperframes render --quality draft
# renders/에서 출력 MP4 확인
ls -la renders/
# 모든 것이 좋아 보이면 최종 렌더
npx hyperframes render --quality standard
6단계: 전달
최종 MP4를 사용자에게 보냅니다. 다음 사항을 문의하세요:
- 고품질 렌더 (
--quality high) - 다른 종횡비 (가로 1920x1080)
- 스크립트 수정
자막 시스템 — 작동 방식
자막 시스템은 이 스킬의 핵심 차별화 요소입니다. 단어별 동기화가 작동하는 방식은 다음과 같습니다:
단어 수준 타임스탬프
내레이션 오디오는 단어 수준 타임스탬프(ElevenLabs 또는 Whisper에서)로 전사됩니다. 각 단어는 WORDS 배열에 [word, startSeconds, endSeconds] 항목으로 추가됩니다.
세 가지 시각적 상태
자막 표시줄의 모든 단어에는 세 가지 CSS 상태가 있습니다:
| 상태 | 클래스 | 시각적 표현 |
|---|---|---|
| 다가오는 | .subtitle-word | 희미한 흰색 rgba(255,255,255,0.35) |
| 활성 | .subtitle-word.active | 밝은 흰색 #FFFFFF, 약간 확대 1.08 |
| 지난 | .subtitle-word.past | 중간 흰색 rgba(255,255,255,0.65) |
GSAP 타임라인은 각 단어의 startSeconds에서 함수를 호출하여 currentWord → active 및 previousWord → past로 전환합니다. 이렇게 하면 오디오에 완벽하게 동기화되는 가라오케 스타일의 단어별 하이라이트가 생성됩니다.
타이포그래피
- 폰트: Inter 700, 42px
- 위치: 하단 180px, 중앙 정렬, 최대 너비 1000px
- 배경: 배경 상자 없음 — 단어가 스크롤 콘텐츠 위에 떠 있으며, 어두움/밝음/어두움 그라데이션으로 어떤 콘텐츠 위에서도 읽을 수 있음
- Z-index: 100 (z-index 1의 스크롤 콘텐츠 위, z-index 200의 CTA 오버레이 아래)
레이아웃 고려 사항
단어는 display: inline-block 및 자연스러운 텍스트 줄 바꿈으로 배치됩니다. 더 긴 스크립트(20초 이상)의 경우 스크롤 세그먼트 사이에 나타나거나 사라지는 2~3줄 그룹으로 분할하는 것을 고려하세요:
// 스크롤 세그먼트별 단어 그룹화
var SEGMENTS = [
{ start: 0, end: 5, words: [0, 12] }, // 비트 1: 히어로
{ start: 5, end: 15, words: [13, 35] }, // 비트 2: 스크롤
{ start: 15, end: 20, words: [36, 50] }, // 비트 3: 통계
{ start: 20, end: 25, words: [51, 65] } // 비트 4: CTA
];
전체 자막 예시 (mercury-skills 저장소, 20초, 62단어)
var WORDS = [
["이것은", 0.0, 0.4],
["mercury", 0.4, 0.7],
["스킬", 0.7, 1.0],
["저장소", 1.0, 1.3],
["입니다", 1.3, 1.6],
["AI", 1.6, 1.9],
["에이전트", 1.9, 2.2],
["도구", 2.2, 2.5],
["모음집", 2.5, 2.8],
["기능을", 2.8, 3.2],
["확장합니다", 3.2, 3.6],
["설치는", 3.6, 4.0],
["한", 4.0, 4.3],
["줄", 4.3, 4.6],
["명령어로", 4.6, 5.0],
["끝납니다", 5.0, 5.4],
["스크롤을", 5.4, 5.8],
["내리면", 5.8, 6.2],
["스크린샷", 6.2, 6.6],
["생성", 6.6, 7.0],
["비디오", 7.0, 7.4],
["투어", 7.4, 7.8],
["빠른", 7.8, 8.2],
["워크플로우가", 8.2, 8.8],
["보입니다", 8.8, 9.2],
["2800", 9.2, 9.6],
["개의", 9.6, 10.0],
["별표", 10.0, 10.4],
["500", 10.4, 10.8],
["개의", 10.8, 11.2],
["포크", 11.2, 11.6],
["활발한", 11.6, 12.0],
["커뮤니티", 12.0, 12.4],
["오픈", 12.4, 12.8],
["소스", 12.8, 13.2],
["도구", 13.2, 13.6],
["지금", 13.6, 14.0],
["시작하세요", 14.0, 14.5],
["GitHub에서", 14.5, 15.5],
["별표를", 15.5, 16.5],
["눌러주세요", 16.5, 17.5],
["링크는", 17.5, 18.5],
["프로필에", 18.5, 19.5],
["있습니다", 19.5, 20.5],
];
