add_video_keyframe

Instructions

# 在1秒时设置旋转角度
add_video_keyframe("video_segment_id", "rotation", "1s", 45.0)

# 在2秒时设置透明度
add_video_keyframe("video_segment_id", "alpha", "2s", 0.5)

Implementation Reference

• jianyingdraft/tool/video_tool.py:294-358 (handler)

  MCP tool handler for 'add_video_keyframe'. Handles input validation, retrieves draft and track information using index_manager, and delegates to the service function add_video_keyframe_service.

  @mcp.tool()
  def add_video_keyframe(
          video_segment_id: str,
          property_name: str,
          time_offset: str,
          value: float
  ) -> ToolResponse:
      """
      为视频片段添加关键帧
  
      Args:
          video_segment_id: 视频片段ID，通过add_video_segment获得
          property_name: 属性名称，可选参数如下：
              position_x：右移为正, 此处的数值应该为`剪映中显示的值` / `草稿宽度`, 也即单位是半个画布宽
              position_y：上移为正, 此处的数值应该为`剪映中显示的值` / `草稿高度`, 也即单位是半个画布高
              rotation：顺时针旋转的**角度**
              scale_x：单独控制X轴缩放比例(1.0为不缩放), 与`uniform_scale`互斥
              scale_y：单独控制Y轴缩放比例(1.0为不缩放), 与`uniform_scale`互斥
              uniform_scale：同时控制X轴及Y轴缩放比例(1.0为不缩放), 与`scale_x`和`scale_y`互斥
              alpha：不透明度, 1.0为完全不透明, 仅对`VideoSegment`有效
              saturation：饱和度, 0.0为原始饱和度, 范围为-1.0到1.0
              contrast：对比度, 0.0为原始对比度, 范围为-1.0到1.0
              brightness：亮度, 0.0为原始亮度, 范围为-1.0到1.0
              volume：音量, 1.0为原始音量
          time_offset: 时间偏移量，格式如 "0.5s", "1s" 等
          value: 属性值
      Examples:
          # 在0.5秒时设置水平位置
          add_video_keyframe("video_segment_id", "position_x", "0.5s", 0.2)
  
          # 在1秒时设置旋转角度
          add_video_keyframe("video_segment_id", "rotation", "1s", 45.0)
  
          # 在2秒时设置透明度
          add_video_keyframe("video_segment_id", "alpha", "2s", 0.5)
      """
      # 通过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_keyframe_service(
          draft_id=draft_id,
          video_segment_id=video_segment_id,
          property_name=property_name,
          time_offset=time_offset,
          value=value,
          track_name=track_name
      )
  
      return result

• jianyingdraft/services/video_service.py:254-327 (helper)

  Helper service function that instantiates VideoSegment and calls its add_keyframe method to perform the actual keyframe addition logic, with error handling and response formatting.

  def add_video_keyframe_service(
      draft_id: str,
      video_segment_id: str,
      property_name: str,
      time_offset: str,
      value: float,
      track_name: Optional[str] = None
  ) -> ToolResponse:
      """
      视频关键帧添加服务 - 为视频片段添加关键帧
  
      Args:
          draft_id: 草稿ID
          video_segment_id: 视频片段ID
          property_name: 属性名称，如 "position_x", "rotation", "alpha" 等
          time_offset: 时间偏移量，如 "0.5s", "1s" 等
          value: 属性值
          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_keyframe(
              property_name=property_name,
              time_offset=time_offset,
              value=value
          )
  
          # 构建返回数据
          response_data = {
              "video_segment_id": video_segment_id,
              "draft_id": draft_id,
              "property_name": property_name,
              "time_offset": time_offset,
              "value": value,
              "add_keyframe": result_data
          }
  
          # 如果有轨道名称，添加到返回数据中
          if track_name:
              response_data["track_name"] = track_name
  
          return ToolResponse(
              success=True,
              message=f"视频关键帧添加成功: {property_name}={value} at {time_offset}",
              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)}"
          )

• jianyingdraft/tool/video_tool.py:8-11 (registration)

  Import statement registering the dependency on add_video_keyframe_service in the video tool module.

  from jianyingdraft.services.video_service import add_video_segment_service, add_video_animation_service, \
      add_video_transition_service, add_video_keyframe_service, add_video_filter_service, \
      add_video_background_filling_service, \
      add_video_mask_service, add_video_effect_service