Hao0321/video-autopilot-kit
PythonFill-in-your-own-data framework for YouTube / short-form video automation: CapCut JSON + ffmpeg tooling + an onboarding questionnaire. Ships with zero private data.
pip install video-autopilot-kit🎬 video-autopilot-kit
一套框架式的 YouTube / 短影音自動化工具 + 方法論模板。 給你純程式 ffmpeg pipeline + CapCut 自動化的程式碼，加上一份「問卷」—— 你回答關於你自己頻道的問題，它就變成屬於你的系統。
⚠️ 不含任何原作者的私人數據 —— voice / 策略 / 社群數字全部是空白模板，你填你的。
🧭 我該走哪條路？（3 秒決策樹）
- 用 Mac / Linux？ → Path 1 Programmatic（純程式，跨平台，不碰 CapCut）
- 要 CapCut 的特效 / 花字 / 雲端模板？ → Path 2 CapCut-assisted（Windows 優先；版本敏感，先看 TROUBLESHOOTING 的版本相容矩陣）
- 只想全自動、不想開任何 GUI？ → Path 1 Programmatic
▶️ 60 秒看它跑（不用 CapCut、不用真素材）
想先看它真的會動？examples/ 裡有自包含、可直接跑的 demo —— 用 ffmpeg 合成測試素材，不需要任何真實影片或 CapCut：
python examples/01_vertical_short.py # 合成素材 → 完整 1080x1920 直式 Short
python examples/02_caption_broll_match.py # 零設定：b-roll 用內容命名就自動對位字幕
需求：Python 3.9+ 與 ffmpeg/ffprobe（只有 example 01 需要 ffmpeg）。細節見 examples/README.md。
為什麼不一樣
市面上的「creator 系統」要嘛賣你某個人的設定（抄了對你沒用、還可能誤導），
要嘛太通用沒有方法論。這個 kit 給你骨架（經實戰的結構），
SETUP.md 一區一區問你問題，用你的答案填滿它 —— 這樣它才真的是你的系統。
內容 —— 兩條 first-class path
這個 kit 有兩條同等地位的路，不是「主力 vs 次要」：
| 路徑 | 模組 | 是什麼 | 平台 |
|---|---|---|---|
| ⭐ Path 1 — Programmatic（推薦採用者預設） | src/longform_maker/ |
教學長片模組 —— fx_lib premium 動態引擎（亞像素 Ken Burns / 雙層 bloom / light sweep / easing / 合成 SFX）、word_captions 字級時間字幕（M105）、screen_clean 螢幕錄影機械化清理（M104）。參數真值 → knowledge/premium-motion-fx.md |
Win / Mac / Linux |
| ⭐ Path 1 — Programmatic | src/silent_vlog_maker/ |
純 ffmpeg pipeline —— 直式 Shorts（多色字幕 / BGM 高光起點 / 正規化）、靜音 vlog、素材清理 | Win / Mac / Linux |
| ⭐ Path 1 — Programmatic | src/capcut_helpers/ 的 QA gates |
交付前機械化 QA（delivery_qa：頻閃·死空檔·caption-sync·全幀掃描 M91-M95 / broll_audit 占比 / caption_broll_matcher 對位）—— 純 ffmpeg/Python，不需要 CapCut，兩條 path 的成品都該過這關 |
Win / Mac / Linux |
| Path 2 — CapCut-assisted（作者本人主用） | src/capcut_helpers/ 其餘 |
CapCut Desktop 自動化 —— 草稿 JSON 直改（draft I/O / 4-level 靜音 / 花字 / AI 字幕校正）+ AI 助手 + Computer Use 操作 CapCut 視窗（套模板 / 匯出）。版本敏感 → TROUBLESHOOTING | Windows-first |
| 共用 | knowledge/ |
影片製作知識庫 —— M1-M106 避坑大全 + 演算法 + SOP + 剪輯心法 | — |
| 共用 | ▶️ examples/ |
自包含可跑 demo —— ffmpeg 合成素材，60 秒看 pipeline 真的動（不用 CapCut/真素材） | — |
| 共用 | ⭐ SETUP.md |
從這開始 —— 回答問題讓系統變成你的 | — |
| 共用 | templates/ |
voice / 品牌 / 演算法 / 社群 的空白填寫模板 | — |
| 共用 | config.example.py |
路徑設定範例（複製成 config.py 填你的，範例不含任何帳號名） |
— |
誠實聲明：原作者的私人流程以 Path 2（CapCut） 為主 —— 但那是因為他的素材、模板、肌肉記憶都在 CapCut 上。 開源採用者多數應該從 Path 1 開始：跨平台、無 CapCut 依賴、不吃 CapCut 版本變動、全程可重現。 需要 CapCut 的花字/雲端模板時再上 Path 2。
Platform support
| 模組 | Windows | macOS |
|---|---|---|
Programmatic（longform_maker / silent_vlog_maker / QA gates） |
✅ | ✅（路徑/字型由 src/platform_compat.py 探測；Linux 同） |
CapCut 草稿 JSON 直改（capcut_helpers draft I/O） |
✅ 本機親測 | ⚠️ 路徑已支援（CAPCUT_USER_DATA env override + detect_draft_format()），自動化未在 Mac 實測 |
| Computer Use GUI 自動化（套模板 / 匯出） | ✅ | ❌（CapCut Mac 無 AppleScript dictionary；見 TROUBLESHOOTING 的 Mac 節） |
🚀 快速開始
- 讀
SETUP.md→ 照問題把templates/*.template.md填成profiles/*.md（或把整個 repo 丟給 Claude / ChatGPT，說「照 SETUP.md 問我問題，幫我生成 profiles/」） cp config.example.py config.py→ 填你的素材 / 匯出路徑（走 Path 2 才需要 CapCut 路徑）- 選路：Path 1 裝好 Python + ffmpeg 就能跑；Path 2 額外裝 CapCut Desktop + 開啟 AI 助手的 Computer Use（見下方需求）
- 開始用
src/的工具
需求
Path 1 — Programmatic（推薦採用者預設；Win / Mac / Linux）
- Python 3.9+
ffmpeg/ffprobe（在 PATH 上）- 不需要 CapCut、不需要 Computer Use —— 整條 pipeline 都是可重現的程式碼
- Mac/Linux：系統路徑與 CJK 字型由
src/platform_compat.py自動探測（不要 hardcode 系統字型路徑）
Path 2 — CapCut-assisted（作者本人主用；Windows-first、版本敏感）
- CapCut Desktop 國際版（有 Pro 更好）—— 剪輯 / 套字幕 / 套模板在這。⚠️ 版本敏感：草稿 JSON 直改對版本有相容矩陣（剪映 CN 6.0+ 已加密不可直改）—— 動手前先讀 TROUBLESHOOTING，並用
detect_draft_format()驗明文 - AI 助手 + Computer Use（Claude Desktop / Claude Code 等）—— GUI 自動化（套雲端模板 / 匯出）必需；Mac 上沒有可用的等效機制（見 TROUBLESHOOTING 的 Mac 節）
- Python 3.9+ 與
ffmpeg/ffprobe—— 匯出後的後製：BGM loop / 修剪到人聲尾 / player-safe 重編
(選用) AI 助手（Claude / ChatGPT）也能照 SETUP.md 自動把你的答案生成 profiles。
設計理念
一套創作系統最值錢的是結構與方法論，不是某個人的私人數字。 所以這個 repo 給你骨架，你用自己的血肉填滿。
License
MIT — 保留標註即可自由使用 / 修改 / 商用。
Author
Hao0321 Studio — 從一套實戰的個人創作系統抽出來的開源框架。