建議：載入 Remotion 最佳實踐

此技能受益於 remotion-best-practices（未捆綁）以獲得完整的 Remotion 模式庫。若無此庫，使用下方最低規則即可。

Pi：在可用技能清單中讀取已載入的 remotion-best-practices 技能。

Claude Code：在繼續之前，先呼叫 remotion-best-practices 技能/工具。

尚未安裝？請從 remotion-dev/skills 取得（文件：remotion.dev/docs/ai/skills）。

如果未安裝 remotion-best-practices，最低規則如下：必須有 Chromium 可用，始終將 4K 內容包裹在 <Scale4K> 中，使用帶有 linearTiming 的 <TransitionSeries>，並將音訊視為主時鐘。

影片播客製作工具是做什麼的？

用於從一個主題自動化製作 4K Bilibili 橫向知識影片 的管線。包含：編碼代理 + TTS 後端 + Remotion + FFmpeg。

啟動 — 前置要求（在第 1 步之前執行）
執行模式 — 自動 vs 互動 → references/workflow-script.md
重新生成現有影片 — 疊代已完成的影片
工作流程 — 11 步驟管線 + 階段檔案指標 + 強制停止點
硬性規則 — 不可協商的生產限制
音訊主時鐘與同步
每個影片的目錄結構
其他資源 — 何時載入每個 references/ 檔案
使用者偏好
故障排除

啟動

將 SKILL_DIR 解析為包含此 SKILL.md 的目錄：

Pi：代理從已載入的技能清單中知道技能路徑 — 在執行指令前將 SKILL_DIR 設為該目錄。
Claude Code：${CLAUDE_SKILL_DIR} 會自動填入。

SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"

# 前置要求（CLI + 後端環境變數）
python3 "${SKILL_DIR}/scripts/check_prereqs.py"

更新通過 skills CLI (npx skills update video-podcast-maker -g) 進行；直接 git clone 安裝則依照 README 使用 git pull。此技能不執行更新檢查。

前置要求失敗 — 請參閱 README.md 進行設定。此檢查會感知後端（解析 TTS_BACKEND 環境變數 → user_prefs.json global.tts.backend → 預設 edge），因此只會驗證活動後端所需的環境變數。

新專案的第一部影片？ 建議重用已安裝 node_modules/ 的現有 Remotion 專案 — 建立新專案會下載約 2.2 GB 的 npm 套件和一個 90 MB 的 Chrome Headless shell（每個專案僅一次）。如果使用者有先前影片的專案，請使用它。如果需要新專案，請在執行步驟 1-4（主題研究和腳本撰寫）時在背景執行 npm install。

所有渲染輸出都放在 videos/{name}/ 中 — 每個 output.mp4、final_video.mp4 和 thumbnail_*.png 都直接放置到每個影片的目錄中。永遠不要渲染到 out/ 或 dist/ 目錄；--public-dir videos/{name}/ 的約定使一切保持自包含。

TTS 引擎 — 兩個本地後端，無需外部技能：

edge（預設） — 免費，無需金鑰，透過 edge-tts 運作。
azure — 需要 AZURE_SPEECH_KEY + AZURE_SPEECH_REGION（Microsoft Speech SDK）。

每個都在內部合成（scripts/tts/backends/native.py）— 內建發音（顯示 → 口語 → 返回顯示以產生字幕）和音素應用。check_prereqs.py 會驗證活動後端的環境變數。

多平台 TTS？ 先前提供 9 後端矩陣的 ttscn 組件技能不再是此技能的依賴項。如果您需要這些平台，請單獨安裝 Agents365-ai/ttsCN 並直接呼叫它 — 此技能僅提供 edge + azure。

設計學習捷徑：如果使用者提供參考影片/圖片或要求儲存/列出/刪除樣式設定檔，請參閱 references/design-learning.md，而不是執行下面的工作流程。

執行模式

在工作流程開始時偵測自動模式（預設）與互動模式 — 自動預設決策表和每次請求的覆寫選項在 references/workflow-script.md 中。

重新生成現有影片

如果 videos/{name}/ 已經存在且使用者正在疊代已完成或進行中的影片，請重用該目錄。不要啟動新專案或新的 videos/{newname}/ 目錄。

根據實際變更的內容選擇最小的重新執行：

變更的內容	重新執行	重用的部分（不要重做）
旁白腳本 (`podcast.txt`)	步驟 7 (TTS) → 步驟 8 預覽 → 渲染+混音	主題研究 + 章節設計
僅視覺（元件、佈局、顏色）	步驟 8 預覽 → 渲染+混音	音訊 (`podcast_audio.wav` / `timing.json`)
僅背景音樂	重新混音 BGM	`output.mp4`（無需重新渲染）
僅字幕	步驟 10.1 最終化	`output.mp4` / `video_with_bgm.mp4`

任何會改變觀眾所看或所聽內容的重新執行，都需要重新進入步驟 8 的關卡：套用變更，讓 Studio 熱重載，並等待新的明確「渲染 4K」確認 — 先前的確認不會延續。腳本的變更會改變每個下游時間戳記，因此始終透過 TTS 重新生成 timing.json — 永遠不要手動編輯。在任何重新執行之後，請重新驗證：

python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/

工作流程

正在疊代已完成的影片？ 如果 videos/{name}/ 已經存在，請參閱上面的重新生成現有影片以取得最小重新執行方案 — 不要從步驟 1 開始。

在步驟 1 開始時，在您的代理任務清單中為每個步驟建立一個任務。開始時標記為 in_progress，完成時標記為 completed。videos/{name}/ 中的檔案是持久記錄 — 如果中斷，請檢查目錄以確定從何處繼續。

#	步驟	輸出	階段檔案
1	定義主題方向	`topic_definition.md`	workflow-script.md
2	研究主題	`topic_research.md`	workflow-script.md
3	設計 5-7 個章節	（記憶體中）	workflow-script.md
4	撰寫旁白腳本	`podcast.txt`	workflow-script.md
4.5	發音預檢 (zh-CN)	`phonemes.json`	workflow-script.md
5	素材計畫與解析	`assets/manifest.json`	workflow-assets.md
6	生成縮圖 (16:9 + 4:3)	`thumbnail_*.png`	workflow-production.md
7	生成 TTS 音訊	`podcast_audio.wav`, `timing.json`	workflow-production.md
8	Remotion 合成 + Studio 預覽	—	workflow-production.md
9	渲染 4K + 混入 BGM	`output.mp4`, `video_with_bgm.mp4`	workflow-production.md
10	發布資訊 + 驗證輸出	`publish_info.md`, `final_video.mp4`	workflow-publish.md
11	生成垂直短片（可選）	`shorts/`	workflow-publish.md

強制停止點（上表中的粗體行）：

步驟 8 — Studio 審查。 必須啟動 npx remotion studio 並等待使用者回饋，才能渲染。在使用者明確確認（「渲染 4K」/「渲染最終版」）之前，永遠不要渲染 4K。包含調整請求的回覆不是確認 — 套用變更，讓 Studio 熱重載，然後再次詢問。每一輪調整都需要在步驟 9 之前獲得自己的全新確認。
步驟 10 — verify_output.py。 必須通過才能宣告影片完成。退出碼 0 = 綠燈；退出碼 2 = 仍有警告但可發布。自動修正常見遺漏（如果缺少則建立 final_video.mp4）。根據平台矩陣驗證發布資訊（標題、描述、標籤、章節）— 在步驟 5.5 和 10.2 中生成。若要取得機器可讀的輸出，請加上 --format json。

渲染前審計（建議） — 在步驟 8 之前：

python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>

標記與旁白偏差超過 1.5 秒的節拍。

自動模式：視覺自我審查。 在自動模式下執行時（沒有使用者觀看 Studio），在要求渲染確認之前，先渲染 3-5 張關鍵幀靜態圖片：

npx remotion still src/remotion/index.ts <CompositionId> videos/{name}/_review_001.png --public-dir videos/{name}/ --frame=<midpoint_frame>

選擇幀：英雄標題（約 10% 處）、密集章節的中點以及結尾。將靜態圖片以圖片形式讀回，並針對實際渲染輸出執行 design-guide.md 和 visual-taste.md 檢查清單。在 4K 渲染之前捕捉溢出、對比度和佈局回歸。審查後刪除 _review_*.png。

驗證檢查點

在步驟之後	檢查
7 (TTS)	`podcast_audio.wav` 可播放 · `timing.json` 涵蓋所有章節 · SRT 為 UTF-8 編碼
9 (渲染)	`output.mp4` 為 3840×2160 · 影音同步 · 無黑幀
10 (驗證)	`verify_output.py` 退出碼為 0（或 2，但需審查過警告）

硬性規則

規則	要求
單一專案	所有影片都在使用者的 Remotion 專案中的 `videos/{name}/` 下。永遠不要為每個影片建立新專案。
4K 輸出	3840×2160（或垂直 2160×3840），在 1920×1080 設計空間上使用 `scale(2)` 包裝器
音訊同步	音訊（`podcast_audio.wav` + `podcast_audio.srt`）是主時鐘。`timing.json` 必須從真實的 TTS 輸出生成，永遠不要手動估計。渲染前，最終影片持續時間必須與音訊匹配，誤差在 ±0.5 秒內。請參閱音訊主時鐘與同步。
縮圖	必須生成 16:9（1920×1080）和 4:3（1200×900）—— 請參閱 design-guide.md
渲染前必須啟動 Studio	必須啟動 `remotion studio` 進行審查。在使用者明確確認之前，永遠不要渲染 4K。調整回饋 ≠ 確認 — 套用、熱重載、再次詢問。
`--public-dir`	每個 Remotion 指令都使用 `--public-dir videos/{name}/`。所有輸出檔案（output.mp4, final_video.mp4, 縮圖）都直接放入 `videos/{name}/` 中 — 永遠不要放到 `out/` 或 `dist/` 目錄。

視覺最小值（文字大小、內容寬度、安全區域、動畫安全性）在 references/design-guide.md 中。必須在步驟 8 之前載入。

音訊主時鐘與同步

黃金法則

音訊是主時鐘。 每個幻燈片開始、字幕、章節和動畫節拍都源自 podcast_audio.wav 和 podcast_audio.srt。
從 TTS 生成時間，而不是從文字估算。 管線：podcast.txt → generate_tts.py → podcast_audio.wav + podcast_audio.srt + timing.json → 合成 → 渲染。
永遠不要在音訊存在之前手動編寫 timing.json。 如果您已經有策劃好的幻燈片，請執行 align_timing_from_srt.py 將它們錨定到真實的 SRT。
補償 TransitionSeries 重疊。 TransitionSeries 渲染 sum(section.duration_frames) - (N-1) * transitionFrames 個影格。按比例縮放每個章節，使渲染長度等於 timing.total_frames。不要將所有重疊影格塞入第一個章節。修正後的模式在 templates/Video.tsx 中。

強制同步檢查點

時機	檢查
步驟 7 (TTS) 之後	`timing.json.total_duration` 與 `podcast_audio.wav` 匹配，誤差在 ±0.5 秒內
渲染之前	`Video.tsx` 為轉場重疊縮放所有章節
渲染之後	`final_video.mp4` 持續時間與 `podcast_audio.wav` 匹配，誤差在 ±0.5 秒內
步驟 10 (驗證)	`verify_output.py` 退出碼為 0 並在音訊/時間方面報告綠燈

如果任何檢查點失敗，請停止。不要發布。

輸出規格

參數	橫向 (16:9)	垂直 (9:16)
解析度	3840×2160 (4K)	2160×3840 (4K)
影格率	30 fps	30 fps
編碼	H.264, 16Mbps	H.264, 16Mbps
音訊	AAC, 192kbps	AAC, 192kbps
持續時間	1-15 分鐘	60-90 秒（精華片段）

每個影片的目錄結構

project-root/                           # Remotion 專案根目錄
├── src/remotion/                       # Remotion 原始碼 (Root.tsx, compositions, index.ts)
├── videos/{video-name}/                # 每個影片的目錄
│   ├── topic_definition.md             # 步驟 1
│   ├── topic_research.md               # 步驟 2
│   ├── podcast.txt                     # 步驟 4：旁白腳本
│   ├── phonemes.json                   # 步驟 4.5：zh-CN 發音覆寫
│   ├── assets/manifest.json            # 步驟 5：每個章節的素材註冊表
│   ├── publish_info.md                 # 步驟 10：標題/描述/標籤
│   ├── podcast_audio.wav               # 步驟 7：TTS 音訊
│   ├── podcast_audio.srt               # 步驟 7：字幕
│   ├── timing.json                     # 步驟 7：時間線（驅動動畫）
│   ├── thumbnail_*.png                 # 步驟 6
│   ├── output.mp4                      # 步驟 9：4K 渲染
│   ├── video_with_bgm.mp4              # 步驟 9：含背景音樂
│   ├── final_video.mp4                 # 步驟 10：最終輸出
│   └── bgm.mp3                         # 背景音樂
└── remotion.config.ts

每個影片的 `--public-dir`

每個 Remotion 指令都使用 --public-dir videos/{name}/ — 每個影片的素材都留在自己的目錄中，從而實現並行渲染：

npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render ... videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16000K

其他資源

這些參考檔案包含詳細的工作流程腳本、生產和發布指引。僅在達到所述步驟時才載入它們。

檔案	何時載入
references/workflow-script.md	步驟 1 — 主題定義指南（研究 + 腳本結構）
references/workflow-assets.md	步驟 5 — 素材來源與解析指引
references/workflow-production.md	步驟 6 — TTS + Remotion + Studio + 渲染
references/workflow-publish.md	步驟 10 — 發布資訊、驗證、社交平台矩陣
references/design-guide.md	步驟 8 之前 — 視覺最小值和指引
references/visual-taste.md	步驟 8 之前 — 美學和情緒檢查（自動模式自我審查使用）
references/design-learning.md	當使用者提供參考影片/圖片以學習其風格時

使用者偏好

使用者可以在使用者專案根目錄的 user_prefs.json 中設定全域或每個影片的偏好（相對於 SKILL.md 位置）。如果存在，則在步驟 1 開始時載入。此技能使用以下鍵：

{
  "global": {
    "tts": {
      "backend": "edge",         // "edge" | "azure"
      "voice": "zh-CN-XiaoxiaoNeural"
    },
    "bgm": {
      "enabled": true,
      "volume": 0.15
    },
    "format": "horizontal",      // "horizontal" | "vertical"
    "resolution": "4K",          // "4K" | "1080p"
    "platform": ["bilibili"]     // 目標平台，影響發布元數據
  },
  "per-video": {
    "my-video-name": {            // 與 videos/{name}/ 匹配
      "tts": { "voice": "zh-CN-YunxiNeural" }
    }
  }
}

故障排除

`npx remotion studio` / `npx remotion render` 找不到 `remotion.config.ts`

在 Remotion 專案根目錄中執行指令。

渲染失敗，錯誤 "No composition found"

驗證組合 ID 與 src/remotion/index.ts 中註冊的 ID 匹配。

TTS 生成失敗，錯誤 "No module named edge-tts"

pip install edge-tts

Azure TTS 失敗，錯誤 "401 Unauthorized"

驗證 AZURE_SPEECH_KEY 和 AZURE_SPEECH_REGION 是否已設定且有效。

音訊不同步

執行 verify_output.py 以取得同步報告。如果時間漂移 > 0.5 秒，請從步驟 7（TTS）重新生成時間。

影片播客製作工具