pyJianYingDraft:用 Python 生成剪映草稿,边界也得一起看

用代码做剪映草稿，最痛快的一刻是几百条字幕一眨眼全进了时间线。最容易扫兴的一刻，是草稿能生成，剪映却打不开，或者能打开，导出还得重新点一遍。

pyJianYingDraft^[1] 是一个 Python 工程库。它能创建剪映草稿，安排视频、音频、图片和文字，也支持动画、特效、滤镜、蒙版、转场和模板替换。

它不只是几段写 JSON 的示例，仓库里有类型定义、素材类、轨道逻辑、模板模式和测试。与此同时，剪映版本、操作系统和自动导出都有明确限制。两面都看，才知道它能省哪一段工作。

1. 草稿生成的四层关系

用它加一段视频，代码大概会写成这样：

script = draft.Script_file(1920, 1080)
script.add_track(draft.Track_type.video)

material = draft.Video_material("demo.mp4")
segment = draft.Video_segment(
    material,
    target_timerange=draft.trange("0s", "8s")
)

script.add_segment(segment)
script.dump("draft_content.json")

这里有四层东西：

文件：demo.mp4
素材 material：记录路径、时长、尺寸等元数据
片段 segment：从素材取哪一段，放到什么时间
轨道 track：多个片段在同一条时间线上的排列

最后 Script_file 把这些对象写成剪映草稿。

这个对象模型很重要。你不用在业务代码里记住剪映每个 UUID 应该落在哪个 JSON 数组，也不用手工维护素材和片段之间的引用。

2. 时间单位是微秒，trange 第二项是时长

视频自动化里，时间错误比视觉问题更常见，也更难一眼发现。

pyJianYingDraft 内部使用微秒。它提供 tim 和 trange 帮你写秒、帧或字符串时间。这里有一个很容易看错的地方：

trange("2s", "5s")

表示从第 2 秒开始，持续 5 秒，并不是从第 2 秒到第 5 秒。

如果上游给的是字幕起止时间，就要先计算 duration：

duration = end - start

把 end 直接当第二个参数，越到后面的片段，时间线错得越厉害。

3. 动画、转场和字幕怎么接上

视频片段创建以后，可以继续添加入场、出场或组合动画，也能在片段之间加转场。

文字部分可以直接设置字体、字号、颜色、位置和动画，也能读 SRT 批量生成字幕。音频片段支持淡入淡出和音效，视频还包括关键帧、蒙版、色度抠图、混合和背景等能力。

这些功能不是 AI 在聊天里描述出来的。仓库用枚举和素材类把剪映里的效果映射成 Python 对象，再由序列化代码写进草稿。

不过，效果名称最终仍受剪映版本约束。某个转场在旧版存在，不代表新版草稿结构完全一样。自动化脚本要跟着实际安装版本做回归测试。

4. 模板模式比“从空白开始”更实用

如果每条视频版式相同，只替换标题、口播和几张图，从头搭时间线并不划算。

pyJianYingDraft 可以读取已有剪映草稿，把里面的素材或文字替换掉，也能导入轨道。实际用法更像：

先在剪映里做一份审美过关的模板
→ 给需要替换的文字和素材命名
→ Python 按业务数据替换
→ 保存成一份新草稿
→ 人在剪映里检查和导出

这条路通常比“让代码负责所有排版”稳。代码擅长重复，剪映擅长人工微调，两边各干自己顺手的事。

5. 自动导出的限制要提前知道

仓库提供了批量导出相关能力，但它不是所有系统、所有剪映版本都能用。

当前说明里，自动导出主要依赖 Windows 的 uiautomation，而且适配剪映 6 及以下。剪映 7 以后，一些控件不再以同样方式暴露，自动点击导出的方案不能照旧使用。

macOS 和 Linux 可以生成草稿，最终导出仍要回到装有剪映的 Windows 环境，或者由人手动完成。

另外，新版剪映的草稿不总是明文 draft_content.json。模板读取可能需要仓库提供的 fallback loader。仓库列出的 10.8 测试也有局部功能限制，例如蒙版。

“兼容性一般”概括不了这些差异。要做生产流程，先锁定剪映版本和导出环境。

公开 issues 里已经有人遇到过剪映 10.3 的 macOS 草稿提示损坏^[2]，也有人报告转场在剪映和导出视频里都没有显示^[3]。这不等于库一定有同一个 bug，却能说明版本测试不能省。自己的剪映版本、系统和效果组合，必须先拿短草稿试过。

6. 怎么用

仓库地址：

https://github.com/GuanYixuan/pyJianYingDraft

它不是现成的 Agent Skill。可以把仓库交给 AI，让它按实际版本生成项目脚本：

请阅读 GuanYixuan/pyJianYingDraft。

我的剪映版本是 5.9，系统是 Windows。
根据 videos.csv 和 captions.srt 生成 1920×1080 草稿。
片段不能重叠，转场只使用仓库当前已有的枚举。

先生成 20 秒测试草稿，检查能否打开，再扩到全部视频。

如果使用模板，还要把模板草稿和要替换的素材名称一起给 AI。

7. 如果自己做一个 Skill

Skill 不该只写“调用 pyJianYingDraft 生成视频”。至少要管住这些输入：

剪映版本与系统
画布尺寸和帧率
素材真实路径、时长、尺寸
轨道顺序和重叠规则
字幕样式
允许使用的动画、转场和滤镜
模板路径
导出方式

执行时先做 20 秒的小草稿。打开成功、素材不离线、字幕时间正确，再生成完整项目。完成后再解析一次草稿，检查每个 segment 引用的 material 是否存在，时间范围有没有超出素材长度。

8. 我的判断

pyJianYingDraft 更适合固定模板、批量口播、课程切片和字幕量很大的项目。它能把重复的时间线操作交给 Python，又保留剪映里的人工调整。

它不适合被宣传成“一句话全自动出片”。草稿格式跟着剪映变，自动导出又受系统和版本影响。程序写完草稿以后，仍需要一次真实打开和预览。

接受这些边界以后，它依然能省下几百次重复拖拽。成片最后看起来怎样，还是得有人打开剪映检查。