add_video_transition
Add transition effects between video segments in JianYing (CapCut) projects. Specify transition type and duration to create professional video edits.
Instructions
为视频片段添加转场效果，注意两视频间添加转场应该在前一个添加转场，即video_segment_id使用前一个视频
Args: video_segment_id: 视频片段ID，通过add_video_segment获得 transition_type: 转场类型名称，可以使用find_effects_by_type工具，资源类型选择TransitionType，从而获取转场类型有哪些 duration: 转场持续时间，格式如 "1s"（可选）
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| video_segment_id | Yes | ||
| transition_type | Yes | ||
| duration | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| message | Yes | ||
| success | Yes |
Implementation Reference
- jianyingdraft/tool/video_tool.py:217-292 (handler)The MCP tool handler for 'add_video_transition'. Validates the transition_type using JianYingResourceManager, resolves draft_id and track_name using index_manager, and delegates to add_video_transition_service.
@mcp.tool() def add_video_transition( video_segment_id: str, transition_type: str, duration: Optional[str] = None ) -> ToolResponse: """ 为视频片段添加转场效果，注意两视频间添加转场应该在前一个添加转场，即video_segment_id使用前一个视频 Args: video_segment_id: 视频片段ID，通过add_video_segment获得 transition_type: 转场类型名称，可以使用find_effects_by_type工具，资源类型选择TransitionType，从而获取转场类型有哪些 duration: 转场持续时间，格式如 "1s"（可选） """ # 转场存在性验证 effects = manager.find_by_type( effect_type="TransitionType", keyword=transition_type, limit=1 ) # 检查是否找到完全匹配的转场 exact_match = False if effects: for effect in effects: if effect.get('name') == transition_type: exact_match = True break if not effects or not exact_match: # 获取建议转场 transition_suggestions = manager.find_by_type("TransitionType", keyword=transition_type) all_suggestions = [] for effect in transition_suggestions: if effect.get('name'): all_suggestions.append(effect.get('name')) return ToolResponse( success=False, message=f"未找到转场 '{transition_type}',请确认转场名称是否正确，或尝试使用以下建议: {', '.join(all_suggestions)}", data={ "error_type": "transition_not_found", "transition_name": transition_type, "suggestions": all_suggestions } ) # 通过video_segment_id获取相关信息 draft_id = index_manager.get_draft_id_by_video_segment_id(video_segment_id) track_info = index_manager.get_track_info_by_video_segment_id(video_segment_id) if not draft_id: return ToolResponse( success=False, message=f"未找到视频片段ID对应的草稿: {video_segment_id}" ) if not track_info: return ToolResponse( success=False, message=f"未找到视频片段ID对应的轨道信息: {video_segment_id}" ) track_name = track_info.get("track_name") # 调用服务层处理业务逻辑 result = add_video_transition_service( draft_id=draft_id, video_segment_id=video_segment_id, transition_type=transition_type, duration=duration, track_name=track_name ) return result - jianyingdraft/server.py:28-28 (registration)The call to video_tools(mcp) in the main server file, which registers the video tools including 'add_video_transition'.
video_tools(mcp) - Helper service function that instantiates VideoSegment and invokes its add_transition method to apply the transition, handling errors and formatting response.
def add_video_transition_service( draft_id: str, video_segment_id: str, transition_type: str, duration: Optional[str] = None, track_name: Optional[str] = None ) -> ToolResponse: """ 视频转场添加服务 - 为视频片段添加转场效果 Args: draft_id: 草稿ID video_segment_id: 视频片段ID transition_type: 转场类型名称，如 "信号故障", "淡入淡出" 等 duration: 转场持续时间，格式如 "1s"（可选） track_name: 轨道名称（可选） Returns: ToolResponse: 包含操作结果的响应对象 """ try: # 创建VideoSegment实例，传入video_segment_id video_segment = VideoSegment(draft_id, video_segment_id=video_segment_id, track_name=track_name) # 调用视频转场添加方法 result_data = video_segment.add_transition( transition_type=transition_type, duration=duration ) # 构建返回数据 response_data = { "video_segment_id": video_segment_id, "draft_id": draft_id, "transition_type": transition_type, "duration": duration, "add_transition": result_data } # 如果有轨道名称，添加到返回数据中 if track_name: response_data["track_name"] = track_name return ToolResponse( success=True, message=f"视频转场添加成功: {transition_type}", data=response_data ) except ValueError as e: # 处理参数错误 return ToolResponse( success=False, message=f"参数错误: {str(e)}" ) except NameError as e: # 处理轨道不存在错误 return ToolResponse( success=False, message=f"轨道错误: {str(e)}" ) except Exception as e: # 处理其他未预期的错误 return ToolResponse( success=False, message=f"视频转场添加失败: {str(e)}" ) - Core implementation in VideoSegment class: constructs the JSON operation data for 'add_transition' and appends it to the draft's video.json file.
def add_transition(self, transition_type: str, duration: Optional[str] = None, video_segment_id: Optional[str] = None) -> bool: """ 添加转场特效 Args: transition_type: 转场类型名称，如 "信号故障", "淡入淡出" 等 duration: 转场持续时间，如 "1s" Returns: bool: 添加是否成功 """ if self.video_segment_id is None and video_segment_id is None: print("错误: video_segment_id不能为空") return False video_segment_id = video_segment_id or self.video_segment_id # 构建add_transition参数（只保存用户传入的参数） add_transition_params = { "transition_type": transition_type } # 只添加用户明确传入的可选参数 if duration is not None: add_transition_params["duration"] = duration # 构建完整的转场数据 transition_data = { "video_segment_id": video_segment_id, "operation": "add_transition", "add_transition": add_transition_params } # 保存参数 self.add_json_to_file(transition_data) return True