Remotion 程式碼解說影片生成器 (remotion-code-explainer)
概述
將任何原始碼檔案轉換為沉浸式、影格同步的 1920×1080 30fps MP4 Remotion 解說影片,採用 單畫面 Log2Base2 工作室格式。
絕不將畫面分割為相互競爭的並排窗格或擁擠的多卡片牆。每部影片皆使用 一個統一的視覺舞台 (<SinglePaneStage>),讓觀眾的注意力完全鎖定在程式碼如何執行:
- 精簡頂部欄 (
44px,內建於SinglePaneStage):- 左側顯示課程標題與當前活躍章節標籤;右側顯示細微的步驟計數器與細條進度條。
- 一個統一的 Log2Base2 舞台 (
SinglePaneStage— 100% 寬度):- 聚焦的單行重點標題:僅顯示當前步驟標題和單一活躍程式碼行 (使用清晰等寬字型,透過
borderBottom: "2px solid #FACC15"原地標記活躍的口語 token,絕不添加水平內距),外加一個在triggerFrame時彈入的緊湊活躍呼叫標籤 (token→白話解釋)。 - 全寬沉浸式 SVG 畫布 (
viewBox="0 0 1600 680"):寬敞、連續的動態圖形,在同一開放畫布上直接結合 Log2Base2 的記憶體/執行視覺元素 (標籤記憶體區塊0x1004、可變變數、動畫strokeDashoffset指標箭頭、推入/彈出的堆疊框架、陣列/樹狀結構交換) 與即時 UI/stdout/張量預覽。
- 聚焦的單行重點標題:僅顯示當前步驟標題和單一活躍程式碼行 (使用清晰等寬字型,透過
- 精簡底部字幕欄 (
VoiceoverCaptionBar—68px):- 清晰置中的逐字卡拉 OK 高亮字幕,由精確的 TTS
WordBoundary毫秒時間戳記 (startMs、endMs) 驅動。
- 清晰置中的逐字卡拉 OK 高亮字幕,由精確的 TTS
相依性
remotion-best-practices(~/.gemini/skills/remotion/SKILL.md):必須遵循所有 Remotion 動畫規則 (useCurrentFrame()、interpolate()、spring()、<Sequence premountFor>、<Audio>、@remotion/google-fonts和零 CSS 過渡)。uv(~/.gemini/config/plugins/science/skills/uv/SKILL.md):需用於執行uv run --with edge-tts以進行神經網路語音合成和WordBoundary時間戳記提取。
快速開始
# 1. 建立 Remotion 解說專案
uv run python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
scaffold \
--project-dir "/path/to/project" \
--source-file "/path/to/source.ext" \
--output "/path/to/project/scaffold-status.json"
# 2. 合成自然神經網路語音旁白 + 精確的逐字 & token 時間戳記
uv run --with edge-tts python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
synthesize-voiceover \
--project-dir "/path/to/project" \
--beats-json "/path/to/project/beats.json" \
--voice "en-US-AndrewNeural" \
--rate "+2%" \
--pause-sec 0.40 \
--output "/path/to/project/public/voiceover/manifest.json"
# 3. 透過快速的 8 工作執行緒關鍵影格去重複渲染器輸出最終 1080p 30fps MP4
uv run python3 \
~/.gemini/config/skills/remotion-code-explainer/scripts/code_explainer_cli.py \
render-mp4 \
--project-dir "/path/to/project" \
--composition-id "CodeExplainer" \
--out-name "Explainer.mp4" \
--concurrency 8 \
--output "/path/to/project/render-report.json"
沉浸式敘事與工作流程
- 設計充滿活力的章節 (
beats.json):- 撰寫清晰、對話式的旁白,立即吸引觀眾了解程式碼行為背後的原因。
- 保持
codeSnippet聚焦 (1–4行),以便傳遞給<SinglePaneStage>的活躍行能逐字包含活躍的token。 - 對於包含移動封包、指標跳躍、陣列交換或即時張量/UI 動畫的章節,設定
"motionStepFrames": 2。
- 建立專案與合成語音:
- 透過
scripts/code_explainer_cli.py執行scaffold(複製SinglePaneStage.tsx、VoiceoverCaptionBar.tsx和render_full_mp4.mjs) 和synthesize-voiceover。
- 透過
- 編寫全畫布動態圖形 (
viewBox="0 0 1600 680"):- 將您動畫化的 Log2Base2 × KodeKloud SVG 故事板作為
children傳遞給<SinglePaneStage>。 - 展示,而非講述:以實際的動畫取代靜態的程式碼牆和文字框——數值從暫存器/變數飛入記憶體插槽、指標平滑重新路由、資料封包在元件間傳輸,以及即時狀態/UI 輸出在同一開放畫布上更新。
- 將動態網格或滾動軌跡包裹在
<clipPath>中,使動畫不會溢出其區域。
- 將您動畫化的 Log2Base2 × KodeKloud SVG 故事板作為
- 驗證靜止畫面與渲染最終 MP4:
- 執行
npm run lint並使用read_file檢查代表性的靜止影格 (npx remotion still),確認無重疊或裁剪。 - 執行
render-mp4(scripts/render_full_mp4.mjs),確保最終的.mp4檔案儲存到out/、專案根目錄以及工作空間根目錄。
- 執行
速率限制與常見錯誤
scripts/code_explainer_cli.py強制執行/tmp/remotion_edge_tts.lock(0.35 秒間隔,3 次重試,退避時間為1 秒/2 秒/4 秒)。- 絕不使用 2 區域分割畫面儀表板或傾倒 40 行的滾動程式碼牆;保持畫面為一個
<SinglePaneStage>窗格。 - 絕不為高亮的行內
token添加水平padding(僅使用borderBottom: "2px solid #FACC15"和backgroundColor)。 - 絕不在 SVG 舞台內部使用靜態文字卡片,當可以透過動畫的記憶體/指標/封包動態來演示概念時。