pyJianYingDraft：用 Python 驾驭剪映，构建全自动视频流水线

pyJianYingDraft 是一个轻量、灵活且功能强大的 Python 库，旨在通过直接操作 剪映专业版 (CapCut PC) 的草稿文件 (draft_content.json)，实现视频剪辑的完全自动化。

• GitHub：https://github.com/GuanYixuan/pyJianYingDraft

无论你是想批量生成营销视频、制作数据可视化报告，还是构建复杂的混剪流水线，pyJianYingDraft 都能让你像写代码一样“剪辑”视频，无需手动打开剪映界面拖拽素材。

核心亮点

• 🐍 纯 Python 驱动：无需模拟鼠标键盘，直接读写工程文件，速度快、稳定性高。
• 🎬 全功能支持：覆盖音视频剪辑、文本字幕、贴纸特效、关键帧动画、蒙版混合模式等核心功能。
• 📝 模板化工作流：支持加载现有草稿作为模板，替换素材或文本，快速复用复杂工程。
• 🤖 自动化导出：(Windows) 结合 UI 自动化技术，实现草稿的批量渲染导出。
• 📹 精细控制：支持微秒级时间控制、曲线变速（部分）、关键帧插值及多轨道层级管理。

⚠️ 版本兼容性提示：

• 草稿生成/编辑：支持剪映 5.0+ (推荐 5.9)。
• 模板加载：仅支持 5.9 及以下 (6.0+ 已加密 draft_content.json)。
• 自动导出：仅支持 6.0 及以下 (7.0+ 隐藏了 UI 控件)，且仅限 Windows。

安装与准备

pip install pyJianYingDraft

环境要求：

• Python 3.8 或 3.11 (推荐，兼容性最佳)
• 已安装 剪映专业版 (Windows/Mac/Linux，但自动导出仅限 Windows)
• 找到剪映草稿文件夹路径 (通常在 文档/JianyingPro Drafts)

快速上手：5 分钟创建第一个自动视频

以下示例将创建一个包含视频、背景音乐、淡入淡出效果、转场和动态字幕的草稿。

import pyJianYingDraft as draft
from pyJianYingDraft import trange, SEC, FontType, TextStyle

# 1. 初始化草稿文件夹管理器
# 替换为你的实际草稿路径
draft_folder = draft.DraftFolder("C:/Users/YourName/Documents/JianyingPro Drafts")

# 2. 创建新草稿 (1920x1080, 30fps)
script = draft_folder.create_draft("AutoGeneratedVideo", 1920, 1080)

# 3. 添加视频轨道并插入片段
video_track = script.add_track(draft.TrackType.video, "MainVideo")
# 截取视频前 10 秒，并添加入场动画
video_seg = draft.VideoSegment("assets/demo.mp4", trange("0s", "10s"))
video_seg.add_animation(draft.IntroType.渐显)
script.add_segment(video_seg, track_name="MainVideo")

# 4. 添加音频轨道并设置淡入淡出
audio_track = script.add_track(draft.TrackType.audio, "BGM")
audio_seg = draft.AudioSegment("assets/bgm.mp3", trange("0s", "10s"))
audio_seg.add_fade("1s", "1s")  # 1 秒淡入，1 秒淡出
audio_seg.volume = 0.5  # 音量调整为 50%
script.add_segment(audio_seg, track_name="BGM")

# 5. 添加动态字幕
text_track = script.add_track(draft.TrackType.text, "Subtitles")
text_seg = draft.TextSegment(
    "欢迎观看自动生成的视频！",
    trange("1s", "4s"),
    font=FontType.文轩体,
    style=TextStyle(size=8.0, color=(1.0, 1.0, 1.0), bold=True)
)
text_seg.add_animation(draft.TextIntro.弹跳)
script.add_segment(text_seg, track_name="Subtitles")

# 6. 添加转场 (在视频片段末尾)
# 注意：转场通常吸附在片段边缘，具体 API 可能随版本微调
# script.add_transition(...) 

# 7. 保存草稿
script.save()

print("✅ 草稿生成成功！请在剪映中刷新并打开 'AutoGeneratedVideo'。")

高级功能详解

1. 模板模式：复用复杂工程

如果你有一个已经调好色调、特效和布局的精美模板，可以直接加载它并替换内容。

# 加载现有草稿作为模板
template = draft_folder.load_template("MyAwesomeTemplate")

# 方法 A: 根据名称替换素材 (适合图片/视频替换)
new_video = draft.VideoMaterial("assets/new_product.mp4")
template.replace_material_by_name("product_placeholder.mp4", new_video)

# 方法 B: 替换文本内容 (保留所有样式和动画)
text_track = template.get_imported_track(draft.TrackType.text, index=0)
template.replace_text(text_track, 0, "新的促销标语！")

# 保存为新草稿
template.save_as("NewPromoVideo")

2. 关键帧与动画

实现复杂的运动效果，如缩放、旋转、透明度变化。

# 创建视频片段
seg = draft.VideoSegment("assets/logo.png", trange("0s", "5s"))

# 添加缩放关键帧：从 0.5 倍放大到 1.0 倍
seg.add_keyframe(draft.KeyframeProperty.scale, "0s", 0.5)
seg.add_keyframe(draft.KeyframeProperty.scale, "5s", 1.0)

# 添加旋转关键帧：旋转 360 度
seg.add_keyframe(draft.KeyframeProperty.rotation, "0s", 0)
seg.add_keyframe(draft.KeyframeProperty.rotation, "5s", 360)

# 添加透明度淡出
seg.add_keyframe(draft.KeyframeProperty.alpha, "4s", 1.0)
seg.add_keyframe(draft.KeyframeProperty.alpha, "5s", 0.0)

3. 特效、滤镜与混合模式

• 混合模式：实现叠加、滤色等效果（需多轨道）。
• 蒙版：线性、圆形、镜面等蒙版。
• 特效/滤镜：支持全息扫描、胶片闪切、原生肤等内置特效。

# 设置混合模式 (滤色)
overlay_seg = draft.VideoSegment("assets/overlay.mp4", trange("0s", "10s"))
overlay_seg.set_mix_mode(draft.MixModeType.滤色)

# 添加蒙版 (线性蒙版，旋转 45 度)
base_seg = draft.VideoSegment("assets/base.mp4", trange("0s", "10s"))
base_seg.add_mask(draft.MaskType.线性, rotation=45, feather=0.2)

# 添加滤镜 (强度 50)
base_seg.add_filter(draft.FilterType.冰雪世界, 50)

4. 批量导出 (Windows Only)

利用 JianyingController 自动控制剪映客户端进行渲染。

from pyJianYingDraft import JianyingController, ExportResolution

# 启动控制器 (需先手动打开剪映并停留在首页)
ctrl = JianyingController()

# 导出单个草稿
ctrl.export_draft(
    "AutoGeneratedVideo", 
    "D:/Exports/final.mp4",
    resolution=ExportResolution.RES_4K,
    framerate=draft.ExportFramerate.FR_60
)

# 批量导出
draft_names = ["Video1", "Video2", "Video3"]
for name in draft_names:
    ctrl.export_draft(name, f"D:/Exports/{name}.mp4")

⚠️ 已知限制与注意事项

1. 加密问题：剪映 6.0+ 对草稿文件进行了加密，导致模板加载功能失效。目前只能从头生成草稿，或手动解密（社区正在研究中）。
2. 导出限制：剪映 7.0+ 隐藏了必要的 UI 控件，导致自动导出功能失效。如需批量导出，请使用 6.0 或更低版本。
3. 跨平台：
   • Windows：支持所有功能（生成 + 导出）。
   • Mac/Linux：仅支持草稿生成。生成的草稿需拷贝到 Windows 机器上或用 Mac 版剪映手动导出。
4. UI 自动化依赖：导出功能依赖 uiautomation 库，运行时请不要干扰鼠标键盘，建议在夜间或闲时运行。

常用资源映射