JianYing MCP

Instructions

Implementation Reference

• jianyingdraft/tool/audio_tool.py:103-205 (handler)

  MCP tool handler for 'add_audio_effect'. Performs parameter validation, checks if effect exists using JianYingResourceManager, retrieves draft and track info from index_manager, and calls add_audio_effect_service.

  @mcp.tool()
  def add_audio_effect(
          audio_segment_id: str,
          effect_type: str,
          effect_name: str,
          params: Optional[List[Optional[float]]] = None
  ) -> ToolResponse:
      """
      为音频片段添加特效
  
      Args:
          audio_segment_id: 音频片段ID，通过add_audio_segment获得
          effect_type: 特效类型，支持以下类型：
              - "AudioSceneEffectType": 场景音效（如雨声、风声等）
              - "ToneEffectType": 音调特效（如机器人、电音等）
              - "SpeechToSongType": 语音转歌声特效（如Lofi、流行等）
          effect_name: 特效名称，如 "雨声", "机器人", "Lofi", "电音", "回声" 等，可以使用find_effects_by_type工具，资源类型选择AudioSceneEffectType、ToneEffectType、SpeechToSongType，从而获取特效类型有哪些
          params: 特效参数列表（可选），参数范围0-100，具体参数数量和含义取决于特效类型，一般不做修改
      """
      # 参数验证
      valid_types = ["AudioSceneEffectType", "ToneEffectType", "SpeechToSongType"]
      if effect_type not in valid_types:
          return ToolResponse(
              success=False,
              message=f"无效的特效类型 '{effect_type}'，支持的类型: {', '.join(valid_types)}"
          )
  
      # 验证参数范围
      if params:
          for i, param in enumerate(params):
              if param is not None and not (0.0 <= param <= 100.0):
                  return ToolResponse(
                      success=False,
                      message=f"参数{i + 1}超出范围，必须在0-100之间，当前值: {param}"
                  )
  
      # 音频特效存在性验证（音频特效使用 name 字段）
      from jianyingdraft.utils.effect_manager import JianYingResourceManager
      manager = JianYingResourceManager()
  
      effects = manager.find_by_type(
          effect_type=effect_type,
          keyword=effect_name,
          limit=1
      )
  
      # 检查是否找到完全匹配的特效
      exact_match = False
      if effects:
          for effect in effects:
              if effect.get('name') == effect_name:
                  exact_match = True
                  break
  
      if not effects or not exact_match:
          # 获取建议特效
          effect_suggestions = manager.find_by_type(effect_type, keyword=effect_name)
  
          all_suggestions = []
          for effect in effect_suggestions:
              if effect.get('name'):
                  all_suggestions.append(effect.get('name'))
  
          return ToolResponse(
              success=False,
              message=f"在 {effect_type} 中未找到特效 '{effect_name}',请确认名称是否正确，或使用相关特效: {', '.join(all_suggestions)}",
              data={
                  "error_type": "effect_not_found",
                  "effect_type": effect_type,
                  "effect_name": effect_name,
                  "suggestions": all_suggestions
              }
          )
  
      # 通过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_effect_service(
          draft_id=draft_id,
          audio_segment_id=audio_segment_id,
          effect_type=effect_type,
          effect_name=effect_name,
          params=params,
          track_name=track_name
      )
  
      return result

• jianyingdraft/services/audio_service.py:99-172 (helper)

  Helper service layer that creates an AudioSegment instance and invokes its add_effect method to apply the audio effect to the specified segment.

  def add_audio_effect_service(
      draft_id: str,
      audio_segment_id: str,
      effect_type: str,
      effect_name: str,
      params: Optional[List[Optional[float]]] = None,
      track_name: Optional[str] = None
  ) -> ToolResponse:
      """
      音频特效添加服务 - 为音频片段添加特效
  
      Args:
          draft_id: 草稿ID
          audio_segment_id: 音频片段ID
          effect_type: 特效类型，"AudioSceneEffectType"、"ToneEffectType"、"SpeechToSongType"
          effect_name: 特效名称，如 "雨声"、"机器人"、"Lofi" 等
          params: 特效参数列表（可选），参数范围0-100
          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_effect(
              effect_type=effect_type,
              effect_name=effect_name,
              params=params
          )
  
          # 构建返回数据
          response_data = {
              "audio_segment_id": audio_segment_id,
              "draft_id": draft_id,
              "effect_type": effect_type,
              "effect_name": effect_name,
              "add_effect": result_data
          }
  
          # 添加可选参数到返回数据
          if params:
              response_data["params"] = params
          if track_name:
              response_data["track_name"] = track_name
  
          return ToolResponse(
              success=True,
              message=f"音频特效添加成功: {effect_type}.{effect_name}",
              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:15-15 (registration)

  Function that registers multiple audio tools including 'add_audio_effect' with the FastMCP server instance.

  def audio_tools(mcp: FastMCP):