核心功能特性

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排查指南
9. 结论

简介

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 与强健的参数校验
• 丰富的媒体与效果装配能力
• 异步渲染与可选自动化导出
• 良好的扩展性与可维护性

建议在生产环境中结合任务队列与监控体系，进一步提升稳定性与可观测性。