Communitygithub.com

GitHub リポジトリツアー — ナレーションと字幕付きスクロール動画

任意の GitHub リポジトリページを、ElevenLabs AI ナレーションと単語単位の字幕同期で、15〜30秒のスクロール動画ツアーとして生成します。モバイルビューポートの全ページスクリーンショットを撮影し、GSAP で上下にスクロール、同期した字幕を HyperFrames CLI で最終 MP4 に焼き付けます。

GitHub リポジトリツアー — ナレーションと字幕付きスクロール動画 とは?

このスキルは、GitHub リポジトリのランディングページを、ソーシャルメディア向けの魅力的な縦型動画(1080x1920、Instagram Reels 形式)に変換する強力なツールです。AI によるナレーション、ページコンテンツと連動した自動スクロール、そしてカラオケスタイルの単語単位ハイライト字幕を組み合わせて、没入感のあるツアー体験を提供します。ユーザーはリポジトリ情報の取得、モバイルビューポートでの全ページスクリーンショットのキャプチャ、ElevenLabs を使用したナレーションの生成、Whisper または ElevenLabs のタイムスタンプを使った単語レベルのタイムマッピング、そして HyperFrames フレームワーク内で GSAP アニメーションを活用した最終 MP4 のレンダリングまで、自動化された6ステップのワークフローを利用できます。最終的な動画にはプログレスバー、明確なコールトゥアクション(「GitHub でスター」)、そして各単語が発音されるたびにハイライトされる高精度な字幕オーバーレイが含まれます。このワークフローは基盤となる `website-to-hyperframes` スキルを特化したものであり、開発者やコンテンツクリエイターが、オープンソースプロジェクトのプロモーション動画をわずか数分で効率的に作成できるようにします。

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

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

プレビュー

スキル README より

GitHub リポジトリツアー — ナレーションと字幕付きスクロール動画 preview

ドキュメント

GitHub リポジトリツアー — ナレーションと字幕付きスクロール動画 は何をしますか?

依存: website-to-hyperframes — 開始する前に読み込んでください。その6ステップのワークフローとリファレンスファイルがここでも適用されます。このスキルは、ナレーションと表示字幕を備えた単一ページのスクロールツアー向けにそのワークフローを特化したものです。


このスキルが生成するもの

1080x1920 の縦型動画(Instagram Reels 形式)は、以下の内容を提供します:

  1. GitHub リポジトリページを表示 — 全画面モバイルスクリーンショットが、15〜30秒かけて上から下へスムーズにスクロールします。
  2. ツアーをナレーション — ElevenLabs AI の声が画面上の内容を説明し、スクロール位置に同期します。
  3. 字幕を画面に焼き付け — ナレーターが話す各単語がハイライトされる、単語単位のキャプションオーバーレイです。視聴者は聞きながら読み進められます。
  4. CTA で終了 — 「GitHub でスター」や「フォローしてね」などのコールトゥアクションで締めくくります。

主要な決定事項

決定事項値理由
寸法1080x1920Instagram 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: 統計
  { 

…

[翻訳のため省略]

注意点とベストプラクティス

  1. スクリーンショットは必ずダークモードでキャプチャすること — ライトモードは白い背景に白いテキストを重ねる形になり、字幕が読みづらくなります。
  2. 音声は必ず文字起こしすること — 単語レベルのタイムスタンプがないとシステムは機能しません。
  3. スクリプトの長さは16〜25語/秒に抑えること — それ以上だと字幕が早すぎて読めなくなります。
  4. スクリプトを書くときは、常にスクロール位置から逆算すること — 各セグメントは、その時点で表示されている内容に言及する必要があります。
  5. CTA はシンプルに保つこと — 「GitHub でスター」または「フォローしてね」。視聴者が取るべき行動は1つだけにします。

Individual skills in this repo

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

関連スキル