pyJianYingDraft 開源實測，用 Python 把剪映草稿與字幕自動組好

用 AI 摘要這篇文章：

ChatGPT Claude Perplexity Google Grok

我在 Mac 上裝好這套函式庫，跑一段三十行左右的腳本，剪映的草稿資料夾裡就多出一支完整的影片骨架：一條影片軌、一條音訊軌、兩條文字軌，外加從 SRT 檔直接落位的兩句字幕，時間軸以微秒記錄。整個過程剪映本體一次都沒打開。這就是 pyJianYingDraft 的工作方式：它不剪片、也不算片，只把「組裝」這件事變成程式碼，產物是一個剪映看得懂的草稿檔，渲染和匯出最後仍交回剪映。

這套 Apache-2.0 授權的開源函式庫由 GitHub 開發者 GuanYixuan 維護，2024 年 7 月建立，2026 年 9 月已累積 4,282 顆星、655 次 fork、215 次提交，最新版 0.3.0 在 2026 年 7 月 8 日發布，是單人多媒體自動化需求裡少見的高關注專案。它的價值和它的邊界是同一件事的兩面，底下先看我實際跑出來的東西。

Pin

我實際跑了什麼

測試環境是 macOS 加 Python 3.11 虛擬環境，pip 裝上 0.3.0 版後，腳本依序做四件事：用 DraftFolder 在指定的草稿資料夾建一份 1920×1080 的新草稿；加入一段 4 秒的測試影片與一段 10 秒的音訊，各帶淡入淡出；放一行帶樣式的文字；最後把一個只有兩句話的 SRT 字幕檔整批匯入字幕軌。存檔收尾後，資料夾裡多了兩個檔案：draft_meta_info.json 與 draft_content.json。

上面這半條管線是我在本機一步步跑出來的。至於草稿送回剪映打開後的實際畫面，以及那套自動匯出（只在 Windows 搭配剪映 6 以下版本成立），下文以官方文件與倉庫 issue 的紀錄為準。

打開產物：一支剪映草稿其實是兩個 JSON 檔

把 draft_content.json 攤開，結構比想像中樸素：素材集中在 materials 區，分成 videos、audios、texts 幾類；時間軸在 tracks 區，每條軌道掛著自己的片段；畫布設定就是一組寬高數字。我這次產出的草稿，素材計影片一件、音訊一件、文字三件（一行手寫文字加兩句字幕），軌道四條，片段共五個，全部塞在一個純文字檔裡。

最能說明「組裝可以交給程式」的證據，是字幕的時間戳。來源 SRT 檔寫的時間，與草稿 JSON 裡實際落位的時間逐微秒一致：

也就是說，配時間軸這件在剪映介面裡最磨耐心的事，可以完全移出 GUI：逐字稿先交給語音轉文字工具產出 SRT，再讓腳本整批匯入，人在剪映裡只剩抽查。時間的寫法也對程式友善，內部一律用微秒，但參數直接寫 “1.5s”、”1h3m12s” 這種字串也行，函式庫自動換算，我實測換算結果與文件宣稱一致。只有一個容易踩的坑：代表時間區間的 trange，第二個參數給的是持續時長而非常見程式慣例的結束時間，文件還特別用警告符號提醒，寫腳本時看清楚能省一次除錯。

還有一個使用上的小眉角來自官方快速上手文件：腳本存好草稿後，剪映的草稿列表不一定馬上看到新草稿，可能要進出一次既有草稿或重開剪映讓列表重新整理。第一次跑完找不到草稿先別慌，多半只是列表沒更新。

模板模式是另一條批次路線，思路跟從零組裝相反：先在剪映裡手工做一份複雜的效果（複合片段、文字特效這類程式難以重現的），把它當模板載入，之後讓腳本批次替換內容。官方提供三種替換：依名稱換素材（最穩，全部引用該素材的片段一起換）、依片段換素材並重新設定截取範圍（會連帶伸縮時間軸）、只換文字內容但保留全部格式。另外能把某個模板草稿的整條軌道原封複製到別的草稿，適合把多份模板拼成新的組合。想再深入的人可以呼叫素材檢查功能，把模板裡出現過的貼紙、花字、文字氣泡的資源編號列出來，之後就能用編號在程式裡重複引用同一批素材。

最反常的部分：字型路徑寫死一個 D:

拆 JSON 時最讓我意外的是文字片段裡的字型物件：路徑欄位的值是字面的一個 “D:”。翻套件原始碼找到出處，text_segment.py 那行後面跟著作者註解，意思是這個欄位並不會真正放置字型檔。換句話說，草稿裡的字型、特效、濾鏡根本不隨檔案走，只帶剪映素材庫的資源編號（resource_id），剪映打開草稿時自己去比對、下載。

我把套件內建的中繼資料表整個列舉了一遍：798 個字型、1,097 個影片特效、1,052 個濾鏡，每一項都帶一個 is_vip 旗標。統計出來的比例值得記住：字型有 318 個標 VIP，影片特效有 462 個，濾鏡則有 802 個，換算下來濾鏡只有約四分之一是免費帳號能引用的。

這個數字直接解釋了官方文件裡一條不太起眼的警告：匯出前請確認有相關權限，不用 VIP 功能或已經開通 VIP，否則匯出流程可能卡進無窮迴圈。腳本批次引用特效時若踩到 VIP 資源，自動化管線會在權限牆前空轉，這是寫腳本時就要先避開的地雷。

離線這件事也要分兩層看。我把整套件原始碼掃過一遍，找不到任何網路呼叫，草稿生成階段素材與腳本完全不出本機，這層乾淨。但資源落地靠剪映打開草稿時下載快取，所以離線只到生成這一步，特效與字型這些資源的落地仍要靠剪映連網下載。官方文件同樣提醒，未快取的動畫、特效、轉場可能載入逾時，字型沒快取時要把草稿開兩次才會出現。

為什麼 Mac 能寫草稿，卻不能自動匯出

從產物回頭看，這套工具的跨平台邊界就有了解釋。草稿既然只是 JSON，寫檔案天生跨平台，官方文件也明言 Linux 與 macOS 支援草稿生成和模板模式。匯出是另一回事：官方的自動匯出靠 uiautomation 這套 Windows 介面自動化函式庫，模擬人的操作去點剪映目錄頁的控制項，而剪映從 7 版起把這些控制項藏了起來，於是自動匯出只支援剪映 6 以下，官方聲明的測試環境是剪映專業版 5.9 與 6.8。匯出期間剪映視窗會被置頂、滑鼠游標會被接管，官方建議挑閒置或夜間時段跑。

Pin

同樣的脆弱性也出現在模板模式。新版剪映的 draft_content.json 往往不是可直接讀取的明文 JSON，想拿舊草稿當模板批次修改，得透過 fallback_loader 參數另外接一個讀取器才有辦法。倉庫裡 45 個開啟中的 issue，好幾個都在問同一件事：新版剪映找不到控制項、自動匯出怎麼辦；更早還有人在剪映 8 上回報匯出失效，作者回覆沒在 8.x 實測過，但 7.x 已把控制項藏起來，評估 8.x 同樣無法自動匯出。

把這幾件事擺在一起，邊界的源頭其實只有一個：剪映沒有提供任何官方 API。草稿格式是社群逆向出來的，介面控制項是作業系統留給輔助工具用的，兩者剪映都沒承諾過穩定。版本一改，加密草稿、藏控制項，管線就得跟著修。採用這套工具，等於接受一種「釘住舊版換自動化」的維運方式，官方文件也附了 issue 連結，裡面有阻止剪映 5.9 自動升級的討論，各種解法成敗互見。

你的環境能不能跑：過三個關卡

想採用的人先對照自己的環境，三個關卡各有不同的結論。

最前面的關卡是剪映還是 CapCut。pyJianYingDraft 針對剪映專業版，也就是字節跳動在中國大陸市場的剪輯器，國際版 CapCut 的草稿格式並不相同。同作者另有一個 CapCut 版本 pyCapCut，倉庫約 659 顆星，不過已將近一年沒有更新，成熟度要打折扣。日常用 CapCut 的台灣讀者，這套目前幫不上忙，除非工作流程本來就雙棲剪映。

作業系統決定管線走不走得完。Windows 上全功能可用；macOS 與 Linux 能生成草稿、能玩模板，但官方明言產生的草稿仍然要在 Windows 版剪映下匯出。Mac 使用者還有一個坑：issue #177 有使用者回報草稿在 Mac 剪映開啟時顯示內容損壞，後續有留言指向剪映在 Mac 上以沙盒執行，草稿要放進沙盒路徑內才讀得到。這是社群經驗而非官方文件，但值得放進心裡。

剪映版本則決定匯出那一環。要自動匯出就得把剪映釘在 6 以下；若接受手動匯出，官方功能表以剪映 10.8 對照，多數生成功能可用，影片遮罩效果暫不支援（官方預計 0.3.1 版修復），新版模板讀取需要額外讀取器。環境組合對照如下：

和直接算片的函式庫比起來，差別在分工。moviepy 那類工具連渲染都自己來，產出就是成片；pyJianYingDraft 只做組裝，渲染交回剪映，換到的是剪映的字型與特效生態、以及人在 GUI 裡逐支檢視的餘地，代價是離不開剪映本體跟它的版本限制。想用自然語言指揮剪輯的另一條路，可以看成風 videocut；想徹底離開剪映生態，則有開源剪輯器 OpenCut 這類選擇。

集中限制：採用前先看這幾條

這套工具的但書集中在權限、版本、功能與平台四個面向，一次看完再決定。

VIP 邊界如前述，批次選素材時就要避開標 VIP 的資源，否則匯出階段會空轉。版本釘住的成本要算進去：剪映 5.9 會自動升級，得另外處理；開啟中的 issue 裡遮罩效果失效、新版找不到控制項都是反覆出現的主題。匯出時整台機器等於交給腳本，游標被接管，不適合邊跑邊用。

功能面還有幾個已知上限：不支援曲線變速；模板匯入的軌道有限制，除了官方提供的三種替換功能外，不能在匯入的軌道上加片段、轉場或特效；從其他草稿匯入的軌道可能有順序問題。這些都是官方文件自己標註的，不算意外，但排流程時要留空間。

量產面向要單獨提醒：issue #181 有使用者回報剪出來的影片被平台扣了健康分，來問有沒有規避方法。工具能自動化組裝，平台端的內容評分規則它幫不了你，把大量結構雷同的影片推上平台，風險自己在內容端吸收。

另外有三個環節建議正式上量前先小規模試一輪：腳本產生的草稿在剪映裡打開後的實際渲染效果、Windows 上自動匯出跑長班次的穩定度、新版加密草稿接上額外讀取器後的模板讀取。這幾處變因多，文件描述與實際表現之間常有一段距離，先拿幾支不重要的素材驗過再投產。

判斷：誰該現在裝，誰先等

工作流程已經在剪映裡、產出的影片結構高度相似（換素材、換字幕、套模板）、手上有一台 Windows，符合這三個條件的人現在就值得裝。成功的樣子很具體：腳本跑完，剪映草稿列表多出幾十支等著檢視的草稿，人工只負責抽查和按下匯出，組裝工完全消失。匯出的成片若要批次上架，下游可以再接社群平台自動上傳工具把分發也省下來。

只剪單支片子的人不需要它，GUI 裡手動排快得多；純 CapCut 用戶短期內沒有對應版本可用，除非願意雙棲剪映；只有 Mac 又要求全自動的人缺了匯出那條腿，先想清楚最後一哩在哪裡跑。若試了之後發現匯出環節撐不住，退一步的用法仍然成立：草稿生成可用、匯出手動做，組裝的工時已經省下大半；要連渲染都擺脫剪映，那就回到 FFmpeg 或 moviepy 那條程式自帶輸出的路線，用放棄剪映特效生態換取整條管線的自給自足。