add_audio_keyframe

Instructions

Implementation Reference

• jianyingdraft/tool/audio_tool.py:287-365 (handler)

  The MCP tool handler for 'add_audio_keyframe', decorated with @mcp.tool(). Validates inputs (audio_segment_id, time_offset, volume), retrieves draft_id and track_name from index_manager, and delegates to add_audio_keyframe_service.

  @mcp.tool()
  def add_audio_keyframe(
          audio_segment_id: str,
          time_offset: str,
          volume: float
  ) -> ToolResponse:
      """
      为音频片段添加音量关键帧
  
      Args:
          audio_segment_id: 音频片段ID，通过add_audio_segment获得
          time_offset: 关键帧的时间偏移量，格式如 "0s", "1.5s", "500ms"
          volume: 音量在time_offset处的值，范围通常0.0-1.0，也可以大于1.0实现增益效果
      """
      # 参数验证
      if not time_offset:
          return ToolResponse(
              success=False,
              message="时间偏移量不能为空"
          )
  
      if volume < 0.0:
          return ToolResponse(
              success=False,
              message=f"音量值不能为负数，当前值: {volume}"
          )
  
      # 时间格式验证
      def validate_time_offset(time_offset: str) -> bool:
          """验证时间偏移量格式是否正确"""
          if not time_offset:
              return False
          # 检查是否以s或ms结尾
          if not (time_offset.endswith('s') or time_offset.endswith('ms')):
              return False
          # 检查数字部分
          try:
              if time_offset.endswith('ms'):
                  float(time_offset[:-2])
              else:
                  float(time_offset[:-1])
              return True
          except ValueError:
              return False
  
      if not validate_time_offset(time_offset):
          return ToolResponse(
              success=False,
              message=f"无效的时间偏移量格式: {time_offset}，正确格式如 '1.5s', '500ms'"
          )
  
      # 通过audio_segment_id获取相关信息
      draft_id = index_manager.get_draft_id_by_audio_segment_id(audio_segment_id)
      track_info = index_manager.get_track_info_by_audio_segment_id(audio_segment_id)
  
      if not draft_id:
          return ToolResponse(
              success=False,
              message=f"未找到音频片段ID对应的草稿: {audio_segment_id}"
          )
  
      if not track_info:
          return ToolResponse(
              success=False,
              message=f"未找到音频片段ID对应的轨道信息: {audio_segment_id}"
          )
  
      track_name = track_info.get("track_name")
  
      # 调用服务层处理业务逻辑
      result = add_audio_keyframe_service(
          draft_id=draft_id,
          audio_segment_id=audio_segment_id,
          time_offset=time_offset,
          volume=volume,
          track_name=track_name
      )
  
      return result

• jianyingdraft/services/audio_service.py:246-315 (helper)

  Service layer implementation add_audio_keyframe_service. Instantiates AudioSegment(draft_id, audio_segment_id=audio_segment_id), calls its add_keyframe(time_offset, volume) method, handles exceptions, and constructs ToolResponse.

  def add_audio_keyframe_service(
      draft_id: str,
      audio_segment_id: str,
      time_offset: str,
      volume: float,
      track_name: Optional[str] = None
  ) -> ToolResponse:
      """
      音频关键帧添加服务 - 为音频片段添加音量关键帧
  
      Args:
          draft_id: 草稿ID
          audio_segment_id: 音频片段ID
          time_offset: 关键帧的时间偏移量，格式如 "0s"、"1.5s"
          volume: 音量在time_offset处的值，范围通常0.0-1.0
          track_name: 轨道名称（可选）
  
      Returns:
          ToolResponse: 包含操作结果的响应对象
      """
      try:
          # 创建AudioSegment实例，传入audio_segment_id
          audio_segment = AudioSegment(draft_id, audio_segment_id=audio_segment_id, track_name=track_name)
  
          # 调用音频关键帧添加方法
          result_data = audio_segment.add_keyframe(
              time_offset=time_offset,
              volume=volume
          )
  
          # 构建返回数据
          response_data = {
              "audio_segment_id": audio_segment_id,
              "draft_id": draft_id,
              "time_offset": time_offset,
              "volume": volume,
              "add_keyframe": result_data
          }
  
          # 添加可选参数到返回数据
          if track_name:
              response_data["track_name"] = track_name
  
          return ToolResponse(
              success=True,
              message=f"音频关键帧添加成功: 时间{time_offset}, 音量{volume}",
              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/audio_tool.py:9-9 (registration)

  Import of add_audio_keyframe_service from services.audio_service, required for the tool handler.

  add_audio_fade_service, add_audio_keyframe_service