Communitygithub.com

cosmicstack-labs/mercury-agent-skills

為任何 GitHub 儲存庫頁面產生一個 15-30 秒的滾動式影片導覽,包含 ElevenLabs AI 語音旁白以及逐字同步字幕。它會擷取全頁行動版視口螢幕截圖,使用 GSAP 從上到下滾動,並透過 HyperFrames CLI 將同步字幕燒錄到最終的 MP4 檔案中。

mercury-agent-skills 是什麼?

此技能專門用於建立經過精心排練的 GitHub 儲存庫影片導覽,非常適合在 Instagram Reels 或 YouTube Shorts 等社交媒體平台上展示開源專案。它會自動化整個流程:首先擷取儲存庫的完整行動版螢幕截圖,然後根據頁面內容產生旁白腳本,接著透過 ElevenLabs API 生成 AI 語音,再使用 Whisper 進行逐字時間戳記轉錄,最後在單一的 HyperFrames 組合中將所有元素(滾動、旁白、卡拉 OK 式字幕和結尾的行動呼籲疊加層)編排在一起。最終成果是一個全畫幅 1080x1920 的肖像影片,其中的視覺效果會與旁白的每個字完美同步,創造出一個流暢、引人入勝的預覽畫面。此技能特別專注於 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 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

預覽

來自技能 README

mercury-agent-skills 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 參與度的甜蜜點
旁白驅動時間軸滾動速度、節拍持續時間和字幕時間都從音訊衍生
字幕逐字高亮每個字在旁白者說出時亮起 — 卡拉 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 取得儲存庫後設資料:

  • 星星數、分叉數、觀看數、未解決議題數
  • 主要程式語言、描述、主題標籤
  • 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 秒的腳本,描述隨著滾動進度,觀看者看到了什麼。旁白者引導觀看者瀏覽頁面:

[0s–4s]  "這是 {儲存庫}。{一句話描述}。"
[4s–8s]  "這裡是 README — 安裝只需要一個指令。"
[8s–13s] "滾動瀏覽功能列表 — {提及 2-3 個可見功能}。"
[13s–18s] "{星星數} 顆星星,{分叉數} 個分叉,以及一個成長中的社群。"
[18s–23s] "在 GitHub 上按星星。連結在個人簡介中。"
[23s–25s] "追蹤以獲取更多。"

腳本規則:

  • 旁白者在每個滾動位置參考 當前螢幕上 的內容。
  • 總字數: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 時間戳記 (如果 API 回應中除了 output_format: "mp3" 之外還有其他輸出 — 請查閱 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

輸出會提供包含每個單字 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="{儲存庫}-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 上按星星</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],
  // ["mercury-skills", 0.3, 0.5],
  // ["儲存庫", 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});

// Phase 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);

// Phase 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]);
});

// Phase 3: CTA 疊加層在 80% 時淡入
tl.to("#cta-overlay", { opacity: 1, duration: 0.5, ease: "power2.out" }, ctaStart);

// Phase 4: CTA 期間淡化字幕列
tl.to("#subtitle-bar", { opacity: 0.3, duration: 0.5 }, ctaStart);

// Phase 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 狀態:

狀態類別視覺效果
即將到來.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。這會建立一個卡拉 OK 風格的逐字高亮,並與音訊完美同步。

排版

  • 字型: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:統計數據
  {
  
…

[為翻譯而截斷]

Individual skills in this repo

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

相關技能