add_text_segment
Add customizable text segments to video tracks in JianYing MCP for creating captions, titles, and annotations with precise timing and styling options.
Instructions
添加文本片段到指定轨道
Args: track_id: 轨道ID，通过create_track获得 text: 文本内容 target_start_end: 片段在轨道上的目标时间范围，格式如 "1s-4.2s"，表示在轨道上从1s开始，到4.2s结束 font: 字体类型名称（可选） style: 字体样式字典（可选），哪些需要修改就填哪些字段 默认style = { "size": 6.0,# 字体大小, 默认为6.0 "bold": False,# 是否加粗, 默认为否 "italic": False,# 是否斜体, 默认为否 "underline": False,# 是否加下划线, 默认为否 "color": (1.0, 1.0, 1.0), # 字体颜色, RGB三元组, 取值范围为[0, 1], 默认为白色 "alpha": 1.0,# 字体不透明度, 取值范围[0, 1], 默认不透明 "align": 0, # 对齐方式, 0: 左对齐, 1: 居中, 2: 右对齐, 默 认为左对齐 "vertical": False,#是否为竖排文本, 默认为否 "letter_spacing": 0,# 字符间距, 定义与剪映中一致, 默认为0 "line_spacing": 0,# 行间距, 定义与剪映中一致, 默认为0 "auto_wrapping": False,# 是否自动换行, 默认关闭 "max_line_width": 0.82 # 每行最大行宽占屏幕宽度比例, 取值范围为[0, 1], 默认为0.82 } clip_settings: 图像调节设置字典（可选），哪些需要修改就填哪些字段 默认 clip_settings = { "alpha": 1.0, # 图像不透明度, 0-1. 默认为1.0. "flip_horizontal": False, # 是否水平翻转. 默认为False. "flip_vertical": False, # 是否垂直翻转. 默认为False. "rotation": 0.0, # 顺时针旋转的角度, 可正可负. 默认为0.0. "scale_x": 1.0, # 水平缩放比例. 默认为1.0. "scale_y": 1.0, # 垂直缩放比例. 默认为1.0. "transform_x": 0.0, # 水平位移, 单位为半个画布宽. 默认为0.0. "transform_y": 0.0 # 垂直位移, 单位为半个画布高. 默认为0.0.但强烈建议修改为-0.8(这样字幕是在正下方，不影响视频观感) } border: 文本描边参数字典（可选），哪些需要修改就填哪些字段 stroke_style = { "alpha": 1.0, # 描边不透明度, 取值范围[0, 1], 默认为1.0 "color": (0.0, 0.0, 0.0), # 描边颜色, RGB三元组, 取值范围为[0, 1], 默认为黑色 "width": 40.0 # 描边宽度, 与剪映中一致, 取值范围为[0, 100], 默认为40.0 } background: 文本背景参数字典（可选），哪些需要修改就填哪些字段 默认 background = { "color": "#000000", # 背景颜色, 格式为'#RRGGBB' (默认为黑色) "style": 1, # 背景样式, 1和2分别对应剪映中的两种样式, 默认为1 "alpha": 1.0, # 背景不透明度, 与剪映中一致, 取值范围[0, 1], 默认为1.0 "round_radius": 0.0, # 背景圆角半径, 与剪映中一致, 取值范围[0, 1], 默认为0.0 "height": 0. 14, # 背景高度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14 "width": 0.14, # 背景宽度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14 "horizontal_offset": 0.5, # 背景水平偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5 "vertical_offset": 0.5 # 背景竖直偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5 }
Examples: # 基础文本 add_text_segment("track_id", "Hello World", "0s-5s")
# 带样式的文本
add_text_segment("track_id", "标题文本", "0s-3s",
style={"size": 12.0, "bold": True, "color": (1.0, 0.0, 0.0)})
# 带描边的文本
add_text_segment("track_id", "描边文本", "2s-7s",
border={"width": 20.0, "color": (0.0, 0.0, 0.0)})
# 带背景的文本
add_text_segment("track_id", "背景文本", "5s-10s",
background={"color": "#FF0000", "alpha": 0.8})Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| track_id | Yes | ||
| text | Yes | ||
| target_start_end | Yes | ||
| font | No | ||
| style | No | ||
| clip_settings | No | ||
| border | No | ||
| background | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| message | Yes | ||
| success | Yes |
Implementation Reference
- jianyingdraft/tool/text_tool.py:16-136 (handler)The main MCP tool handler function for 'add_text_segment'. It validates inputs, resolves draft_id and track_name from track_id using index_manager, calls the text service, and updates mappings.
def add_text_segment( track_id: str, text: str, target_start_end: str, font: Optional[str] = None, style: Optional[Dict[str, Any]] = None, clip_settings: Optional[Dict[str, Any]] = None, border: Optional[Dict[str, Any]] = None, background: Optional[Dict[str, Any]] = None ) -> ToolResponse: """ 添加文本片段到指定轨道 Args: track_id: 轨道ID，通过create_track获得 text: 文本内容 target_start_end: 片段在轨道上的目标时间范围，格式如 "1s-4.2s"，表示在轨道上从1s开始，到4.2s结束 font: 字体类型名称（可选） style: 字体样式字典（可选），哪些需要修改就填哪些字段 默认style = { "size": 6.0,# 字体大小, 默认为6.0 "bold": False,# 是否加粗, 默认为否 "italic": False,# 是否斜体, 默认为否 "underline": False,# 是否加下划线, 默认为否 "color": (1.0, 1.0, 1.0), # 字体颜色, RGB三元组, 取值范围为[0, 1], 默认为白色 "alpha": 1.0,# 字体不透明度, 取值范围[0, 1], 默认不透明 "align": 0, # 对齐方式, 0: 左对齐, 1: 居中, 2: 右对齐, 默 认为左对齐 "vertical": False,#是否为竖排文本, 默认为否 "letter_spacing": 0,# 字符间距, 定义与剪映中一致, 默认为0 "line_spacing": 0,# 行间距, 定义与剪映中一致, 默认为0 "auto_wrapping": False,# 是否自动换行, 默认关闭 "max_line_width": 0.82 # 每行最大行宽占屏幕宽度比例, 取值范围为[0, 1], 默认为0.82 } clip_settings: 图像调节设置字典（可选），哪些需要修改就填哪些字段 默认 clip_settings = { "alpha": 1.0, # 图像不透明度, 0-1. 默认为1.0. "flip_horizontal": False, # 是否水平翻转. 默认为False. "flip_vertical": False, # 是否垂直翻转. 默认为False. "rotation": 0.0, # 顺时针旋转的**角度**, 可正可负. 默认为0.0. "scale_x": 1.0, # 水平缩放比例. 默认为1.0. "scale_y": 1.0, # 垂直缩放比例. 默认为1.0. "transform_x": 0.0, # 水平位移, 单位为半个画布宽. 默认为0.0. "transform_y": 0.0 # 垂直位移, 单位为半个画布高. 默认为0.0.但强烈建议修改为-0.8(这样字幕是在正下方，不影响视频观感) } border: 文本描边参数字典（可选），哪些需要修改就填哪些字段 stroke_style = { "alpha": 1.0, # 描边不透明度, 取值范围[0, 1], 默认为1.0 "color": (0.0, 0.0, 0.0), # 描边颜色, RGB三元组, 取值范围为[0, 1], 默认为黑色 "width": 40.0 # 描边宽度, 与剪映中一致, 取值范围为[0, 100], 默认为40.0 } background: 文本背景参数字典（可选），哪些需要修改就填哪些字段 默认 background = { "color": "#000000", # 背景颜色, 格式为'#RRGGBB' (默认为黑色) "style": 1, # 背景样式, 1和2分别对应剪映中的两种样式, 默认为1 "alpha": 1.0, # 背景不透明度, 与剪映中一致, 取值范围[0, 1], 默认为1.0 "round_radius": 0.0, # 背景圆角半径, 与剪映中一致, 取值范围[0, 1], 默认为0.0 "height": 0. 14, # 背景高度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14 "width": 0.14, # 背景宽度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14 "horizontal_offset": 0.5, # 背景水平偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5 "vertical_offset": 0.5 # 背景竖直偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5 } Examples: # 基础文本 add_text_segment("track_id", "Hello World", "0s-5s") # 带样式的文本 add_text_segment("track_id", "标题文本", "0s-3s", style={"size": 12.0, "bold": True, "color": (1.0, 0.0, 0.0)}) # 带描边的文本 add_text_segment("track_id", "描边文本", "2s-7s", border={"width": 20.0, "color": (0.0, 0.0, 0.0)}) # 带背景的文本 add_text_segment("track_id", "背景文本", "5s-10s", background={"color": "#FF0000", "alpha": 0.8}) """ # 将新格式转换为原来的格式 try: timerange = parse_start_end_format(target_start_end) except ValueError as e: return ToolResponse( success=False, message=f"target_start_end格式错误: {str(e)}" ) # 通过track_id获取draft_id和track_name draft_id = index_manager.get_draft_id_by_track_id(track_id) track_name = index_manager.get_track_name_by_track_id(track_id) if not draft_id: return ToolResponse( success=False, message=f"未找到轨道ID对应的草稿: {track_id}" ) if not track_name: return ToolResponse( success=False, message=f"未找到轨道ID对应的轨道名: {track_id}" ) # 调用服务层处理业务逻辑 result = add_text_segment_service( draft_id=draft_id, text=text, timerange=timerange, font=font, style=style, clip_settings=clip_settings, border=border, background=background, track_name=track_name ) # 如果文本片段添加成功，添加索引记录 if result.success and result.data and "text_segment_id" in result.data: text_segment_id = result.data["text_segment_id"] index_manager.add_text_segment_mapping(text_segment_id, track_id) return result - jianyingdraft/server.py:24-36 (registration)Registration of all tools including text_tools(mcp) which registers the add_text_segment tool.
def main(): # 注册所有工具 draft_tools(mcp) track_tools(mcp) video_tools(mcp) text_tools(mcp) audio_tools(mcp) utility_tools(mcp) mcp.run() if __name__ == "__main__": main() - Service function that instantiates TextSegment and calls its add_text_segment method, handles errors and formats response.
def add_text_segment_service( draft_id: str, text: str, timerange: str, font: Optional[str] = None, style: Optional[Dict[str, Any]] = None, clip_settings: Optional[Dict[str, Any]] = None, border: Optional[Dict[str, Any]] = None, background: Optional[Dict[str, Any]] = None, track_name: Optional[str] = None ) -> ToolResponse: """ 文本片段添加服务 - 创建文本片段 Args: draft_id: 草稿ID text: 文本内容 timerange: 时间范围，格式如 "0s-5s" font: 字体类型名称（可选） style: 字体样式字典（可选） clip_settings: 图像调节设置字典（可选） border: 文本描边参数字典（可选） background: 文本背景参数字典（可选） track_name: 指定的轨道名称（可选） Returns: ToolResponse: 包含操作结果的响应对象 """ try: # 创建TextSegment实例 text_segment = TextSegment(draft_id, track_name=track_name) # 调用文本片段添加方法 result_data = text_segment.add_text_segment( text=text, timerange=timerange, font=font, style=style, clip_settings=clip_settings, border=border, background=background, track_name=track_name ) # 构建返回数据 response_data = { "text_segment_id": text_segment.text_segment_id, "draft_id": draft_id, "text": text, "timerange": timerange, "add_text_segment": result_data } # 添加可选参数到返回数据 if font: response_data["font"] = font if style: response_data["style"] = style if clip_settings: response_data["clip_settings"] = clip_settings if border: response_data["border"] = border if background: response_data["background"] = background if track_name: response_data["track_name"] = track_name return ToolResponse( success=True, message=f"文本片段添加成功: {text[:20]}{'...' if len(text) > 20 else ''}", 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 TextSegment class that parses timerange, builds the operation JSON with 'add_text_segment' params, validates track and overlap, generates ID, saves to draft's text.json file.
def add_text_segment(self, text: str, timerange: str, font: Optional[str] = None, style: Optional[Dict[str, Any]] = None, clip_settings: Optional[Dict[str, Any]] = None, border: Optional[Dict[str, Any]] = None, background: Optional[Dict[str, Any]] = None, track_name: Optional[str] = None) -> Dict[str, Any]: """ 创建文本片段配置，可选的参数用户没要求可不填 Args: text: 文本内容 timerange: 时间范围，格式如 "0s-4.2s",表示在轨道上从0s开始，持续4.2s font: 字体类型名称（可选） style: 字体样式字典（可选），哪些需要修改就填哪些字段 默认style = { "size": 6.0,# 字体大小, 默认为6.0 "bold": False,# 是否加粗, 默认为否 "italic": False,# 是否斜体, 默认为否 "underline": False,# 是否加下划线, 默认为否 "color": (1.0, 1.0, 1.0), # 字体颜色, RGB三元组, 取值范围为[0, 1], 默认为白色 "alpha": 1.0,# 字体不透明度, 取值范围[0, 1], 默认不透明 "align": 0, # 对齐方式, 0: 左对齐, 1: 居中, 2: 右对齐, 默 认为左对齐 "vertical": False,#是否为竖排文本, 默认为否 "letter_spacing": 0,# 字符间距, 定义与剪映中一致, 默认为0 "line_spacing": 0,# 行间距, 定义与剪映中一致, 默认为0 "auto_wrapping": False,# 是否自动换行, 默认关闭 "max_line_width": 0.82 # 每行最大行宽占屏幕宽度比例, 取值范围为[0, 1], 默认为0.82 } clip_settings: 图像调节设置字典（可选），哪些需要修改就填哪些字段 默认 clip_settings = { "alpha": 1.0, # 图像不透明度, 0-1. 默认为1.0. "flip_horizontal": False, # 是否水平翻转. 默认为False. "flip_vertical": False, # 是否垂直翻转. 默认为False. "rotation": 0.0, # 顺时针旋转的**角度**, 可正可负. 默认为0.0. "scale_x": 1.0, # 水平缩放比例. 默认为1.0. "scale_y": 1.0, # 垂直缩放比例. 默认为1.0. "transform_x": 0.0, # 水平位移, 单位为半个画布宽. 默认为0.0. "transform_y": 0.0 # 垂直位移, 单位为半个画布高. 默认为0.0. } border: 文本描边参数字典（可选），哪些需要修改就填哪些字段 stroke_style = { "alpha": 1.0, # 描边不透明度, 取值范围[0, 1], 默认为1.0 "color": (0.0, 0.0, 0.0), # 描边颜色, RGB三元组, 取值范围为[0, 1], 默认为黑色 "width": 40.0 # 描边宽度, 与剪映中一致, 取值范围为[0, 100], 默认为40.0 } background: 文本背景参数字典（可选），哪些需要修改就填哪些字段 默认 background = { "color": "#000000", # 背景颜色, 格式为'#RRGGBB' (默认为黑色) "style": 1, # 背景样式, 1和2分别对应剪映中的两种样式, 默认为1 "alpha": 1.0, # 背景不透明度, 与剪映中一致, 取值范围[0, 1], 默认为1.0 "round_radius": 0.0, # 背景圆角半径, 与剪映中一致, 取值范围[0, 1], 默认为0.0 "height": 0. 14, # 背景高度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14 "width": 0.14, # 背景宽度, 与剪映中一致, 取值范围为[0, 1], 默认为0.14 "horizontal_offset": 0.5, # 背景水平偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5 "vertical_offset": 0.5 # 背景竖直偏移, 与剪映中一致, 取值范围为[0, 1], 默认为0.5 } track_name: 指定的轨道名称（可选），如果不指定则使用实例的track_name Returns: Dict[str, Any]: 构造的参数字典 """ self.text_segment_id = str(uuid.uuid4()) # 解析timerange if not timerange or "-" not in timerange: raise ValueError(f"Invalid timerange format: {timerange}") start_str, duration_str = timerange.split("-", 1) timerange_data = { "start": start_str.strip(), "duration": duration_str.strip() } # 构建add_text_segment参数（只保存用户传入的参数） add_text_segment_params = { "text": text, "timerange": timerange_data } # 只添加用户明确传入的可选参数 if font is not None: add_text_segment_params["font"] = font if style is not None: add_text_segment_params["style"] = style if clip_settings is not None: add_text_segment_params["clip_settings"] = clip_settings if border is not None: add_text_segment_params["border"] = border if background is not None: add_text_segment_params["background"] = background # 确定使用的轨道名称（参数优先，然后是实例属性） final_track_name = track_name or self.track_name # 验证轨道 if final_track_name: self._validate_track_for_text(final_track_name) # 验证片段重叠 if final_track_name: validate_overlap(self.draft_id, "text", final_track_name, timerange_data) # 构建完整的文本片段数据 text_segment_data = { "text_segment_id": self.text_segment_id, "operation": "add_text_segment", "add_text_segment": add_text_segment_params } # 只在指定了轨道名称时才添加track_name字段 if final_track_name: text_segment_data["track_name"] = final_track_name # 保存到文件 self.add_json_to_file(text_segment_data) return add_text_segment_params