第26章 特效添加服务
26.1 概述
特效添加服务负责在视频编辑草稿中添加各种视觉特效，包括场景特效和人物特效两大类。该服务支持批量添加特效，每个特效可以设置不同的开始时间、结束时间和特效参数，为视频创作提供丰富的视觉效果。
26.2 核心实现
26.2.1 服务入口函数
特效添加服务的核心实现位于 src/service/add_effects.py 文件中：
async def add_effects(request: AddEffectsRequest) -> AddEffectsResponse:
"""添加特效到草稿"""
logger.info(f"添加特效到草稿: {request.draft_url}")
# 参数验证
if not request.draft_url:
raise ValueError("草稿URL不能为空")
if not request.effects:
raise ValueError("特效列表不能为空")
# 获取草稿缓存
draft = await get_draft_cache(request.draft_url)
if not draft:
raise INVALID_DRAFT_URL
# 创建特效轨道
effect_track = draft.create_track("effect")
# 处理特效列表
effect_ids = []
segment_ids = []
for effect_item in request.effects:
try:
# 解析特效信息
effect_info = parse_effect_info(effect_item)
# 创建特效片段
effect_segment = create_effect_segment(effect_info, draft)
# 添加特效到轨道
effect_track.add_segment(effect_segment)
# 记录ID
effect_ids.append(effect_segment.material_id)
segment_ids.append(effect_segment.id)
except Exception as e:
logger.error(f"处理特效失败: {effect_item}, 错误: {str(e)}")
continue
# 保存草稿
await save_draft_cache(request.draft_url, draft)
return AddEffectsResponse(
draft_url=request.draft_url,
track_id=effect_track.id,
effect_ids=effect_ids,
segment_ids=segment_ids
)
26.2.2 特效信息解析
特效信息的解析是关键步骤，涉及JSON解析和参数验证：
def parse_effect_info(effect_item: EffectItem) -> dict:
"""解析特效信息"""
try:
# 如果是字符串，尝试JSON解析
if isinstance(effect_item.effect_info, str):
effect_info = json.loads(effect_item.effect_info)
else:
effect_info = effect_item.effect_info
# 验证必填字段
required_fields = ["effect_name", "start", "end"]
for field in required_fields:
if field not in effect_info:
raise ValueError(f"缺少必填字段: {field}")
return effect_info
except json.JSONDecodeError as e:
raise ValueError(f"特效信息JSON解析失败: {str(e)}")
except Exception as e:
raise ValueError(f"特效信息解析失败: {str(e)}")
26.2.3 特效片段创建
根据解析后的特效信息创建特效片段：
def create_effect_segment(effect_info: dict, draft) -> EffectSegment:
"""创建特效片段"""
# 获取特效类型
effect_type = get_effect_type(effect_info["effect_name"])
# 创建时间范围
time_range = TimeRange(
start=effect_info["start"],
duration=effect_info["end"] - effect_info["start"]
)
# 创建特效片段
effect_segment = EffectSegment(
id=f"effect_{uuid.uuid4().hex}",
material_id=effect_info["effect_name"],
type=effect_type,
clip=clip_settings,
render_type="effect",
source_type="user",
time_range=time_range
)
# 设置特效参数
if "params" in effect_info:
effect_segment.params = effect_info["params"]
return effect_segment
26.2.4 特效类型判断
系统根据特效名称判断特效类型：
def get_effect_type(effect_name: str) -> str:
"""获取特效类型"""
# 场景特效类型
scene_effects = [
VideoSceneEffectType.FLASH,
VideoSceneEffectType.GLITCH,
VideoSceneEffectType.BLUR,
VideoSceneEffectType.PARTICLE,
VideoSceneEffectType.LIGHT,
VideoSceneEffectType.WEATHER,
VideoSceneEffectType.TRANSITION
]
# 人物特效类型
character_effects = [
VideoCharacterEffectType.BEAUTY,
VideoCharacterEffectType.FACE,
VideoCharacterEffectType.BODY,
VideoCharacterEffectType.HAIR,
VideoCharacterEffectType.MAKEUP
]
# 判断特效类型
if effect_name in scene_effects:
return "scene"
elif effect_name in character_effects:
return "character"
else:
return "unknown"
26.3 特效分类与参数配置
26.3.1 场景特效类型
场景特效主要影响整个视频画面，包括：
class VideoSceneEffectType:
FLASH = "flash" # 闪烁特效
GLITCH = "glitch" # 故障特效
BLUR = "blur" # 模糊特效
PARTICLE = "particle" # 粒子特效
LIGHT = "light" # 光影特效
WEATHER = "weather" # 天气特效
TRANSITION = "transition" # 转场特效
26.3.2 人物特效类型
人物特效主要针对视频中的人物进行处理：
class VideoCharacterEffectType:
BEAUTY = "beauty" # 美颜特效
FACE = "face" # 面部特效
BODY = "body" # 身体特效
HAIR = "hair" # 发型特效
MAKEUP = "makeup" # 美妆特效
26.3.3 特效参数配置
不同类型的特效支持不同的参数配置：
# 闪烁特效参数
flash_params = {
"frequency": 2.0, # 闪烁频率
"intensity": 0.8 # 闪烁强度
}
# 模糊特效参数
blur_params = {
"radius": 5.0, # 模糊半径
"type": "gaussian" # 模糊类型
}
# 美颜特效参数
beauty_params = {
"smooth": 0.6, # 磨皮程度
"whiten": 0.4, # 美白程度
"thin_face": 0.3 # 瘦脸程度
}
26.4 数据结构定义
26.4.1 请求参数模型
class AddEffectsRequest(BaseModel):
"""添加特效请求参数"""
draft_url: str = Field(..., description="草稿URL")
effects: List[EffectItem] = Field(..., description="特效列表")
class EffectItem(BaseModel):
"""单个特效项"""
effect_info: Union[str, dict] = Field(..., description="特效信息，可以是JSON字符串或对象")
start: int = Field(default=0, description="开始时间，单位：微秒")
end: int = Field(default=None, description="结束时间，单位：微秒")
26.4.2 响应参数模型
class AddEffectsResponse(BaseModel):
"""添加特效响应参数"""
draft_url: str = Field(..., description="草稿URL")
track_id: str = Field(..., description="特效轨道ID")
effect_ids: List[str] = Field(..., description="特效ID列表")
segment_ids: List[str] = Field(..., description="片段ID列表")
26.5 异常处理
特效添加服务定义了完善的异常处理机制：
# 无效的特效信息
INVALID_EFFECT_INFO = HTTPException(
status_code=400,
detail="无效的特效信息"
)
# 特效添加失败
EFFECT_ADD_FAILED = HTTPException(
status_code=500,
detail="特效添加失败"
)
# 不支持的特效类型
UNSUPPORTED_EFFECT_TYPE = HTTPException(
status_code=400,
detail="不支持的特效类型"
)
26.6 API接口定义
@router.post("/addEffects", response_model=AddEffectsResponse)
async def add_effects_endpoint(request: AddEffectsRequest):
"""添加特效"""
try:
return await add_effects(request)
except Exception as e:
logger.error(f"添加特效失败: {str(e)}")
raise EFFECT_ADD_FAILED
26.7 使用示例
26.7.1 请求示例
{
"draft_url": "capcut://draft/123456789",
"effects": [
{
"effect_info": {
"effect_name": "flash",
"start": 0,
"end": 2000000,
"params": {
"frequency": 2.0,
"intensity": 0.8
}
}
},
{
"effect_info": {
"effect_name": "beauty",
"start": 2000000,
"end": 5000000,
"params": {
"smooth": 0.6,
"whiten": 0.4,
"thin_face": 0.3
}
}
}
]
}
26.7.2 响应示例
{
"draft_url": "capcut://draft/123456789",
"track_id": "track_effect_001",
"effect_ids": ["flash", "beauty"],
"segment_ids": ["effect_abc123", "effect_def456"]
}
26.8 性能优化
特效添加服务采用了多种性能优化策略：
- 批量处理：支持一次添加多个特效，减少网络请求次数
- 异步处理：使用异步函数处理特效添加，提高并发性能
- 缓存机制：草稿数据缓存在内存中，减少重复读取
- 错误隔离：单个特效添加失败不影响其他特效的处理
26.9 扩展性设计
特效服务具有良好的扩展性：
- 特效类型扩展：易于添加新的特效类型支持
- 参数配置扩展：特效参数可以通过配置文件动态调整
- 效果组合扩展：支持多个特效的组合使用
- 渲染引擎扩展：支持接入不同的渲染引擎
附录
代码仓库地址：
- GitHub:
https://github.com/Hommy-master/capcut-mate - Gitee:
https://gitee.com/taohongmin-gitee/capcut-mate
接口文档地址：
- API文档地址:
https://docs.jcaigc.cn
扫一扫
483
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
