pyJianYingDraft 實測：Python 自動剪映的 4 個版本天花板

TL;DR：pyJianYingDraft 是一個用 Python 程式碼自動生成「剪映（JianYing）草稿」的開源庫，3.7k star、Apache-2.0、pip install pyJianYingDraft 就能裝。它讓你跳過手拉時間軸，用程式碼批次產影片草稿、跑全自動混剪流水線。但裝之前你得先知道 4 道版本天花板：模板模式只吃剪映 5.9 及以下（6+ 草稿檔被加密）、批量導出只支援剪映 6 及以下且只能在 Windows 跑、Mac/Linux 只能生草稿不能自動導出、Python 3.13 會踩依賴雷。這篇把安裝、核心 API、模板替換、批量導出，連同這 4 個限制一次講清楚。

📌 目錄

• pyJianYingDraft 是什麼？核心思路
• 為什麼我想試：從手拉時間軸到程式碼產草稿
• 安裝與快速上手
• 核心 API：片段、軌道與時間格式
• 模板模式：複製草稿、替換素材與文本
• 批量導出：JianyingController 與它的硬限制
• 4 個版本天花板總表
• 實際踩過的坑
• 常見問題 FAQ
• 延伸資源

⚡ pyJianYingDraft 是什麼？{#pyjianyingdraft-是什麼}

pyJianYingDraft 是 GitHub 上一個 3.7k star 的開源 Python 庫，作者 GuanYixuan，授權 Apache-2.0。它自己的定位是「輕量、靈活、易上手的 Python 剪映草稿生成及導出工具，構建全自動視頻剪輯/混剪流水線」。

一句話：它不幫你剪片，它幫你「寫出剪片的藍圖」。 你用 Python 描述「哪段素材、放在哪條軌道、什麼時間、加什麼特效」，它產出剪映看得懂的 draft_content.json 草稿檔。你在剪映裡打開那個草稿，時間軸就已經排好了，剩下微調或直接導出。

剪映（JianYing）是抖音母公司字節跳動的影片剪輯軟體，國際版叫 CapCut。如果你的工作是「同一個模板換素材，量產一堆短影片」——電商商品片、Vlog 片頭、字幕影片——這個庫的價值就出來了：把重複的拖拉動作換成一個 for 迴圈。

ℹ️ 作者另外在開發 CapCut 版本（pyCapCut），如果你用的是國際版 CapCut 而非中國版剪映，去看那個倉庫。

🧠 為什麼我想試 {#為什麼我想試}

我自己一開始也以為「剪映就是手動軟體，自動化頂多用按鍵精靈點一點」。直到要做一批字幕影片——同一套版型、20 支片、每支只換背景影片跟一行標題——才發現手拉時間軸這件事本身就是瓶頸：版型再固定，也得一支一支開新專案、拉素材、調時長。

pyJianYingDraft 解決的就是這個「結構固定、內容會變」的場景。它的使用思路很直白：

整條鏈路裡，人只負責寫一次「配方」，剩下交給迴圈。這篇接下來就照這條鏈路走一遍。

💻 安裝與快速上手 {#安裝與快速上手}

前置依賴

⚠️ 不要用 Python 3.13。作者明說 3.13 下 uiautomation（批量導出依賴）會出依賴問題，推薦 3.8、3.10 或 3.11。

一鍵安裝

pip install pyJianYingDraft

PyPI 上的安裝包不含 demo.py 範例，範例要去 GitHub 倉庫拿。

驗證安裝

import pyJianYingDraft as draft
print(draft.__name__)  # 印出 pyJianYingDraft 即安裝成功

最小可跑範例

下面這段建立一個 1920×1080 的草稿，加一段影片片段（截取素材前 4 秒），存成草稿檔：

import pyJianYingDraft as draft
# 用你的剪映草稿資料夾路徑替換 <draft_folder>
# 路徑類似 .../JianyingPro Drafts，可在剪映「全局設置」-「草稿位置」查
script = draft.DraftFolder("<draft_folder>").create_draft("demo", 1920, 1080)
# 建立影片片段：截取素材的前 4 秒
video_segment = draft.VideoSegment("video.mp4", draft.trange("0s", "4s"))
script.add_segment(video_segment)
# 存成剪映草稿檔
script.dump("draft_content.json")

跑完後在剪映裡找到並打開 demo 草稿（可能要先進再退某個已有草稿，或重啟剪映刷新列表），時間軸上就會出現那段 4 秒影片。

ℹ️ 草稿資料夾路徑哪裡找：剪映 → 全局設置 → 草稿位置。記下那串 .../JianyingPro Drafts，後面所有操作都要它。

跨平台能做什麼

⭐ 核心 API {#核心-api}

幾個你一定會碰到的核心類別與函式，先建立心智模型，後面才不會卡。

草稿與資料夾

• DraftFolder("<草稿資料夾>") — 管理整個剪映草稿資料夾，能根據模板生成新草稿
• create_draft("名稱", 寬, 高) — 建立新草稿，回傳一個 ScriptFile 物件
• script.dump("draft_content.json") / script.save() — 把草稿寫回檔案

片段（Segment）

VideoSegment、AudioSegment、TextSegment 是三種主要片段。影片與音訊片段支援兩種建構方式：

import pyJianYingDraft as draft
from pyJianYingDraft import trange
# 方式一：便捷構造（推薦）— 直接傳素材路徑
seg1 = draft.VideoSegment("video.mp4", trange("0s", "4s"))
# 方式二：傳統構造 — 先建素材實例再傳入（需要設定圖像裁剪時用這個）
mat = draft.VideoMaterial("video.mp4")
seg2 = draft.VideoSegment(mat, trange("0s", "4s"))

變速也在建構時設定，用 speed 參數：

# 截取素材前 4×1.25 = 5 秒，但片段在時間軸上仍是 4 秒（被加速）
seg = draft.VideoSegment("video.mp4", trange("0s", "4s"), speed=1.25)

ℹ️ 目前不支援曲線變速，只有整體變速。

時間格式：微秒、字串，與一個必踩的坑

剪映內部用微秒存時間。pyJianYingDraft 同時支援微秒（int）和字串（str，如 "1.5s"、"1h3m12s"）兩種輸入：

from pyJianYingDraft import SEC, tim, trange
# 這幾個相等：1 秒 = 1000000 微秒
assert 1000000 == SEC == tim("1s")
# trange 建立一個 Timerange
assert draft.Timerange(0, 60*SEC) == trange("0s", "1m")

這裡有個最容易踩的坑：trange 的第二個參數是持續時長，不是結束時間。

# 這是「從 0 秒開始，持續 4 秒」（也就是 0~4 秒）
trange("0s", "4s")
# 不是「0 秒到 4 秒」這種直覺解讀——剛好結果一樣，所以新手不會發現
# 但這個就會出事：「從 4 秒開始，持續 1 秒」（4~5 秒），不是「4 秒到 1 秒」
trange("4s", "1s")

如果你照「start, end」的直覺去寫 trange("4s", "10s") 想表達 4~10 秒，實際得到的是「從 4 秒開始持續 10 秒」（4~14 秒）。這個坑作者特別用 ⚠️ 標出來，因為起點 0s 時兩種解讀剛好同值，會讓你誤以為自己懂了。

多軌道

# 加 3 個視訊軌道（倒序，數字越小越上層）
for i in range(3, 0, -1):
    script.add_track(draft.TrackType.video, "%d" % i)
# 把片段加到指定軌道
script.add_segment(seg1, "1").add_segment(seg2, "2")

特效、濾鏡、轉場、動畫、蒙版、混合模式都掛在片段上用對應方法添加，這裡不一一展開，記得「片段是掛載點」這個心智模型即可。

🎨 模板模式 {#模板模式}

這是 pyJianYingDraft 最實用的功能，也是「量產同版型影片」的核心。

思路：在剪映裡先手動做好一個漂亮的草稿當模板（含複雜特效、文字花字、複合片段），然後用程式碼複製它、替換裡面的素材與文字，格式全部保留。

import pyJianYingDraft as draft
draft_folder = draft.DraftFolder("<剪映草稿資料夾>")
# 複製「模板草稿」並命名為「新草稿」，同時打開供編輯
script = draft_folder.duplicate_as_template("模板草稿", "新草稿")
# ... 對 script 做替換 ...
script.save()  # 存檔

三種替換方式

new_material = draft.AudioMaterial("<新音訊路徑>")
script.replace_material_by_name("audio.mp3", new_material)

按片段替換則要先「選軌道」再「替換」，並能處理時長變化：

from pyJianYingDraft import trange, ShrinkMode, ExtendMode
audio_track = script.get_imported_track(draft.TrackType.audio, index=0)
script.replace_material_by_seg(
    audio_track, 0, new_material,
    source_timerange=trange("0s", "10s"),   # 截取新素材前 10 秒
    handle_shrink=ShrinkMode.cut_tail,      # 變短時前移終止點
    handle_extend=ExtendMode.push_tail,     # 變長時後移終止點
)

換文字最直接：

text_track = script.get_imported_track(draft.TrackType.text, index=0)
script.replace_text(text_track, 0, "新文本內容")

⚠️ 模板模式的版本天花板（第 1 道牆）

剪映 6+ 版本對 draft_content.json 進行了加密，所以模板模式目前只支援剪映 5.9 及以下版本。

這是裝之前最該知道的一條。如果你的剪映已經更新到 6 或 7，模板模式直接用不了——載入模板、替換素材這整套功能都吃不到加密後的草稿檔。作者也在倉庫裡公開徵求「6+ 版本草稿檔的解密方式」，意思是這道牆暫時無解，只能降版或鎖在 5.9。

另外，導入的軌道與新建的軌道是分離的：除了上述替換功能，你不能在導入的軌道上加片段、轉場、淡入淡出、特效；但你可以照常新建軌道並在上面操作，就像非模板模式一樣。

📤 批量導出 {#批量導出}

作為自動化流程的最後一步，這個庫提供基礎的草稿批量導出。它不是直接寫影片檔，而是用 UI 自動化去操控剪映軟體本身幫你按導出。

import pyJianYingDraft as draft
from pyJianYingDraft import ExportResolution, ExportFramerate
# 此前需先把剪映打開，並停在目錄頁
ctrl = draft.JianyingController()
# 導出指定名稱的草稿到指定路徑
ctrl.export_draft("要導出的草稿名稱", "<導出路徑>",
                  resolution=ExportResolution.RES_1080P,
                  framerate=ExportFramerate.FR_24)

批量就是套迴圈：

import os
for name in draft_names:
    ctrl.export_draft(name, os.path.join(export_folder, name + ".mp4"))

⚠️ 批量導出的兩道牆（第 2、3 道）

這功能限制最多，務必看清楚：

剪映 7+ 版本隱藏了控件，所以批量導出目前只支援剪映 6 及以下版本。 作者實測通過的是剪映專業版 5.9 和 6.8。

此功能依賴 uiautomation 庫，目前只支援在 Windows 系統下執行。 它會把剪映視窗置頂、控制游標點擊，所以建議在閒時/夜間跑，跑的時候你不能搶滑鼠。

還有一個會讓你陷入死循環的雷：

⚠️ 請確認有導出草稿的權限（不使用 VIP 功能，或已開通 VIP），否則可能卡在死循環。

換句話說，如果你的模板用了 VIP 才有的特效、帳號又沒開 VIP，導出時剪映會跳付費牆，UI 自動化點不過去就無限重試。

⚖️ 4 個版本天花板總表 {#版本天花板總表}

把散在各處的限制收成一張表，這是我認為裝之前最該看的東西：

• 只想生草稿？任何 5.0+ 版本、任何平台都行，沒包袱。
• 要用模板量產？把剪映鎖在 5.9，別讓它自動更新到 6（一更新草稿就加密，模板模式報廢）。
• 要全自動導出？只能 Windows + 剪映 6 及以下。Mac 使用者死心，最後一步得搬到 Windows。

🔧 實際踩過的坑 {#實際踩過的坑}

trange 第二參數不是結束時間

前面講過，這裡再強調一次因為它太容易出事。trange("4s", "1s") 是「4 秒開始、持續 1 秒」，不是「4 到 1 秒」。我第一次寫批次的時候照「start, end」思維算時間軸，所有片段時長全錯，還以為是素材問題查了半天。把第二參數一律當「duration」讀就不會錯。

剪映自動升級把模板模式弄壞

如果你靠模板模式，最大的隱形風險是剪映自動更新。5.9 一旦被升到 6+，草稿檔加密，你的整套模板腳本立刻失效。作者在 issue #115 討論過 5.9 自動升級問題——上生產線前先把剪映的自動更新關掉。

Python 3.13 的 uiautomation 依賴雷

# 3.13 下安裝/執行 uiautomation 可能出現依賴錯誤

作者明確建議用 3.8、3.10 或 3.11（issue #12）。如果你習慣裝最新 Python，這裡會卡住，且錯誤訊息不一定直接指向版本問題。

Mac 上「以為能導出」

Mac 能跑草稿生成跟模板模式，很容易讓人以為導出也能跑。實際上 JianyingController 依賴 Windows-only 的 uiautomation，Mac 上連 import 那段流程都走不通。Mac 的定位是「生草稿的機器」，導出這步要嘛手動、要嘛搬 Windows。

❓ 常見問題 {#常見問題}

Q：pyJianYingDraft 支援 CapCut 國際版嗎？
A：本庫針對中國版剪映。國際版 CapCut 請看作者另一個正在開發的倉庫 pyCapCut。

Q：我的剪映是 7.x，還能用嗎？
A：草稿生成可以（5.0+ 全支援）。但模板模式（6+ 加密）和批量導出（7+ 控件隱藏）都用不了。要完整功能請鎖 5.9。

Q：Mac 可以全自動產片+導出嗎？
A：不行。Mac 只能生草稿和跑模板，導出依賴 Windows-only 的 uiautomation。生出來的草稿最後要拿到 Windows 剪映導出。

Q：怎麼找到剪映的草稿資料夾路徑？
A：剪映 → 全局設置 → 草稿位置，路徑類似 .../JianyingPro Drafts。

Q：批量導出跑到一半卡住不動？
A：先檢查兩件事——剪映版本是否 ≤ 6、帳號是否有導出權限（沒開 VIP 但模板用了 VIP 特效會卡死循環）。另外它會佔用滑鼠，跑的時候別動電腦。

🔗 延伸資源 {#延伸資源}

• pyJianYingDraft GitHub 倉庫 — 完整 README、demo.py、功能清單
• PyPI: pyJianYingDraft — pip install 來源
• pyCapCut（CapCut 國際版，開發中） — 用 CapCut 而非剪映的人看這個
• 作者 Discord 討論伺服器 — 用法與新功能討論
• issue #115：5.9 自動升級問題
• issue #12：Python 版本與 uiautomation 依賴