Communitygithub.com

GitHub 仓库导览 — 带同步配音与字幕的滚动视频

为任意 GitHub 仓库页面生成一段 15-30 秒的滚动视频导览,搭配 ElevenLabs AI 配音和逐字同步字幕。截取全页移动端视口截图,使用 GSAP 从上到下滚动,并通过 HyperFrames CLI 将同步字幕烧录到最终 MP4 文件中。

GitHub 仓库导览 — 带同步配音与字幕的滚动视频 是什么?

该技能基于现有的 website-to-hyperframes 工作流进行了专业化定制,专注于为 GitHub 仓库页面生成 Instagram Reels 格式的竖屏宣传视频。它通过全页移动端截图(宽 390px)、GSAP 驱动的滚动动画、ElevenLabs 的 AI 配音以及逐字高亮字幕(卡拉 OK 风格)来构建完整的视频叙事。工作流包含六个步骤:捕获仓库元数据和截图、编写配音脚本、生成配音音频、获取逐字时间戳、创建 HyperFrames 合成(带有滚动容器、进度条、字幕叠加和最后的 CTA 覆盖层),最后使用 hyperframes render 命令渲染输出。该技能依赖于 website-to-hyperframes 技能进行初始项目配置,并支持在 HyperFrames CLI 平台上运行,输出 1080x1920 分辨率的 MP4 文件,适配 Instagram Reels。通过将字幕时间戳与音频和滚动位置精确同步,实现了沉浸式的浏览体验。

兼容平台✓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 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

GitHub 仓库导览 — 带同步配音与字幕的滚动视频 preview

文档

GitHub 仓库导览 — 带同步配音与字幕的滚动视频 是做什么的?

依赖: website-to-hyperframes — 请先加载该技能。其 6 步工作流和参考文件在此处同样适用。本技能将该工作流专门用于单页滚动导览,并带有配音和可见字幕。


本技能产出什么

一个 1080x1920 竖屏视频(Instagram Reels 格式),其效果如下:

  1. 展示一个 GitHub 仓库页面 — 全页移动端截图,在 15–30 秒内从上到下平滑滚动。
  2. 为导览配音 — ElevenLabs AI 语音描述屏幕上的内容,并与滚动位置同步。
  3. 在屏幕上烧录字幕 — 逐字叠加字幕,随着配音朗读高亮每个单词。观众可以一边听一边跟读。
  4. 以 CTA 结束 — “在 GitHub 上 Star”或“关注以获取更多”的号召性用语。

核心决策

决策项值原因
尺寸1080x1920Instagram Reels 的主要格式
时长15–30 秒Shorts/Reels 参与度的最佳区间
配音驱动时间线滚动速度、节奏持续时间和字幕时间均源自音频
字幕逐字高亮配音说出每个单词时,该单词会高亮显示 — 卡拉 OK 风格字幕
手机视口全屏滚动,无边框GitHub 页面填满整个 1080x1920 画布
输出文件夹github-promos/<仓库名>-tour/与 github-repo-promo 项目同级

目录结构

github-promos/
  <仓库名>-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 获取仓库元数据:

  • Star、Fork、Watcher、开放 Issue 数量
  • 主要编程语言、描述、话题标签
  • README 摘要(项目功能、关键特性)

然后使用 screenshot 技能捕获一张 全页、深色模式、移动端视口 的截图:

use_skill("screenshot")
// URL: https://github.com/{所有者}/{仓库名}
// 全页,深色模式
// 视口:390px 宽(iPhone 14 移动端)— 截图应
//   以移动宽度捕获页面的完整高度
// 保存至:github-promos/<仓库名>-tour/assets/repo-page.png

获取截图尺寸(你需要像素高度用于滚动计算):

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

第 1 步:编写配音脚本

编写一个 15–30 秒的脚本,描述观众随着滚动进行所看到的内容。配音员引导观众浏览页面:

[0秒–4秒]  “这是 {仓库名}。{一句话描述}。”
[4秒–8秒]  “这是 README — 安装只需要一条命令。”
[8秒–13秒] “滚动浏览功能列表 — {提及 2-3 个可见功能}。”
[13秒–18秒] “{Star数} Star,{Fork数} Fork,以及一个不断壮大的社区。”
[18秒–23秒] “在 GitHub 上 Star 它。链接在简介中。”
[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": "完整脚本内容",
    "model_id": "eleven_multilingual_v2",
    "voice_settings": {
      "stability": 0.35,
      "similarity_boost": 0.8,
      "style": 0.25,
      "use_speaker_boost": true
    }
  }' \
  --output github-promos/<仓库名>-tour/assets/narration.mp3

确认文件存在且大小大于 0。

第 3 步:转录并生成时间映射

生成音频后,提取逐字时间戳:

选项 A:ElevenLabs 时间戳(如果 output_format: "mp3" 不是唯一输出,则会在 API 响应中返回 — 请查阅 API 文档了解 aligned 输出)。

选项 B:使用 ffmpeg + Whisper(带单词时间戳的本地转录):

# 如有需要请安装 whisper
pip install openai-whisper

# 使用单词时间戳进行转录
whisper github-promos/<仓库名>-tour/assets/narration.mp3 \
  --model base \
  --output_format json \
  --output_dir github-promos/<仓库名>-tour/assets/ \
  --word_timestamps True

输出提供一个 words[] 数组,其中包含每个单词的 start 和 end 时间戳。将这些时间戳映射到滚动位置。

第 4 步:构建 HyperFrames 合成

创建 index.html,遵循 HyperFrames 合成架构:

<!DOCTYPE html>
<html lang="zh-CN">
<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="{仓库名}-tour"
  data-width="1080"
  data-height="1920"
  data-start="0"
  data-duration="{总时长}">

  <audio id="narration-audio"
    src="assets/narration.mp3"
    data-start="0"
    data-duration="{总时长}"
    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">在 GitHub 上 Star</div>
    <div class="cta-subtitle">{仓库描述}</div>
    <div class="cta-button">github.com/{所有者}/{仓库名}</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 = [
  // ["这是", 0.0, 0.3],
  // ["一个", 0.3, 0.5],
  // ["示例", 0.5, 1.0],
  // ...
];

var TOTAL_DURATION = /* 音频总秒数 */;

// ── 构建字幕 <span> ────────────────────────────────
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:在 80% 处淡入 CTA 覆盖层
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["{仓库名}-tour"] = tl;
</script>
</body>
</html>

第 5 步:渲染

cd github-promos/<仓库名>-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 数组中都有一个 [单词, 开始秒数, 结束秒数] 条目。

三种视觉状态

字幕栏中的每个单词都有三种 CSS 状态:

状态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 时刻调用一个函数,将 当前单词 → active 状态并转换 上一个单词 → past 状态。这创建了一个 卡拉 OK 风格的逐字高亮,与音频完美同步。

排版

  • 字体:Inter 700,42px
  • 位置:底部 180px,居中,最大宽度 1000px
  • 背景:无背景框 — 单词浮动在滚动内容之上,通过暗/亮/暗渐变使其在任何内容上都可读
  • Z-index:100(位于滚动内容 z-index 1 之上,低于 CTA 覆盖层 z-index 200)

布局考虑

单词使用 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 拍:数据


此技能将 website-to-hyperframes 工作流专门用于 GitHub 仓库导览视频。

Individual skills in this repo

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

相关技能