PR 導覽影片
為 Pull Request 建立一個附有旁白的導覽影片。這是一個內部使用的產物,其好處如同 PR 作者自己錄製的 Loom 影片——逐步解說程式碼變更,解釋做了什麼以及為什麼,讓任何觀看者都能快速理解該 PR。
輸入: 一個 GitHub Pull Request URL(例如 https://github.com/tldraw/tldraw/pull/7924)。如果只提供 PR 編號或其他描述,則假設該 PR 位於 tldraw/tldraw 儲存庫。
輸出: 一個解析度為 1280×720 (30 fps) 的 MP4 影片,包含語音旁白、使用 Whisper 計時的黃底黑字字幕,以及標準化的開場/結尾幻燈片,儲存為 out/pr-<number>-walkthrough.mp4。
所有中間檔案(音檔、清單、腳本)都放在此技能目錄下的 tmp/pr-<number>/ 中。該目錄已加入 .gitignore。只有最終的 .mp4 檔案會存放在 out/ 目錄中。
從此技能目錄執行所有參照 ./scripts 或 ./video 的命令。
核心理念
這是從作者視角進行的導覽。 目標與 PR 作者坐下來向某人解說變更時相同——展示特定程式碼,解釋變更了什麼以及為什麼,並以能建立理解的順序進行。觀看者看完後應能理解程式碼的功能以及如何看待這些變更。
這意味著:
- 旁白主導一切。 先將導覽旁白寫成對 PR 的連續解釋。然後再決定在每個時刻畫面上應該顯示什麼內容來支援正在說的內容。
- 展示程式碼。 預設的視覺內容是程式碼差異或原始碼檔案。文字幻燈片是例外(開場、簡短過場、結尾),而不是常規。當旁白談到某個函式時,觀看者應該正在看著那個函式。
- 以邏輯順序解說變更,不一定要按照檔案順序或提交順序——但始終要錨定在具體的程式碼上,而不是抽象的描述。
- 解釋「為什麼」,而不只是「做了什麼」。 螢幕上的程式碼顯示了「什麼」變了。旁白則補充了推理過程——為什麼採用這種方法、它解決了什麼問題、它處理了什麼邊界情況。
工作流程
步驟 1:理解 PR
閱讀 PR 的提交、差異和描述。理解敘事主軸:
- 這解決了什麼問題?
- 採取了什麼方法?
- 關鍵機制是什麼?
git log main..HEAD --oneline
git diff main..HEAD --stat
跳過產生的檔案。 閱讀差異時,忽略自動產生而非手動編輯的檔案。這些只會增加雜訊,無助於導覽。此儲存庫中常見的範例:
**/api-report.md,**/api-report.api.md— 產生的 API 表面報告**/*.api.json,**/temp/*.api.json— API 提取器輸出apps/docs/content/reference/**— 產生的參考文件pnpm-lock.yaml,package-lock.json— 鎖定檔案**/CHANGELOG.md— 自動產生的更新日誌- 任何儲存庫工具重新產生的檔案(快照、結構轉儲、打包資源)
如果不確定某個檔案是否為產生的,請檢查是否有像「DO NOT EDIT」這樣的標頭註解,或檢查儲存庫是否有產生該檔案的產生器命令。在挑選要在 diff/code 幻燈片中展示的檔案時,請過濾掉這些。
步驟 2:撰寫旁白
將旁白寫成連續文字,並分成邏輯段落。每個段落是導覽的一個節拍——一個概念、一個變更或一組相關的變更。將其儲存為 tmp/pr-<number>/SCRIPT.md。
旁白讀起來應該像作者在向同事解釋 PR:「所以我們要做的是……核心問題是 X……我採取的方法是 Y……如果你來看這個函式……」
結構:開場 → 背景/問題 → 程式碼導覽 → 總結。請參閱下方的腳本結構。
如果提交很簡單且組織良好(通常在名稱包含 -clean 的分支上),你可以依照它們的提交訊息和描述來引導旁白。否則,請檢查程式碼並建立自己的敘事。以能建立在先前介紹的概念之上的順序來介紹概念。
避免冗餘,特別是在開場和第一個內容段落之間。
步驟 3:產生音檔和時間戳
為每個段落產生獨立的音檔,每個段落呼叫一次 TTS。這完全避免了分段、對齊和分割的問題——每個段落都足夠短,可以進行一次可靠的 TTS 呼叫。
撰寫一個 narration.json 檔案,然後執行 generate-audio.sh CLI 工具:
./scripts/generate-audio.sh narration.json tmp/pr-<number>/
API 金鑰: 自動從儲存庫的 .env 檔案(GEMINI_API_KEY)中取得。
Narration JSON 格式
{
"style": "以平靜、穩定、專業的語調朗讀以下導覽旁白。以適中的節奏說話,彷彿 Pull Request 的作者正在向同事解說程式碼變更。",
"voice": "Iapetus",
"slides": [
"此 Pull Request 為箭頭工具新增了分組感知的綁定解析功能……",
"核心問題是,當目標形狀位於群組內時……",
"如果你來看 ArrowBindingUtil.ts 中的 getBindingTarget 方法……"
]
}
style— 聲音角色和節奏指示。保持簡短且具體。voice— Gemini 聲音名稱(預設:Iapetus)。slides— 旁文字串陣列,每個條目對應一個段落。
運作方式
- 對於每個段落,腳本會建立一個提示:風格前言 + 段落文字。
- 每次呼叫
gemini-3.1-flash-tts-preview的 API 以產生一個 WAV 剪輯。 - 每個剪輯都會經過驗證(持續時間合理性檢查與字數比對),如果輸出不佳,會自動重試。
- 每個剪輯的前導/結尾靜音都會被修剪。
輸出: 每段落的音檔(audio-00.wav,……)和一個 durations.json 檔案,將每個音檔名稱映射到其持續時間(秒)。
相依性: ffmpeg / ffprobe。除了標準函式庫外,不需要 Python 套件。
請勿在旁文字中使用 [pause long] 或 [pause medium] 標記——模型可能會逐字讀出它們。
步驟 4:撰寫清單
讀取步驟 3 中的 durations.json 以取得每個剪輯的長度,然後在與音檔相同的目錄中撰寫 manifest.json。它列出了每個幻燈片的一個條目(按順序),每個條目都包含其 type、audio 和 durationInSeconds。
請參閱 references/manifest.md 以了解幻燈片類型及其欄位。
步驟 5:渲染影片
執行 render.sh 腳本:
./video/render.sh \
tmp/pr-<number>/manifest.json \
out/pr-<number>-walkthrough.mp4
該腳本會:
- 將參照的音檔/圖片檔案複製到
video/assets/。 - 對每個音檔執行 Whisper 轉錄 →
video/transcripts/audio-NN.json(冪等——僅在音檔比現有轉錄更新時才重新轉錄)。 - 執行
build.mjs <manifest>以產生video/index.html——一個具有計時剪輯的超幀 (hyperframes) 組合,包含用於轉場和程式碼焦點移動的 GSAP 時間線,以及從 Whisper 轉錄中得出的具有開始/結束時間的黃底黑字字幕剪輯。 - 檢查組合的格式錯誤,並透過
npx hyperframes render渲染 1920×1080 幀。 - 使用 ffmpeg(CRF 26 + AAC 96k)縮小到 1280×720 / 30fps 並重新壓縮,以獲得最終小巧但清晰的 MP4。
相依性: Node.js 22+、ffmpeg、Python 3(由 render.sh 用於解析清單)。hyperframes 透過 npx --yes 呼叫,因此無需安裝步驟。Whisper 在本地執行(small.en 模型,首次下載約 150MB)。
透過 Whisper 同步字幕
字幕以黃色文字顯示在黑色背景上,固定在畫面底部。它們的開始/結束時間來自字詞級別的 Whisper 轉錄,這些轉錄被分組為 5–7 個單詞的區塊,並在自然停頓處(>450ms 的間隔 = 句子邊界)提前中斷。一個影響是:Whisper 會按語音轉錄品牌/程式碼名稱——「tldraw」→「TL Draw」,「OverlayUtil」→「overlay util」。這對於字幕來說可以接受,但稍後可以透過 build.mjs 中的替換表進行標準化。
檔案大小調整
預設渲染目標是 8 分鐘影片約 30–60 MB。若要調整:
render.sh中 ffmpeg 縮小步驟的--crf <n>——22 接近無損,26 是預設值,30+ 會更小。對於文件品質的結果,CRF 28–30 是不錯的範圍。- 1080p 超幀渲染使用
-q draft --crf 30來保持中間檔案較小(無論如何,縮小步驟主導了最終大小)。
檔案組織
最終輸出位於此技能目錄中。所有中間檔案都放在 tmp/(已加入 .gitignore):
pr-walkthrough/
├── SKILL.md # 本檔案
├── scripts/ # CLI 工具(已簽入)
│ └── generate-audio.sh # narration.json → 每個幻燈片的 WAV + durations.json
├── video/ # Hyperframes 專案(已簽入)
│ ├── hyperframes.json # hyperframes 設定
│ ├── meta.json # 專案元資料
│ ├── build.mjs # manifest.json → index.html 組合
│ ├── render.sh # manifest.json → 720p MP4(完整管線)
│ ├── assets/ # 渲染時自動填充(已加入 .gitignore)
│ ├── transcripts/ # Whisper 字詞級別 JSON(已加入 .gitignore,已快取)
│ └── renders/ # 中間 1080p 渲染(已加入 .gitignore)
├── out/ # 最終輸出(已加入 .gitignore)
│ └── pr-XXXX-walkthrough.mp4
└── tmp/ # 中間檔案(已加入 .gitignore)
└── pr-XXXX/
├── SCRIPT.md # 旁白腳本
├── narration.json # generate-audio.sh 的輸入
├── durations.json # 音檔名稱 → 持續時間(秒)
├── manifest.json # render.sh 的輸入
└── audio-XX.wav # 每個段落的音檔
API 設定
- Gemini API 金鑰: 儲存在專案根目錄的
.env檔案中,作為GEMINI_API_KEY。用於 TTS 和音頻對齊。 - TTS 模型:
gemini-3.1-flash-tts-preview - TTS 語音:
Iapetus(始終使用)
腳本結構
導覽遵循一致的敘事主軸。並非每個部分都需要自己的段落——根據 PR 的複雜度來合併或跳過部分。目標是總共 8-12 個段落,其中絕大多數都展示程式碼。
開場(1 個段落)
開場卡片:tldraw 標誌 + PR 標題 + 日期。旁白應為一句話,從高層次說明這個 PR 的作用。先不要深入細節。
清單幻燈片類型:intro。
背景(0-1 個段落)
在深入程式碼之前進行簡要說明。這個 PR 之前的狀況是什麼?是什麼問題或需求促成了這項工作?保持簡短——只需提供足夠的背景資訊,讓程式碼導覽有意義。
- 要具體:「當目標形狀在群組內部時,箭頭綁定失效了」,而不是「綁定有問題」
- 指出受影響的程式碼庫區域
如果可以在展示第一段相關程式碼的同時解釋背景,請跳過獨立的背景段落,將其合併到第一個程式碼段落中。
清單幻燈片類型:text 或 diff(如果展示有問題的程式碼)。
程式碼導覽(6-10 個段落)
影片的主體。逐步解說實際的程式碼變更,展示具體的差異和檔案,同時解釋做了什麼以及為什麼。
每個段落都應展示程式碼。 使用 diff 幻燈片來展示變更,使用 code 幻燈片來展示未變更的參考程式碼。
指導原則:
- 命名檔案和函式。 每個附有旁白的段落都應至少參照一個特定的檔案或函式。
- 展示差異。 每個段落的視覺內容應該是正在討論的實際差異。使用
git diff main..HEAD -- path/to/file來取得差異,然後提取相關的區塊。 - 按理解順序,而不是檔案順序。 以能建立理解的順序來呈現變更。如果在一個檔案中定義了新類型並在另一個檔案中使用,請先展示定義。
- 解釋「為什麼」,而不只是「做了什麼」。 差異顯示了「什麼」變了——旁白則補充了推理過程、它處理的邊界情況以及考慮過的替代方案。
- 跳過樣板,但提及它。 不要為每個匯入變更或類型匯出保留一個段落,但可以順帶提及:「
index.ts中也新增了一些類型匯出——這些只是我們接下來會看到的新類型的重新匯出。」 - 將相關的小變更分組。 如果三個檔案都經歷了相同的單行修正,一個段落可以涵蓋所有三個。逐一提及每個檔案的名稱。
總結(1 個段落)
簡要回顧 PR 完成了什麼。這是一個簡短的結尾——用一兩句話總結整體變更,如果相關,提及任何已知的限制或後續工作。
清單幻燈片類型:text。
結尾(1 個段落,無聲)
tldraw 標誌,3 秒靜音。始終將其作為最後一個幻燈片包含在內。
清單幻燈片類型:outro,且 durationInSeconds: 3。
旁白撰寫技巧
- 對程式碼要具體。 說「在
BindingUtil.ts中,onAfterChange處理程式現在會檢查群組祖先」——而不是「綁定系統已更新。」命名檔案和函式,以便觀看者可以將旁白與螢幕上的內容連結起來。 - 每個段落 = 一個變更或一組密切相關的變更。 如果你無法為該段落指出一個特定的差異,它可能太抽象了。
- 以作者的身份撰寫。 語氣應該是解釋性的且自然的——就像在向某人解說你的工作。「所以這裡主要的是……」或「棘手的部分是……」都可以。
- 避免開場和第一個內容段落之間的冗餘。
- 提及未展示的檔案。 如果一個 PR 觸及了 15 個檔案,但只有 6 個是重要的,簡短地確認一下其他的:「其餘的變更是類型匯出和測試裝置。」
- 目標是總共 5-7 分鐘 的旁白。
檢查清單
- 閱讀所有 PR 提交並理解完整的差異
- 在 SCRIPT.md 中撰寫旁白(8-12 個段落)
- 為每個段落產生音檔(Iapetus 聲音)
- 讀取 durations.json 以取得每個段落的持續時間
- 撰寫清單