核心功能特性
目录
简介
capcut-mate 是一个面向 CapCut（剪映）的自动化脚本与 API 平台，提供草稿管理、媒体处理、编辑效果系统与视频生成流程的完整能力。通过标准化的 REST API，用户可以快速创建草稿、批量添加视频/音频/图片/字幕/特效，以及异步生成视频。项目采用 FastAPI 提供接口，结合本地草稿缓存与剪映自动化控制，实现从“素材装配”到“云端渲染”的端到端工作流。
项目结构
项目采用分层架构：
- 接口层：FastAPI 路由与请求/响应模型
- 业务层：各功能模块的服务实现（service）
- 工具层：媒体工具、下载器、任务管理器、日志等
- 草稿引擎层：基于 pyJianYingDraft 的草稿读写与片段装配
- 自动化层：剪映窗口控制与导出流程
graph TB
Client["客户端/调用方"] --> API["FastAPI 接口层<br/>src/router/v1.py"]
API --> Service["业务服务层<br/>src/service/*.py"]
Service --> Draft["草稿引擎<br/>pyJianYingDraft"]
Service --> Utils["工具层<br/>下载/媒体/任务管理"]
Service --> Config["配置中心<br/>config.py"]
Service --> Controller["剪映自动化<br/>jianying_controller.py"]
核心组件
- 草稿管理系统：创建/保存/获取草稿，维护草稿缓存与持久化
- 媒体处理功能：批量添加视频/音频/图片，支持时长/转场/遮罩/动画等参数
- 编辑效果系统：字幕样式与动画、特效叠加、关键帧与遮罩
- 视频生成流程：异步提交渲染任务、查询状态、导出与下载
架构总览
CapCut Mate 的整体流程：客户端通过 API 发起请求 → FastAPI 路由接收 → 业务服务处理 → 草稿引擎装配片段 → 任务管理器异步渲染 → 剪映自动化导出（可选）。
sequenceDiagram
participant C as "客户端"
participant R as "路由层"
participant S as "服务层"
participant D as "草稿引擎"
participant Q as "任务管理器"
participant J as "剪映自动化"
C->>R : 请求如添加视频/生成视频
R->>S : 参数校验与转发
S->>D : 读取/写入草稿、装配片段
S->>Q : 提交渲染任务异步
Q-->>S : 返回任务状态
S-->>R : 响应结果
R-->>C : 返回草稿URL/任务ID/状态
S->>J : 导出可选
J-->>S : 导出完成
详细组件分析
草稿管理系统
- 能力概述
- 创建草稿：复制模板目录，设置画布尺寸，初始化主轨道
- 保存草稿：更新缓存并返回可访问的草稿URL
- 获取草稿：列出草稿内文件清单
- 实现要点
- 使用模板 default，启用双文件兼容模式，确保草稿内容与元信息一致
- 通过缓存管理草稿生命周期，避免重复IO
- 使用场景
- 批量素材装配前的“画布准备”
- 多轮编辑后的“草稿归档与分享”
flowchart TD
Start(["创建草稿"]) --> CopyTpl["复制模板目录"]
CopyTpl --> LoadScript["加载草稿脚本"]
LoadScript --> SetCanvas["设置画布尺寸"]
SetCanvas --> AddTrack["添加主视频轨道"]
AddTrack --> SaveDraft["保存草稿"]
SaveDraft --> Cache["更新缓存"]
Cache --> End(["返回草稿URL"])
媒体处理功能
视频装配（批量添加视频）
- 能力概述
- 支持多段视频按时间轴拼接，设置透明度、缩放、位移
- 支持转场效果与遮罩类型
- 实现要点
- 下载视频至草稿资源目录，解析时长与尺寸
- 构造 VideoSegment，设置目标/源时间范围与播放速度
- 自动创建非主轨道，避免与主轨道冲突
- 使用场景
- 多片段拼接、背景音乐配合画面
- 与音频/图片/字幕共同组成完整叙事
sequenceDiagram
participant API as "API"
participant S as "add_videos"
participant DL as "下载器"
participant D as "草稿引擎"
API->>S : 草稿URL + 视频信息
S->>DL : 下载视频文件
S->>D : 创建VideoSegment并添加到轨道
D-->>S : 返回segment_id与track_id
S-->>API : 返回结果
音频装配（批量添加音频）
- 能力概述
- 支持多段音频拼接，自动处理重叠与越界
- 可选音频效果（如混响/均衡等）
- 实现要点
- 下载音频并检测实际时长，智能修正 end/start 与 segment_duration
- 若添加失败且提示重叠，逐步微调起始时间以规避冲突
- 使用场景
- 配乐叠加、旁白配音、多轨音效合成
图片装配（批量添加图片）
- 能力概述
- 支持入场/出场/循环动画，转场效果与时长
- 按像素级位移与缩放控制
- 实现要点
- 图片使用 VideoSegment 表达，便于应用动画与转场
- 转场时长限制在 100000–2500000 微秒范围内
- 使用场景
- 片头片尾、图文卡片、动态字幕背景
字幕系统（批量添加字幕）
- 能力概述
- 支持文本样式（颜色、透明度、对齐、字体、描边、阴影）
- 支持关键词高亮与多种动画（入场/出场/循环）
- 实现要点
- TextStyle 统一管理字体、颜色、间距等属性
- 关键词高亮通过 extra_styles 注入，避免全局污染
- 动画映射到 TextIntro/TextOutro/TextLoopAnim
- 使用场景
- 字幕对齐原声音轨、强调关键词、营造视觉节奏
特效系统（批量添加特效）
- 能力概述
- 支持场景特效与角色特效，按时间范围叠加
- 实现要点
- 通过 effect_title 查找 VideoSceneEffectType 或 VideoCharacterEffectType
- 创建 EffectSegment 并添加到特效轨道
- 使用场景
- 特写转场、氛围渲染、品牌风格化
视频生成流程
- 能力概述
- 异步提交渲染任务，支持 API Key 校验与积分检查
- 查询任务状态，支持草稿URL解析与任务绑定
- 实现要点
- 任务管理器负责排队与调度
- 可选剪映自动化导出（导出窗口识别、分辨率/帧率设置、等待完成）
- 使用场景
- 批量生成成品视频，云端渲染与本地导出结合
sequenceDiagram
participant U as "用户"
participant API as "gen_video"
participant TM as "任务管理器"
participant J as "剪映自动化"
U->>API : 提交草稿URL + apiKey
API->>TM : submit_task(draft_url, apiKey)
TM-->>API : 返回任务状态
API-->>U : 返回任务已提交
API->>J : 可选：触发导出流程
J-->>API : 导出完成
媒体工具与辅助能力
- 媒体时长探测：基于 ffprobe 获取音视频时长（微秒），支持超时与格式化输出
- URL参数解析：从草稿URL中提取 draft_id
- 剪映自动化：窗口识别、导出路径获取、分辨率/帧率设置、等待导出完成
依赖关系分析
- 路由层依赖服务层；服务层依赖草稿引擎与工具层；配置中心贯穿全局
- 任务管理器与剪映自动化为可选集成点，不影响核心装配流程
graph LR
Router["路由层<br/>src/router/v1.py"] --> Service["服务层<br/>src/service/*.py"]
Service --> Draft["草稿引擎<br/>pyJianYingDraft"]
Service --> Utils["工具层<br/>下载/媒体/任务管理"]
Service --> Config["配置中心<br/>config.py"]
Service --> Controller["剪映自动化<br/>jianying_controller.py"]
性能考虑
- 草稿缓存：通过内存缓存减少重复读写，提高批量装配效率
- 异步渲染：视频生成采用任务队列，避免阻塞接口响应
- 资源复用：同一草稿内素材（视频/音频/图片）共享资源目录，减少IO
- 时间范围优化：音频/视频片段时长与边界智能修正，降低重叠与回退成本
故障排查指南
- 草稿URL无效
- 现象：抛出 INVALID_DRAFT_URL
- 排查：确认 draft_id 存在且在缓存中；检查草稿URL格式
- 资源下载失败
- 现象：下载器异常或 ffprobe 超时
- 排查：检查网络连通性、URL有效性、磁盘空间
- 片段重叠
- 现象：添加片段时报重叠错误
- 排查：微调 start/end 或使用服务层自动偏移策略
- API Key 校验失败
- 现象：INVALID_APIKEY 或 INSUFFICIENT_ACCOUNT_BALANCE
- 排查：确认 apiKey 格式与余额
结论
capcut-mate 通过清晰的分层设计与完善的业务服务，实现了从“草稿装配”到“视频生成”的高效闭环。其核心优势在于：
- 标准化 API 与强健的参数校验
- 丰富的媒体与效果装配能力
- 异步渲染与可选自动化导出
- 良好的扩展性与可维护性
建议在生产环境中结合任务队列与监控体系，进一步提升稳定性与可观测性。
