GitHub リポジトリツアー — ナレーションと字幕付きスクロール動画 は何をしますか?
依存: website-to-hyperframes — 開始する前に読み込んでください。その6ステップのワークフローとリファレンスファイルがここでも適用されます。このスキルは、ナレーションと表示字幕を備えた単一ページのスクロールツアー向けにそのワークフローを特化したものです。
このスキルが生成するもの
1080x1920 の縦型動画(Instagram Reels 形式)は、以下の内容を提供します:
- GitHub リポジトリページを表示 — 全画面モバイルスクリーンショットが、15〜30秒かけて上から下へスムーズにスクロールします。
- ツアーをナレーション — ElevenLabs AI の声が画面上の内容を説明し、スクロール位置に同期します。
- 字幕を画面に焼き付け — ナレーターが話す各単語がハイライトされる、単語単位のキャプションオーバーレイです。視聴者は聞きながら読み進められます。
- CTA で終了 — 「GitHub でスター」や「フォローしてね」などのコールトゥアクションで締めくくります。
主要な決定事項
| 決定事項 | 値 | 理由 |
|---|---|---|
| 寸法 | 1080x1920 | Instagram Reels の主要フォーマット |
| 長さ | 15~30秒 | Shorts/Reels のエンゲージメントに最適な時間 |
| ナレーション | タイミングの基準 | スクロール速度、ビートの長さ、字幕タイミングはすべて音声から派生 |
| 字幕 | 単語単位のハイライト | ナレーターが話す各単語が光る — カラオケスタイルのキャプション |
| スマホビューポート | 全画面スクロール、ベゼルなし | 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 です — インストールは1コマンドです。"
[8秒~13秒] "機能リストをスクロールしています — {2〜3の目に見える機能を挙げる}。"
[13秒~18秒] "{スター数} スター、{フォーク数} フォーク、そして成長するコミュニティ。"
[18秒~23秒] "GitHub でスターをお願いします。リンクはプロフィールにあります。"
[23秒~25秒] "フォローしてね。"
スクリプトのルール:
- ナレーターは、各スクロール位置で現在画面に表示されているものに言及します。
- 総単語数: 50〜75語(15〜30秒で心地よいペース)。
- フィラー(「えーと」、「あのー」、「ご紹介します」など)は不使用。すべての言葉に意味を持たせます。
- 明確な 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": "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
ファイルが存在し、サイズが 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="en">
<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>
/* ── ルートとキャンバス ── */
* { margin: 0; padding: 0; box-sizing: border-box; }
#root {
position: relative;
width: 1080px;
height: 1920px;
background: #0d1117;
font-family: 'Inter', sans-serif;
overflow: hidden;
}
/* ── スクロールスクリーンショット ── */
.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; /* 実際のスクリーンショットの高さ */
}
/* ── 字幕オーバーレイ ── */
.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-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 オーバーレイ(ビート 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>
<!-- スクロールするスクリーンショット(全キャンバス) -->
<div class="scroll-container">
<img class="scroll-content" src="assets/repo-page.png" />
</div>
<!-- スクロールプログレスバー -->
<div class="scroll-progress-track">
<div class="scroll-progress-thumb" id="scroll-thumb"></div>
</div>
<!-- 字幕オーバーレイ -->
<div class="subtitle-bar" id="subtitle-bar">
<!-- 単語ごとに JS で注入される <span class="subtitle-word"> -->
</div>
<!-- CTA オーバーレイ(最後の5秒間) -->
<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>
// ── スクロール計算 ──────────────────────────────────────────
var IMG_H = /* 実際のスクリーンショットの高さ */;
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;
}
// ── 単語タイムスタンプ ─────────────────────────────────────
// ステップ 3 の単語レベルのタイムスタンプをここに貼り付けます。
// 形式: [単語, 開始秒, 終了秒]
var WORDS = [
// ["This", 0.0, 0.3],
// ["is", 0.3, 0.5],
// ["mercury-skills", 0.5, 1.0],
// ...
];
var TOTAL_DURATION = /* 音声の合計秒数 */;
// ── 字幕スパンを構築 ────────────────────────────────
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 タイムライン ───────────────────────────────────────
window.__timelines = window.__timelines || {};
var tl = gsap.timeline({paused: true});
// フェーズ 1: スクロール(0秒〜全体の長さの約80%)
var scrollEnd = TOTAL_DURATION * 0.80;
var ctaStart = TOTAL_DURATION * 0.80;
// イージングを使用して上から下へスクロール
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);
// フェーズ 2: 単語単位の字幕ハイライト
var currentWordIndex = -1;
WORDS.forEach(function(w, i) {
tl.call(function() {
// 前の単語を非アクティブ化
if (currentWordIndex >= 0 && wordSpans[currentWordIndex]) {
wordSpans[currentWordIndex].classList.remove("active");
wordSpans[currentWordIndex].classList.add("past");
}
// 現在の単語をアクティブ化
wordSpans[i].classList.add("active");
currentWordIndex = i;
}, null, w[1]);
});
// フェーズ 3: CTA オーバーレイが 80% の時点でフェードイン
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);
// フェーズ 4: CTA 中に字幕バーを暗くする
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);
// フェーズ 5: スクロールプログレスバーをフェードアウト
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 配列に [単語, 開始秒, 終了秒] エントリとして格納されます。
3つの視覚状態
字幕バーのすべての単語には、3つの 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: 統計
{
…
[翻訳のため省略]
注意点とベストプラクティス
- スクリーンショットは必ずダークモードでキャプチャすること — ライトモードは白い背景に白いテキストを重ねる形になり、字幕が読みづらくなります。
- 音声は必ず文字起こしすること — 単語レベルのタイムスタンプがないとシステムは機能しません。
- スクリプトの長さは16〜25語/秒に抑えること — それ以上だと字幕が早すぎて読めなくなります。
- スクリプトを書くときは、常にスクロール位置から逆算すること — 各セグメントは、その時点で表示されている内容に言及する必要があります。
- CTA はシンプルに保つこと — 「GitHub でスター」または「フォローしてね」。視聴者が取るべき行動は1つだけにします。
