【开源剪映小助手】核心功能特性

Hommy882026-06-05 18:07

核心功能特性

目录

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

简介

capcut-mate 是一个面向 CapCut（剪映）的自动化脚本与 API 平台，提供草稿管理、媒体处理、编辑效果系统与视频生成流程的完整能力。通过标准化的 REST API，用户可以快速创建草稿、批量添加视频/音频/图片/字幕/特效，以及异步生成视频。项目采用 FastAPI 提供接口，结合本地草稿缓存与剪映自动化控制，实现从"素材装配"到"云端渲染"的端到端工作流。

项目结构

项目采用分层架构：

  • 接口层：FastAPI 路由与请求/响应模型
  • 业务层：各功能模块的服务实现（service）
  • 工具层：媒体工具、下载器、任务管理器、日志等
  • 草稿引擎层：基于 pyJianYingDraft 的草稿读写与片段装配
  • 自动化层：剪映窗口控制与导出流程

#mermaid-svg-xpABi7G5x6ZZaBpu{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-xpABi7G5x6ZZaBpu .error-icon{fill:#552222;}#mermaid-svg-xpABi7G5x6ZZaBpu .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-xpABi7G5x6ZZaBpu .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-xpABi7G5x6ZZaBpu .marker{fill:#333333;stroke:#333333;}#mermaid-svg-xpABi7G5x6ZZaBpu .marker.cross{stroke:#333333;}#mermaid-svg-xpABi7G5x6ZZaBpu svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-xpABi7G5x6ZZaBpu p{margin:0;}#mermaid-svg-xpABi7G5x6ZZaBpu .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu .cluster-label text{fill:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu .cluster-label span{color:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu .cluster-label span p{background-color:transparent;}#mermaid-svg-xpABi7G5x6ZZaBpu .label text,#mermaid-svg-xpABi7G5x6ZZaBpu span{fill:#333;color:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu .node rect,#mermaid-svg-xpABi7G5x6ZZaBpu .node circle,#mermaid-svg-xpABi7G5x6ZZaBpu .node ellipse,#mermaid-svg-xpABi7G5x6ZZaBpu .node polygon,#mermaid-svg-xpABi7G5x6ZZaBpu .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-xpABi7G5x6ZZaBpu .rough-node .label text,#mermaid-svg-xpABi7G5x6ZZaBpu .node .label text,#mermaid-svg-xpABi7G5x6ZZaBpu .image-shape .label,#mermaid-svg-xpABi7G5x6ZZaBpu .icon-shape .label{text-anchor:middle;}#mermaid-svg-xpABi7G5x6ZZaBpu .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-xpABi7G5x6ZZaBpu .rough-node .label,#mermaid-svg-xpABi7G5x6ZZaBpu .node .label,#mermaid-svg-xpABi7G5x6ZZaBpu .image-shape .label,#mermaid-svg-xpABi7G5x6ZZaBpu .icon-shape .label{text-align:center;}#mermaid-svg-xpABi7G5x6ZZaBpu .node.clickable{cursor:pointer;}#mermaid-svg-xpABi7G5x6ZZaBpu .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-xpABi7G5x6ZZaBpu .arrowheadPath{fill:#333333;}#mermaid-svg-xpABi7G5x6ZZaBpu .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-xpABi7G5x6ZZaBpu .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-xpABi7G5x6ZZaBpu .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-xpABi7G5x6ZZaBpu .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-xpABi7G5x6ZZaBpu .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-xpABi7G5x6ZZaBpu .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-xpABi7G5x6ZZaBpu .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-xpABi7G5x6ZZaBpu .cluster text{fill:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu .cluster span{color:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-xpABi7G5x6ZZaBpu .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-xpABi7G5x6ZZaBpu rect.text{fill:none;stroke-width:0;}#mermaid-svg-xpABi7G5x6ZZaBpu .icon-shape,#mermaid-svg-xpABi7G5x6ZZaBpu .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-xpABi7G5x6ZZaBpu .icon-shape p,#mermaid-svg-xpABi7G5x6ZZaBpu .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-xpABi7G5x6ZZaBpu .icon-shape .label rect,#mermaid-svg-xpABi7G5x6ZZaBpu .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-xpABi7G5x6ZZaBpu .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-xpABi7G5x6ZZaBpu .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-xpABi7G5x6ZZaBpu :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 客户端/调用方
FastAPI 接口层

src/router/v1.py
业务服务层

src/service/*.py
草稿引擎

pyJianYingDraft
工具层

下载/媒体/任务管理
配置中心

config.py
剪映自动化

jianying_controller.py

核心组件

  • 草稿管理系统：创建/保存/获取草稿，维护草稿缓存与持久化
  • 媒体处理功能：批量添加视频/音频/图片，支持时长/转场/遮罩/动画等参数
  • 编辑效果系统：字幕样式与动画、特效叠加、关键帧与遮罩
  • 视频生成流程：异步提交渲染任务、查询状态、导出与下载

架构总览

CapCut Mate 的整体流程：客户端通过 API 发起请求 → FastAPI 路由接收 → 业务服务处理 → 草稿引擎装配片段 → 任务管理器异步渲染 → 剪映自动化导出（可选）。
"剪映自动化" "任务管理器" "草稿引擎" "服务层" "路由层" "客户端" "剪映自动化" "任务管理器" "草稿引擎" "服务层" "路由层" "客户端" #mermaid-svg-3uVz7iZTb8pZSrpS{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-3uVz7iZTb8pZSrpS .error-icon{fill:#552222;}#mermaid-svg-3uVz7iZTb8pZSrpS .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-3uVz7iZTb8pZSrpS .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-3uVz7iZTb8pZSrpS .marker{fill:#333333;stroke:#333333;}#mermaid-svg-3uVz7iZTb8pZSrpS .marker.cross{stroke:#333333;}#mermaid-svg-3uVz7iZTb8pZSrpS svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-3uVz7iZTb8pZSrpS p{margin:0;}#mermaid-svg-3uVz7iZTb8pZSrpS .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-3uVz7iZTb8pZSrpS text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-3uVz7iZTb8pZSrpS .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-3uVz7iZTb8pZSrpS .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-3uVz7iZTb8pZSrpS #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-3uVz7iZTb8pZSrpS .sequenceNumber{fill:white;}#mermaid-svg-3uVz7iZTb8pZSrpS #sequencenumber{fill:#333;}#mermaid-svg-3uVz7iZTb8pZSrpS #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-3uVz7iZTb8pZSrpS .messageText{fill:#333;stroke:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-3uVz7iZTb8pZSrpS .labelText,#mermaid-svg-3uVz7iZTb8pZSrpS .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .loopText,#mermaid-svg-3uVz7iZTb8pZSrpS .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-3uVz7iZTb8pZSrpS .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-3uVz7iZTb8pZSrpS .noteText,#mermaid-svg-3uVz7iZTb8pZSrpS .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-3uVz7iZTb8pZSrpS .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-3uVz7iZTb8pZSrpS .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-3uVz7iZTb8pZSrpS .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-3uVz7iZTb8pZSrpS .actorPopupMenu{position:absolute;}#mermaid-svg-3uVz7iZTb8pZSrpS .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-3uVz7iZTb8pZSrpS .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-3uVz7iZTb8pZSrpS .actor-man circle,#mermaid-svg-3uVz7iZTb8pZSrpS line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-3uVz7iZTb8pZSrpS :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 请求如添加视频/生成视频 参数校验与转发 读取/写入草稿、装配片段 提交渲染任务异步 返回任务状态 响应结果 返回草稿URL/任务ID/状态 导出可选 导出完成

详细组件分析

草稿管理系统

  • 能力概述
    • 创建草稿：复制模板目录，设置画布尺寸，初始化主轨道
    • 保存草稿：更新缓存并返回可访问的草稿URL
    • 获取草稿：列出草稿内文件清单
  • 实现要点
    • 使用模板 default，启用双文件兼容模式，确保草稿内容与元信息一致
    • 通过缓存管理草稿生命周期，避免重复IO
  • 使用场景
    • 批量素材装配前的"画布准备"
    • 多轮编辑后的"草稿归档与分享"

#mermaid-svg-X1Lk3sJhybx5VoLa{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-X1Lk3sJhybx5VoLa .error-icon{fill:#552222;}#mermaid-svg-X1Lk3sJhybx5VoLa .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-X1Lk3sJhybx5VoLa .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-X1Lk3sJhybx5VoLa .marker{fill:#333333;stroke:#333333;}#mermaid-svg-X1Lk3sJhybx5VoLa .marker.cross{stroke:#333333;}#mermaid-svg-X1Lk3sJhybx5VoLa svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-X1Lk3sJhybx5VoLa p{margin:0;}#mermaid-svg-X1Lk3sJhybx5VoLa .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa .cluster-label text{fill:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa .cluster-label span{color:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa .cluster-label span p{background-color:transparent;}#mermaid-svg-X1Lk3sJhybx5VoLa .label text,#mermaid-svg-X1Lk3sJhybx5VoLa span{fill:#333;color:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa .node rect,#mermaid-svg-X1Lk3sJhybx5VoLa .node circle,#mermaid-svg-X1Lk3sJhybx5VoLa .node ellipse,#mermaid-svg-X1Lk3sJhybx5VoLa .node polygon,#mermaid-svg-X1Lk3sJhybx5VoLa .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-X1Lk3sJhybx5VoLa .rough-node .label text,#mermaid-svg-X1Lk3sJhybx5VoLa .node .label text,#mermaid-svg-X1Lk3sJhybx5VoLa .image-shape .label,#mermaid-svg-X1Lk3sJhybx5VoLa .icon-shape .label{text-anchor:middle;}#mermaid-svg-X1Lk3sJhybx5VoLa .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-X1Lk3sJhybx5VoLa .rough-node .label,#mermaid-svg-X1Lk3sJhybx5VoLa .node .label,#mermaid-svg-X1Lk3sJhybx5VoLa .image-shape .label,#mermaid-svg-X1Lk3sJhybx5VoLa .icon-shape .label{text-align:center;}#mermaid-svg-X1Lk3sJhybx5VoLa .node.clickable{cursor:pointer;}#mermaid-svg-X1Lk3sJhybx5VoLa .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-X1Lk3sJhybx5VoLa .arrowheadPath{fill:#333333;}#mermaid-svg-X1Lk3sJhybx5VoLa .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-X1Lk3sJhybx5VoLa .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-X1Lk3sJhybx5VoLa .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-X1Lk3sJhybx5VoLa .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-X1Lk3sJhybx5VoLa .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-X1Lk3sJhybx5VoLa .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-X1Lk3sJhybx5VoLa .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-X1Lk3sJhybx5VoLa .cluster text{fill:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa .cluster span{color:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-X1Lk3sJhybx5VoLa .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-X1Lk3sJhybx5VoLa rect.text{fill:none;stroke-width:0;}#mermaid-svg-X1Lk3sJhybx5VoLa .icon-shape,#mermaid-svg-X1Lk3sJhybx5VoLa .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-X1Lk3sJhybx5VoLa .icon-shape p,#mermaid-svg-X1Lk3sJhybx5VoLa .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-X1Lk3sJhybx5VoLa .icon-shape .label rect,#mermaid-svg-X1Lk3sJhybx5VoLa .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-X1Lk3sJhybx5VoLa .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-X1Lk3sJhybx5VoLa .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-X1Lk3sJhybx5VoLa :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 创建草稿
复制模板目录
加载草稿脚本
设置画布尺寸
添加主视频轨道
保存草稿
更新缓存
返回草稿URL

媒体处理功能

视频装配（批量添加视频）
  • 能力概述
    • 支持多段视频按时间轴拼接，设置透明度、缩放、位移
    • 支持转场效果与遮罩类型
  • 实现要点
    • 下载视频至草稿资源目录，解析时长与尺寸
    • 构造 VideoSegment，设置目标/源时间范围与播放速度
    • 自动创建非主轨道，避免与主轨道冲突
  • 使用场景
    • 多片段拼接、背景音乐配合画面
    • 与音频/图片/字幕共同组成完整叙事

"草稿引擎" "下载器" "add_videos" "API" "草稿引擎" "下载器" "add_videos" "API" #mermaid-svg-BqbtGlbICqsDJNu2{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-BqbtGlbICqsDJNu2 .error-icon{fill:#552222;}#mermaid-svg-BqbtGlbICqsDJNu2 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-BqbtGlbICqsDJNu2 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-BqbtGlbICqsDJNu2 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-BqbtGlbICqsDJNu2 .marker.cross{stroke:#333333;}#mermaid-svg-BqbtGlbICqsDJNu2 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-BqbtGlbICqsDJNu2 p{margin:0;}#mermaid-svg-BqbtGlbICqsDJNu2 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-BqbtGlbICqsDJNu2 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-BqbtGlbICqsDJNu2 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-BqbtGlbICqsDJNu2 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-BqbtGlbICqsDJNu2 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-BqbtGlbICqsDJNu2 .sequenceNumber{fill:white;}#mermaid-svg-BqbtGlbICqsDJNu2 #sequencenumber{fill:#333;}#mermaid-svg-BqbtGlbICqsDJNu2 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-BqbtGlbICqsDJNu2 .messageText{fill:#333;stroke:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-BqbtGlbICqsDJNu2 .labelText,#mermaid-svg-BqbtGlbICqsDJNu2 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .loopText,#mermaid-svg-BqbtGlbICqsDJNu2 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-BqbtGlbICqsDJNu2 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-BqbtGlbICqsDJNu2 .noteText,#mermaid-svg-BqbtGlbICqsDJNu2 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-BqbtGlbICqsDJNu2 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-BqbtGlbICqsDJNu2 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-BqbtGlbICqsDJNu2 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-BqbtGlbICqsDJNu2 .actorPopupMenu{position:absolute;}#mermaid-svg-BqbtGlbICqsDJNu2 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-BqbtGlbICqsDJNu2 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-BqbtGlbICqsDJNu2 .actor-man circle,#mermaid-svg-BqbtGlbICqsDJNu2 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-BqbtGlbICqsDJNu2 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 草稿URL + 视频信息 下载视频文件 创建VideoSegment并添加到轨道 返回segment_id与track_id 返回结果

音频装配（批量添加音频）
  • 能力概述
    • 支持多段音频拼接，自动处理重叠与越界
    • 可选音频效果（如混响/均衡等）
  • 实现要点
    • 下载音频并检测实际时长，智能修正 end/start 与 segment_duration
    • 若添加失败且提示重叠，逐步微调起始时间以规避冲突
  • 使用场景
    • 配乐叠加、旁白配音、多轨音效合成
图片装配（批量添加图片）
  • 能力概述
    • 支持入场/出场/循环动画，转场效果与时长
    • 按像素级位移与缩放控制
  • 实现要点
    • 图片使用 VideoSegment 表达，便于应用动画与转场
    • 转场时长限制在 100000--2500000 微秒范围内
  • 使用场景
    • 片头片尾、图文卡片、动态字幕背景
字幕系统（批量添加字幕）
  • 能力概述
    • 支持文本样式（颜色、透明度、对齐、字体、描边、阴影）
    • 支持关键词高亮与多种动画（入场/出场/循环）
  • 实现要点
    • TextStyle 统一管理字体、颜色、间距等属性
    • 关键词高亮通过 extra_styles 注入，避免全局污染
    • 动画映射到 TextIntro/TextOutro/TextLoopAnim
  • 使用场景
    • 字幕对齐原声音轨、强调关键词、营造视觉节奏
特效系统（批量添加特效）
  • 能力概述
    • 支持场景特效与角色特效，按时间范围叠加
  • 实现要点
    • 通过 effect_title 查找 VideoSceneEffectType 或 VideoCharacterEffectType
    • 创建 EffectSegment 并添加到特效轨道
  • 使用场景
    • 特写转场、氛围渲染、品牌风格化

视频生成流程

  • 能力概述
    • 异步提交渲染任务，支持 API Key 校验与积分检查
    • 查询任务状态，支持草稿URL解析与任务绑定
  • 实现要点
    • 任务管理器负责排队与调度
    • 可选剪映自动化导出（导出窗口识别、分辨率/帧率设置、等待完成）
  • 使用场景
    • 批量生成成品视频，云端渲染与本地导出结合

"剪映自动化" "任务管理器" "gen_video" "用户" "剪映自动化" "任务管理器" "gen_video" "用户" #mermaid-svg-08zxLSVJb0wlyhDD{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-08zxLSVJb0wlyhDD .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-08zxLSVJb0wlyhDD .error-icon{fill:#552222;}#mermaid-svg-08zxLSVJb0wlyhDD .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-08zxLSVJb0wlyhDD .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-08zxLSVJb0wlyhDD .marker{fill:#333333;stroke:#333333;}#mermaid-svg-08zxLSVJb0wlyhDD .marker.cross{stroke:#333333;}#mermaid-svg-08zxLSVJb0wlyhDD svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-08zxLSVJb0wlyhDD p{margin:0;}#mermaid-svg-08zxLSVJb0wlyhDD .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-08zxLSVJb0wlyhDD text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-08zxLSVJb0wlyhDD .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-08zxLSVJb0wlyhDD .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-08zxLSVJb0wlyhDD .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-08zxLSVJb0wlyhDD .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-08zxLSVJb0wlyhDD #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-08zxLSVJb0wlyhDD .sequenceNumber{fill:white;}#mermaid-svg-08zxLSVJb0wlyhDD #sequencenumber{fill:#333;}#mermaid-svg-08zxLSVJb0wlyhDD #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-08zxLSVJb0wlyhDD .messageText{fill:#333;stroke:none;}#mermaid-svg-08zxLSVJb0wlyhDD .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-08zxLSVJb0wlyhDD .labelText,#mermaid-svg-08zxLSVJb0wlyhDD .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-08zxLSVJb0wlyhDD .loopText,#mermaid-svg-08zxLSVJb0wlyhDD .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-08zxLSVJb0wlyhDD .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-08zxLSVJb0wlyhDD .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-08zxLSVJb0wlyhDD .noteText,#mermaid-svg-08zxLSVJb0wlyhDD .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-08zxLSVJb0wlyhDD .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-08zxLSVJb0wlyhDD .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-08zxLSVJb0wlyhDD .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-08zxLSVJb0wlyhDD .actorPopupMenu{position:absolute;}#mermaid-svg-08zxLSVJb0wlyhDD .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-08zxLSVJb0wlyhDD .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-08zxLSVJb0wlyhDD .actor-man circle,#mermaid-svg-08zxLSVJb0wlyhDD line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-08zxLSVJb0wlyhDD :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 提交草稿URL + apiKey submit_task(draft_url, apiKey) 返回任务状态 返回任务已提交 可选：触发导出流程 导出完成

媒体工具与辅助能力

  • 媒体时长探测：基于 ffprobe 获取音视频时长（微秒），支持超时与格式化输出
  • URL参数解析：从草稿URL中提取 draft_id
  • 剪映自动化：窗口识别、导出路径获取、分辨率/帧率设置、等待导出完成

依赖关系分析

  • 路由层依赖服务层；服务层依赖草稿引擎与工具层；配置中心贯穿全局
  • 任务管理器与剪映自动化为可选集成点，不影响核心装配流程

#mermaid-svg-toZHwAVyZI4viiIr{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-toZHwAVyZI4viiIr .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-toZHwAVyZI4viiIr .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-toZHwAVyZI4viiIr .error-icon{fill:#552222;}#mermaid-svg-toZHwAVyZI4viiIr .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-toZHwAVyZI4viiIr .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-toZHwAVyZI4viiIr .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-toZHwAVyZI4viiIr .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-toZHwAVyZI4viiIr .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-toZHwAVyZI4viiIr .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-toZHwAVyZI4viiIr .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-toZHwAVyZI4viiIr .marker{fill:#333333;stroke:#333333;}#mermaid-svg-toZHwAVyZI4viiIr .marker.cross{stroke:#333333;}#mermaid-svg-toZHwAVyZI4viiIr svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-toZHwAVyZI4viiIr p{margin:0;}#mermaid-svg-toZHwAVyZI4viiIr .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-toZHwAVyZI4viiIr .cluster-label text{fill:#333;}#mermaid-svg-toZHwAVyZI4viiIr .cluster-label span{color:#333;}#mermaid-svg-toZHwAVyZI4viiIr .cluster-label span p{background-color:transparent;}#mermaid-svg-toZHwAVyZI4viiIr .label text,#mermaid-svg-toZHwAVyZI4viiIr span{fill:#333;color:#333;}#mermaid-svg-toZHwAVyZI4viiIr .node rect,#mermaid-svg-toZHwAVyZI4viiIr .node circle,#mermaid-svg-toZHwAVyZI4viiIr .node ellipse,#mermaid-svg-toZHwAVyZI4viiIr .node polygon,#mermaid-svg-toZHwAVyZI4viiIr .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-toZHwAVyZI4viiIr .rough-node .label text,#mermaid-svg-toZHwAVyZI4viiIr .node .label text,#mermaid-svg-toZHwAVyZI4viiIr .image-shape .label,#mermaid-svg-toZHwAVyZI4viiIr .icon-shape .label{text-anchor:middle;}#mermaid-svg-toZHwAVyZI4viiIr .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-toZHwAVyZI4viiIr .rough-node .label,#mermaid-svg-toZHwAVyZI4viiIr .node .label,#mermaid-svg-toZHwAVyZI4viiIr .image-shape .label,#mermaid-svg-toZHwAVyZI4viiIr .icon-shape .label{text-align:center;}#mermaid-svg-toZHwAVyZI4viiIr .node.clickable{cursor:pointer;}#mermaid-svg-toZHwAVyZI4viiIr .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-toZHwAVyZI4viiIr .arrowheadPath{fill:#333333;}#mermaid-svg-toZHwAVyZI4viiIr .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-toZHwAVyZI4viiIr .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-toZHwAVyZI4viiIr .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-toZHwAVyZI4viiIr .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-toZHwAVyZI4viiIr .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-toZHwAVyZI4viiIr .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-toZHwAVyZI4viiIr .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-toZHwAVyZI4viiIr .cluster text{fill:#333;}#mermaid-svg-toZHwAVyZI4viiIr .cluster span{color:#333;}#mermaid-svg-toZHwAVyZI4viiIr div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-toZHwAVyZI4viiIr .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-toZHwAVyZI4viiIr rect.text{fill:none;stroke-width:0;}#mermaid-svg-toZHwAVyZI4viiIr .icon-shape,#mermaid-svg-toZHwAVyZI4viiIr .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-toZHwAVyZI4viiIr .icon-shape p,#mermaid-svg-toZHwAVyZI4viiIr .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-toZHwAVyZI4viiIr .icon-shape .label rect,#mermaid-svg-toZHwAVyZI4viiIr .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-toZHwAVyZI4viiIr .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-toZHwAVyZI4viiIr .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-toZHwAVyZI4viiIr :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 路由层

src/router/v1.py
服务层

src/service/*.py
草稿引擎

pyJianYingDraft
工具层

下载/媒体/任务管理
配置中心

config.py
剪映自动化

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

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

文档信息

相关推荐
小仙女喂得猪2 小时前
AI 写 Android 代码老翻车？我把移动端的 Harness 系统开源了
android·github·ai编程
AdCj32 小时前
上下文成本四把刀: 本期 GitHub Trending Daily 精选技术分析版(2026-06-04)
github
鱼羽生生2 小时前
基于NetCorePal Cloud Framework的DDD架构管理系统实践
github
自进化Agent智能体2 小时前
Hermes Skill设计模式：把AI能力变成可复用的工程资产
github
X54先生（人文科技）3 小时前
《元创力》纪实录·卷宗2.1边界测绘：一枚信标的沉没与一张舆图的诞生
人工智能·深度学习·开源·ai写作
AdCj34 小时前
上下文成本四把刀本期 GitHub Trending Daily 精选 (2026-06-04)
github
brycegao3215 小时前
Tauri2+Vue3+Ollama 实战｜依托 AI 协同开发全离线隐私记账桌面软件（开源）
人工智能·开源·vue·ai编程·tauri·ollama·桌面开发
亥时科技5 小时前
无人机利用率看不清？一块 BI 仪表盘，能把“设备台账”变成“经营驾驶舱”
开源·无人机·ai巡检
pipo6 小时前
从 LIO 到 Nav2：我把 FAST-LIO改造成了机器人能用的底盘里程计
github
热门推荐
01GitHub 镜像站点02【AI】2026 年具身智能模型和世界模型总结03Codex 下载安装指南：Windows 和 macOS 官方版下载042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf05Codex 桌面端更新后 Chrome 插件和 Computer Use 不可用，怎么排查和修复06【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法07CC-Switch 下载、安装与使用配置指南【2026.5.29】08Codex 接入 DeepSeek API 完整配置文档09CC-Switch & Claude 基于 Linux 服务器安装使用指南10裂开！ChatGPT 居然开始要手机号验证，附详细解决方法