基于 pyJianYingDraft 库的 AI 自动化草稿生成能力详解
AI-Agent 全栈鹤哥 2026年8月18日 50 次阅读
深入讲解如何利用 pyJianYingDraft 开源库进行剪映草稿的 AI 自动化生成，涵盖从模板导入、JSON 自然语言化、MCP 协议桥接到 Agent 智能决策（时间/位置/节奏）的完整链路，并指出当前库的不足与二次开发方向。
基于 pyJianYingDraft 库的 AI 自动化草稿生成能力详解
作者：AI-Agent 全栈鹤哥
本文深入讲解如何利用 pyJianYingDraft 开源库进行剪映草稿的 AI 自动化生成，涵盖从模板导入、自然语言化、MCP 协议桥接到 Agent 智能决策的完整链路，并指出当前库的不足与二次开发方向。
一、前提条件：源码 draft_content.json 的导入与生成
pyJianYingDraft 的核心原理是直接操作剪映的草稿配置文件 draft_content.json，而非模拟鼠标点击。这意味着所有自动化都发生在文件层面——AI 生成的是 JSON 配置，剪映读取这个 JSON 来渲染视频项目。
1.1 草稿文件结构
剪映的草稿目录通常位于：
Windows: %USERPROFILE%\AppData\Local\JianyingPro\User Data\Projects\com.lveditor.draft\
macOS: ~/Movies/JianyingPro/User Data/Projects/com.lveditor.draft/
每个草稿文件夹中的 draft_content.json 包含以下核心字段：
| 字段 | 说明 |
|---|---|
materials |
所有素材定义（视频、音频、文本、贴纸等），每个素材有唯一 ID |
tracks |
时间轨道列表，每个轨道包含 segments 段落 |
segments |
段落定义，通过 material_id 关联素材，通过 target_timerange 定义时间 |
duration |
整个草稿的总时长（微秒） |
canvas_config |
画布尺寸、背景色等配置 |
关键点：materials 和 tracks 是分离的。素材先在 materials 中注册，然后在 tracks 的 segments 中通过 material_id 引用并设定时间区间。这个设计正是 AI 可以利用的结构化接口。
1.2 pyJianYingDraft 基础安装
pip install pyJianYingDraft
兼容性警告：库目前完美兼容剪映专业版 5.9 及以下版本。剪映 6.0+ 对核心配置文件进行了加密处理，新版本的
draft_content.json不再是纯文本 JSON，需要使用fallback_loader进行解析。这是当前最大的兼容性障碍。
1.3 基本使用模式
from pyJianYingDraft import ScriptFile, DraftFolder, Track, VideoMaterial, AudioMaterial, TextMaterial, tim, trange
# 方式一：从模板创建（推荐用于 AI 自动化）
folder = DraftFolder(r"C:\Users\xxx\AppData\Local\JianyingPro\User Data\Projects\com.lveditor.draft")
script = folder.duplicate_as_template("模板草稿名", "AI生成草稿_001")
# 方式二：创建空白草稿
script = ScriptFile(1920, 1080)
script.set_duration(tim("2m"))
# 添加素材到轨道
video_mat = VideoMaterial(r"C:\videos\intro.mp4")
audio_mat = AudioMaterial(r"C:\audio\bgm.mp3")
text_mat = TextMaterial("欢迎观看")
video_track = script.add_track(Track.Type.video, "主视频轨道")
audio_track = script.add_track(Track.Type.audio, "背景音乐")
text_track = script.add_track(Track.Type.text, "字幕轨道")
script.add_segment(video_mat, video_track, trange("0s", "30s"))
script.add_segment(audio_mat, audio_track, trange("0s", "2m"))
script.add_segment(text_mat, text_track, trange("2s", "8s"))
# 保存草稿
script.dump(r"path\to\draft_folder\draft_content.json")
二、详细流程：从模板导入到 AI 智能生成
第一阶段（A）：导入第三方草稿模板，将 JSON 语言化
这是整个流程的起点，也是最关键的一步。核心思路是：将复杂的 draft_content.json 解析为结构化的自然语言描述，让大模型能够理解并操作。
步骤 1：加载模板草稿
from pyJianYingDraft import DraftFolder, ScriptFile
import json
folder = DraftFolder(r"剪映草稿目录路径")
# 加载已有模板
template_script = folder.load_template("我的模板")
# 如果是新版本剪映（加密草稿），需要 fallback_loader
template_script = folder.load_template("我的模板", fallback_loader=my_custom_loader)
步骤 2：解析 JSON 为自然语言指令
将 draft_content.json 的 tracks 和 materials 解析为人类可读的操作指令列表：
def draft_to_natural_language(script: ScriptFile) -> list[dict]:
"""
将剪映草稿的 JSON 结构转换为自然语言化的操作指令列表。
每条指令描述一个具体的编辑动作。
"""
commands = []
for track in script.tracks:
track_type = track.type # video, audio, text, sticker, effect...
track_name = track.name
for seg in track.segments:
start_time = seg.target_timerange.start / 1_000_000 # 微秒转秒
duration = seg.target_timerange.duration / 1_000_000
end_time = start_time + duration
# 根据 track 类型生成不同的自然语言指令
if track_type == "video":
material = script.get_material(seg.material_id)
commands.append({
"action": "add_video",
"description": f"在 {start_time:.1f}s 处添加视频素材 '{material.file_path}'，持续 {duration:.1f}s",
"params": {
"file_path": material.file_path,
"start": start_time,
"duration": duration,
"track_name": track_name
}
})
elif track_type == "audio":
material = script.get_material(seg.material_id)
commands.append({
"action": "add_audio",
"description": f"在 {start_time:.1f}s 处添加音频 '{material.file_path}'，持续 {duration:.1f}s",
"params": {
"file_path": material.file_path,
"start": start_time,
"duration": duration,
"track_name": track_name
}
})
elif track_type == "text":
material = script.get_material(seg.material_id)
commands.append({
"action": "add_text",
"description": f"在 {start_time:.1f}s 处显示文字 '{material.content}'，持续 {duration:.1f}s",
"params": {
"content": material.content,
"start": start_time,
"duration": duration,
"track_name": track_name
}
})
elif track_type == "sticker":
material = script.get_material(seg.material_id)
commands.append({
"action": "add_sticker",
"description": f"在 {start_time:.1f}s 处添加贴纸 '{material.name}'，持续 {duration:.1f}s",
"params": {
"sticker_id": material.sticker_id,
"start": start_time,
"duration": duration,
"track_name": track_name
}
})
return commands
解析后，模板草稿变成了一组清晰的操作指令，例如：
[
{"action": "add_video", "description": "在 0.0s 处添加视频素材 'intro.mp4'，持续 30.0s"},
{"action": "add_audio", "description": "在 0.0s 处添加音频 'bgm.mp3'，持续 120.0s"},
{"action": "add_text", "description": "在 2.0s 处显示文字 '欢迎观看'，持续 6.0s"},
{"action": "add_sticker", "description": "在 5.0s 处添加贴纸 '点赞'，持续 10.0s"}
]
这就是"将复杂的草稿模板语言化"的核心。 大模型可以直接理解这些指令，并根据用户需求修改、新增或删除操作。
步骤 3：构建 System Prompt 让 AI 理解操作空间
SYSTEM_PROMPT = """你是一个视频剪辑自动化助手。你可以执行以下操作：
1. add_video(file_path, start, duration, track_name) - 添加视频片段
2. add_audio(file_path, start, duration, track_name) - 添加音频（背景音乐、配音等）
3. add_sound_effect(file_path, start, duration, track_name) - 添加音效
4. add_text(content, start, duration, track_name) - 添加文字/字幕
5. add_sticker(sticker_id, start, duration, track_name) - 添加贴纸/表情
6. add_image(file_path, start, duration, track_name) - 添加图片
7. add_transition(track_name, segment_index, transition_type) - 添加转场
8. add_filter(filter_id, track_name, segment_index) - 添加滤镜
时间单位为秒。你可以根据视频内容和节奏，智能决定每个素材的出现时间、持续时长和位置。
当用户描述需求时，请输出一组 JSON 格式的操作指令。
"""
第二阶段（B）：利用 MCP 协议，将语言化指令转换为草稿 JSON
MCP（Model Context Protocol）是连接 AI 模型与外部工具的标准协议。通过将 pyJianYingDraft 的核心方法封装为 MCP Server，大模型可以直接调用这些方法生成草稿。
MCP Server 设计
from mcp.server import Server
from pyJianYingDraft import ScriptFile, Track, VideoMaterial, AudioMaterial, TextMaterial, tim, trange
import json
server = Server("jianying-draft-generator")
# 全局草稿实例
current_draft: ScriptFile | None = None
@server.tool("create_draft")
async def create_draft(width: int, height: int, duration: str) -> str:
"""创建一个新的空白剪映草稿项目。
Args:
width: 视频宽度（像素），如 1920
height: 视频高度（像素），如 1080
duration: 总时长，如 "2m" 或 "120s"
Returns:
成功消息
"""
global current_draft
current_draft = ScriptFile(width, height)
current_draft.set_duration(tim(duration))
return f"草稿已创建，画布 {width}x{height}，时长 {duration}"
@server.tool("add_video")
async def add_video(file_path: str, start: str, duration: str, track_name: str = "主视频") -> str:
"""添加视频素材到草稿。
Args:
file_path: 视频文件路径
start: 开始时间，如 "0s" 或 "1.5s"
duration: 持续时长，如 "30s"
track_name: 轨道名称
"""
global current_draft
video_mat = VideoMaterial(file_path)
track = current_draft.get_track_by_name(track_name) or current_draft.add_track(Track.Type.video, track_name)
current_draft.add_segment(video_mat, track, trange(start, duration))
return f"视频 '{file_path}' 已添加到轨道 '{track_name}'，时间 {start} ~ {start}+{duration}"
@server.tool("add_audio")
async def add_audio(file_path: str, start: str, duration: str, track_name: str = "背景音乐") -> str:
"""添加音频素材到草稿。"""
global current_draft
audio_mat = AudioMaterial(file_path)
track = current_draft.get_track_by_name(track_name) or current_draft.add_track(Track.Type.audio, track_name)
current_draft.add_segment(audio_mat, track, trange(start, duration))
return f"音频 '{file_path}' 已添加到轨道 '{track_name}'，时间 {start} ~ {start}+{duration}"
@server.tool("add_text")
async def add_text(content: str, start: str, duration: str, track_name: str = "字幕") -> str:
"""添加文字到草稿。"""
global current_draft
text_mat = TextMaterial(content)
track = current_draft.get_track_by_name(track_name) or current_draft.add_track(Track.Type.text, track_name)
current_draft.add_segment(text_mat, track, trange(start, duration))
return f"文字 '{content}' 已添加到轨道 '{track_name}'，时间 {start} 持续 {duration}"
@server.tool("add_sticker")
async def add_sticker(sticker_id: str, start: str, duration: str, track_name: str = "贴纸") -> str:
"""添加贴纸到草稿。"""
global current_draft
sticker_mat = StickerMaterial(sticker_id)
track = current_draft.get_track_by_name(track_name) or current_draft.add_track(Track.Type.sticker, track_name)
current_draft.add_segment(sticker_mat, track, trange(start, duration))
return f"贴纸 '{sticker_id}' 已添加到轨道 '{track_name}'，时间 {start} 持续 {duration}"
@server.tool("save_draft")
async def save_draft(output_path: str) -> str:
"""保存草稿到指定路径。"""
global current_draft
current_draft.dump(output_path)
return f"草稿已保存到 {output_path}"
@server.tool("load_template")
async def load_template(template_path: str, new_name: str) -> str:
"""从已有草稿模板创建新草稿。"""
global current_draft
folder = DraftFolder(template_path)
current_draft = folder.duplicate_as_template(template_path, new_name)
return f"已从模板 '{template_path}' 创建新草稿 '{new_name}'"
@server.tool("replace_material_by_name")
async def replace_material(original_name: str, new_file_path: str) -> str:
"""通过素材名称替换模板中的素材。"""
global current_draft
new_mat = VideoMaterial(new_file_path)
current_draft.replace_material_by_name(original_name, new_mat)
return f"素材 '{original_name}' 已替换为 '{new_file_path}'"
MCP Client 调用流程
当用户对 AI 说"帮我做一个产品介绍视频，开头放产品logo图片3秒，然后放产品演示视频30秒，背景配轻音乐，底部加产品名称字幕"时：
用户输入 → LLM 解析意图 → 生成 MCP 工具调用序列 → MCP Server 执行 → 生成 draft_content.json → 剪映打开渲染
LLM 会自动生成类似这样的调用序列：
[
{"tool": "load_template", "args": {"template_path": "产品介绍模板", "new_name": "AI生成_产品介绍_001"}},
{"tool": "replace_material_by_name", "args": {"original_name": "logo_placeholder.png", "new_file_path": "C:/assets/my_logo.png"}},
{"tool": "add_video", "args": {"file_path": "C:/videos/demo.mp4", "start": "3s", "duration": "30s"}},
{"tool": "add_audio", "args": {"file_path": "C:/audio/light_bgm.mp3", "start": "0s", "duration": "33s"}},
{"tool": "add_text", "args": {"content": "智能助手 X1", "start": "3s", "duration": "30s", "track_name": "产品名称"}},
{"tool": "save_draft", "args": {"output_path": "C:/drafts/AI_product_intro/draft_content.json"}}
]
第三阶段（C）：AI Agent 智能决策——时间、位置、节奏的自动化
这是整个方案中最有价值也最需要二次开发的部分。不是简单地让 AI 执行用户指定的操作，而是让 AI 自主决策素材应该出现在什么时间、持续多久、放在哪个轨道。
Agent 设计核心：场景理解与智能排布
一个真正的视频自动化 Agent 需要具备以下决策能力：
# Agent 的决策维度
AGENT_DECISION_DIMENSIONS = {
"时间决策": {
"视频片段何时出现": "根据脚本内容节奏，自动决定每个片段的切入/切出时间",
"字幕何时显示": "根据语音识别结果自动对齐字幕时间码",
"音效何时触发": "根据视频画面变化或脚本节点自动触发音效",
"贴纸何时弹出": "在关键信息出现时自动弹出强调贴纸",
},
"位置决策": {
"人名条位置": "根据画面构图自动判断人名条应该出现在左下/右下/顶部",
"字幕位置": "根据画面是否有底部字幕条自动调整字幕 Y 轴位置",
"贴纸位置": "根据画面留白区域自动选择贴纸放置位置",
"Logo位置": "根据画面安全区域自动选择角落位置",
},
"内容决策": {
"关键词高亮": "AI 分析语音文本，自动识别关键词并放大/变色显示",
"章节分段": "AI 根据内容语义自动划分视频章节，添加章节标题",
"情绪匹配": "根据语音情绪自动选择贴纸类型（开心→笑脸，严肃→感叹号）",
"节奏控制": "根据语音语速自动调整字幕显示时长和切换节奏",
}
}
具体实现示例：智能人名条
@server.tool("smart_add_name_card")
async def smart_add_name_card(
person_name: str,
appearance_time: str,
video_duration: str,
preferred_position: str = "auto"
) -> str:
"""
AI 智能添加人名条。
Agent 会自动决策：
1. 人名条出现的最佳时间（通常在人物首次出现后 0.5-1s）
2. 人名条的位置（根据画面构图自动选择）
3. 人名条的持续时长（通常 3-5s 或与人物镜头等长）
4. 人名条的样式（根据视频整体风格自动匹配）
"""
global current_draft
# AI 决策：位置选择逻辑
if preferred_position == "auto":
# 这里可以接入画面分析模型，判断画面留白区域
# 简化示例：默认右下角
position = "bottom-right"
# AI 决策：持续时长逻辑
duration_sec = 4.0 # 默认 4 秒
# 如果人物镜头 < 4s，则与镜头等长
if tim(video_duration) < tim("4s"):
duration = video_duration
else:
duration = "4s"
# AI 决策：延迟出现逻辑（人物出现后 0.5s 再弹出人名条）
start_time = f"{float(appearance_time.rstrip('s')) + 0.5}s"
# 创建人名条素材
name_card_mat = TextMaterial(person_name)
name_track = current_draft.add_track(Track.Type.text, f"人名条_{person_name}")
current_draft.add_segment(name_card_mat, name_track, trange(start_time, duration))
return f"人名条 '{person_name}' 已智能添加：位置 {position}，时间 {start_time} 持续 {duration}s"
Agent 工作流编排
class VideoEditingAgent:
"""视频剪辑 AI Agent"""
def __init__(self, llm_client, mcp_server):
self.llm = llm_client # 大模型客户端
self.mcp = mcp_server # MCP Server 实例
async def process_request(self, user_input: str, template_path: str = None):
"""
完整的 Agent 处理流程：
1. 理解用户意图
2. 分析可用素材
3. 制定剪辑方案（时间线、轨道分配、素材选择）
4. 通过 MCP 执行操作
5. 验证并优化
"""
# 步骤 1：加载模板（如果提供）
if template_path:
await self.mcp.call("load_template", {
"template_path": template_path,
"new_name": f"AI_Generated_{int(time.time())}"
})
else:
await self.mcp.call("create_draft", {
"width": 1920, "height": 1080, "duration": "5m"
})
# 步骤 2：AI 分析用户意图，生成操作计划
plan = await self.llm.analyze_and_plan(
user_input=user_input,
available_tools=self.mcp.get_tool_list(),
system_prompt=AGENT_SYSTEM_PROMPT
)
# 步骤 3：执行操作序列
for action in plan.actions:
result = await self.mcp.call(action.tool, action.args)
# AI 验证每一步的执行结果
verification = await self.llm.verify_action(action, result)
if not verification.success:
# 自动修正
corrected = await self.llm.correct_action(action, verification.error)
await self.mcp.call(corrected.tool, corrected.args)
# 步骤 4：保存草稿
await self.mcp.call("save_draft", {
"output_path": f"C:/drafts/AI_Generated_{int(time.time())}/draft_content.json"
})
三、pyJianYingDraft 的不足与二次开发方向
当前开源库（v0.3.0）在实际 AI 自动化场景中存在以下关键不足，需要二次开发：
3.1 结构性缺陷
| 问题 | 影响 | 二次开发方向 |
|---|---|---|
| 新版本加密草稿 | 剪映 6.0+ 加密了 draft_content.json，库无法直接读写 |
逆向分析加密格式，开发自定义 fallback_loader；或锁定使用 5.9 版本 |
| 导入轨道隔离 | 从模板导入的轨道无法直接追加新段落或特效 | 修改 import_track 逻辑，支持对导入轨道的增量操作 |
| 复合段落缺失 | 不支持嵌套草稿（compound segments） | 扩展 Segment 类，支持父子层级关系 |
| 内置音效不支持 | 无法添加剪映自带的音效库素材 | 逆向解析音效素材的 material 结构，新增 SoundEffectMaterial 类 |
| 蒙版功能缺失 | 新版剪映的视频蒙版不支持 | 补充 mask 字段的 JSON 结构映射 |
3.2 AI 自动化场景的缺失能力
# 需要二次开发的核心能力清单
class AIEnhancedScriptFile(ScriptFile):
"""二次开发版 ScriptFile，增加 AI 自动化所需能力"""
def smart_layout(self, elements: list, canvas_size: tuple):
"""
智能布局：AI 根据画布尺寸和元素列表，
自动决定每个元素的位置、大小和层级。
原版库不支持位置坐标控制，需要扩展。
"""
# 需要扩展 Segment 的 transform 字段
# 原版库的 add_segment 不支持 x, y, scale 参数
pass
def auto_subtitle_timing(self, audio_file: str):
"""
自动字幕时间对齐：通过语音识别自动生成字幕并对齐时间码。
原版库支持导入 .srt 文件但不支持自动生成。
需要集成 ASR 能力。
"""
pass
def smart_transition(self, track_name: str, transition_type: str = "auto"):
"""
智能转场：AI 根据相邻片段的内容差异自动选择转场类型。
原版库支持手动添加转场但不支持智能选择。
"""
pass
def get_timeline_summary(self) -> str:
"""
获取时间线摘要：将当前草稿的所有轨道、段落、素材
转换为结构化文本，供 AI 上下文理解使用。
原版库缺少这个能力，导致 AI 无法"看到"当前草稿状态。
"""
summary_parts = []
for track in self.tracks:
for seg in track.segments:
mat = self.get_material(seg.material_id)
start_s = seg.target_timerange.start / 1_000_000
dur_s = seg.target_timerange.duration / 1_000_000
summary_parts.append(
f"[{track.name}] {track.type}: "
f"{mat.name} @ {start_s:.1f}s for {dur_s:.1f}s"
)
return "\n".join(summary_parts)
3.3 位置控制能力缺失
这是最关键的问题。当前 pyJianYingDraft 的 add_segment 方法不支持指定素材在画面中的位置（x, y 坐标）和缩放比例。这意味着：
- 无法控制人名条出现在左下角还是右下角
- 无法控制贴纸出现在画面哪个位置
- 无法控制 Logo 的角落位置
剪映的 draft_content.json 中，每个 segment 的 clip 字段下有 transform 字段，包含 x, y, scale 等属性。二次开发需要：
# 需要在 Segment 类中扩展 transform 支持
def add_segment_with_position(
self,
material,
track,
time_range,
position: tuple[float, float] = None, # (x, y) 归一化坐标 0-1
scale: float = 1.0
):
"""
扩展版 add_segment：支持位置和缩放控制
"""
seg = self.add_segment(material, track, time_range)
if position or scale != 1.0:
# 写入 transform 字段
if not hasattr(seg, 'clip'):
seg.clip = {}
if 'transform' not in seg.clip:
seg.clip['transform'] = {}
if position:
seg.clip['transform']['x'] = position[0]
seg.clip['transform']['y'] = position[1]
seg.clip['transform']['scale'] = {
'x': scale,
'y': scale
}
return seg
四、完整工程实践建议
4.1 推荐技术栈
AI 层: GPT-4o / Claude / 通义千问 (支持 MCP 的 LLM)
协议层: MCP Server (Python)
操作层: pyJianYingDraft (二次开发版)
文件层: draft_content.json
渲染层: 剪映专业版 5.9
4.2 工作目录结构
ai-video-agent/
├── mcp_server/
│ ├── __init__.py
│ ├── server.py # MCP Server 主入口
│ ├── tools.py # 工具函数定义
│ └── draft_manager.py # 草稿管理器
├── pyJianYingDraft_enhanced/
│ ├── __init__.py
│ ├── script_file.py # 扩展版 ScriptFile
│ ├── segment.py # 扩展版 Segment（支持位置控制）
│ └── materials.py # 扩展素材类
├── agent/
│ ├── prompts.py # System prompts
│ ├── planner.py # 操作规划器
│ └── executor.py # 操作执行器
├── templates/
│ └── product_intro/ # 模板草稿目录
└── output/
└── drafts/ # 生成的草稿输出目录
4.3 安全注意事项
- 媒体文件路径避免空格和中文字符，防止解析失败
- 写入 JSON 前确保剪映已完全关闭，避免文件锁定
- 使用 try-catch 包裹所有 JSON 操作，防止格式错误导致数据丢失
- 每次生成前备份模板草稿，防止误操作覆盖
五、总结
pyJianYingDraft 为剪映草稿的 AI 自动化提供了基础能力，但要构建真正的 AI Agent 级视频剪辑系统，需要进行以下二次开发：
- 位置控制：扩展 Segment 支持 transform 字段的 x/y/scale
- 状态可视化：新增
get_timeline_summary方法让 AI 理解当前草稿状态 - 新版本兼容：开发
fallback_loader应对加密草稿格式 - 智能能力集成：ASR 字幕对齐、画面构图分析、节奏检测
- 复合段落支持：支持嵌套草稿结构，实现更复杂的编辑场景
核心价值在于：AI 不只是执行用户的指令，而是自主决策素材的时间、位置、内容和节奏。 这才是从"自动化工具"到"AI Agent"的本质跨越。