【开源剪映小助手】字幕接口

字幕处理接口

简介

字幕处理接口是 CapCut Mate 项目的核心功能模块，提供完整的字幕管理解决方案。该接口支持批量添加字幕、样式配置、信息生成等功能，涵盖文本格式、时间轴定位、字体样式、颜色配置和动画效果等方面。

系统采用模块化设计，通过 FastAPI 框架提供 RESTful API 接口，支持多语言字幕处理、关键词高亮、字幕布局和对齐方式设置。接口还提供字幕文件的导入导出、批量处理和自动生成能力，并实现了字幕与音频的同步机制和显示优化技术。

项目结构

项目采用清晰的分层架构设计：
外部集成
核心引擎
服务层
API层
路由层
模式定义
业务逻辑
工具函数
草稿引擎
片段管理
动画系统
媒体处理
缓存管理
日志系统

核心组件

字幕添加接口

字幕添加接口提供批量字幕处理能力，支持丰富的样式配置选项：

参数类别	参数名称	数据类型	默认值	说明
基础参数	draft_url	string	-	目标草稿URL
基础参数	captions	string	-	字幕信息JSON字符串
样式参数	text_color	string	"#ffffff"	文本颜色
样式参数	border_color	string	null	边框颜色
样式参数	alignment	integer	1	文本对齐方式
样式参数	alpha	number	1.0	文本透明度
字体参数	font	string	null	字体名称
字体参数	font_size	integer	15	字体大小
位置参数	scale_x	number	1.0	水平缩放
位置参数	scale_y	number	1.0	垂直缩放
位置参数	transform_x	number	0.0	X轴位置偏移
位置参数	transform_y	number	0.0	Y轴位置偏移

字幕信息生成接口

字幕信息生成接口提供自动化字幕信息生成功能：
"字幕生成器" "服务层" "API接口" "客户端" "字幕生成器" "服务层" "API接口" "客户端" POST /v1/caption_infos caption_infos() _build_caption_info() 处理文本和时间线应用样式配置返回字幕信息返回JSON字符串字幕信息响应

架构概览

系统采用分层架构设计，确保各层职责清晰分离：
数据层
业务层
应用层
表现层
Web界面
RESTful API
路由处理器
参数验证器
数据格式化器
字幕服务
动画服务
样式服务
草稿缓存
素材缓存
配置存储

数据模型关系

contains
uses
produces
AddCaptionsRequest
+string draft_url
+string captions
+string text_color
+string border_color
+integer alignment
+float alpha
+string font
+integer font_size
+float scale_x
+float scale_y
+float transform_x
+float transform_y
+ShadowInfo shadow_info
CaptionItem
+integer start
+integer end
+string text
+string keyword
+string keyword_color
+integer keyword_font_size
+integer font_size
+string in_animation
+string out_animation
+string loop_animation
ShadowInfo
+float shadow_alpha
+string shadow_color
+float shadow_diffuse
+float shadow_distance
+float shadow_angle
AddCaptionsResponse
+string draft_url
+string track_id
+string[] text_ids
+string[] segment_ids
+SegmentInfo[] segment_infos

详细组件分析

字幕样式系统

字幕样式系统提供全面的文本格式化能力：

字体样式配置

样式属性	参数名称	数据类型	默认值	说明
字体大小	size	float	8.0	字体尺寸
字体粗细	bold	boolean	false	是否加粗
字体倾斜	italic	boolean	false	是否斜体
下划线	underline	boolean	false	是否下划线
字体颜色	color	tuple	(1.0, 1.0, 1.0)	RGB颜色值
透明度	alpha	float	1.0	文本透明度
对齐方式	align	integer	0	对齐方式
字符间距	letter_spacing	integer	0	字符间距
行间距	line_spacing	integer	0	行间距
自动换行	auto_wrapping	boolean	false	是否自动换行

文本阴影系统

否
是
否
是
开始阴影处理
是否启用阴影?
跳过阴影处理
是否有阴影配置?
使用默认阴影配置
使用自定义阴影配置
创建阴影对象
验证参数
应用阴影到文本
完成

关键词高亮功能

关键词高亮功能支持多关键词处理和个性化样式配置：
"样式构建器" "关键词处理器" "文本片段" "样式构建器" "关键词处理器" "文本片段" 处理关键词列表解析关键词分隔符创建高亮样式设置关键词颜色设置关键词字体大小复制基础样式属性返回样式配置应用额外样式更新文本样式

动画系统

系统提供丰富的文字动画效果，包括入场、出场和循环动画：

动画类型分类

动画类型	数量	说明
入场动画	75+	文字进入画面的动画效果
出场动画	60+	文字离开画面的动画效果
循环动画	40+	文字持续播放的循环效果

动画配置参数

extends
manages
TextAnimation
+string name
+boolean is_free
+float duration
+string resource_id
+string effect_id
+string platform
AnimationMeta
+string title
+boolean is_premium
+float duration
+string resource_id
+string effect_id
+string platform
SegmentAnimations
+TextAnimation[] animations
+string animation_id
+add_animation(animation, start, duration)
+get_animation_trange(type)

时间轴管理系统

时间轴管理系统提供精确的时间控制和同步机制：

时间参数规范

参数名称	单位	范围	说明
start	微秒	≥0	开始时间戳
end	微秒	>start	结束时间戳
duration	微秒	>0	显示时长
transform_x	像素	任意整数	水平位置偏移
transform_y	像素	任意整数	垂直位置偏移
scale_x	比例	>0	水平缩放比例
scale_y	比例	>0	垂直缩放比例

坐标系统转换

像素坐标
转换为画布宽度比例
转换为画布高度比例
相对坐标
应用变换
最终位置
transform_x / script.width
transform_y / script.height

依赖关系分析

系统采用模块化设计，各组件之间保持松耦合：
外部接口
媒体处理
业务逻辑
核心依赖
Pydantic模型验证
FastAPI路由框架
UUID生成
辅助工具
日志系统
缓存管理
脚本文件
文本片段
动画系统
草稿缓存
媒体工具
异常处理
Router
ServiceLayer
ErrorHandler

错误处理机制

系统提供完善的错误处理和异常管理：

错误类型	错误码	触发条件	处理方式
参数验证错误	400	必填参数缺失	返回详细错误信息
草稿不存在	404	草稿URL无效	提示重新获取草稿
字幕添加失败	500	业务逻辑异常	记录日志并重试
JSON解析错误	400	字幕数据格式错误	返回格式错误信息

性能考虑

缓存策略

系统采用多级缓存机制优化性能：

草稿缓存：存储活跃的草稿对象，避免重复加载
素材缓存：缓存常用的字体和动画素材
配置缓存：缓存用户偏好设置和样式配置

批量处理优化

是
否
批量字幕处理
验证批次数据
逐项处理
应用样式配置
添加到轨道
批量保存草稿
完成处理
是否有动画?
处理动画
跳过动画

内存管理

系统采用流式处理和及时释放机制：

及时释放临时对象引用
控制批量处理的内存占用
优化大文件处理的内存使用

故障排除指南

常见问题诊断

字幕显示异常

问题症状：字幕位置不正确或样式异常

诊断步骤：

检查坐标转换是否正确
验证字体配置是否有效
确认动画参数设置

解决方案：

调整transform_x和transform_y参数
检查字体文件是否存在
验证动画名称拼写

性能问题

问题症状：批量处理速度慢或内存占用过高