isolate_audio

Instructions

⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.

Implementation Reference

• elevenlabs_mcp/server.py:547-568 (handler)

  The isolate_audio tool handler function. It reads an input audio file, calls ElevenLabs' audio_isolation.convert API to isolate audio, and returns the result via handle_output_mode.

  @mcp.tool(
      annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
      description=f"""Isolate audio from a file. {get_output_mode_description(output_mode)}.
  
      ⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
      """
  )
  def isolate_audio(
      input_file_path: str, output_directory: str | None = None
  ) -> Union[TextContent, EmbeddedResource]:
      file_path = handle_input_file(input_file_path)
      output_path = make_output_path(output_directory, base_path)
      output_file_name = make_output_file("iso", file_path.name, "mp3")
      with file_path.open("rb") as f:
          audio_bytes = f.read()
      audio_data = client.audio_isolation.convert(
          audio=audio_bytes,
      )
      audio_bytes = b"".join(audio_data)
  
      # Handle different output modes
      return handle_output_mode(audio_bytes, output_path, output_file_name, output_mode)

• elevenlabs_mcp/server.py:547-553 (registration)

  The tool registration via @mcp.tool decorator with annotations and description.

  @mcp.tool(
      annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True),
      description=f"""Isolate audio from a file. {get_output_mode_description(output_mode)}.
  
      ⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
      """
  )

• elevenlabs_mcp/utils.py:126-148 (helper)

  Helper function handle_input_file validates and resolves the input file path, used by isolate_audio.

  def handle_input_file(file_path: str, audio_content_check: bool = True) -> Path:
      if not os.path.isabs(file_path) and not os.environ.get("ELEVENLABS_MCP_BASE_PATH"):
          make_error(
              "File path must be an absolute path if ELEVENLABS_MCP_BASE_PATH is not set"
          )
      path = Path(file_path)
      if not path.exists() and path.parent.exists():
          parent_directory = path.parent
          similar_files = try_find_similar_files(path.name, parent_directory)
          similar_files_formatted = ",".join([str(file) for file in similar_files])
          if similar_files:
              make_error(
                  f"File ({path}) does not exist. Did you mean any of these files: {similar_files_formatted}?"
              )
          make_error(f"File ({path}) does not exist")
      elif not path.exists():
          make_error(f"File ({path}) does not exist")
      elif not path.is_file():
          make_error(f"File ({path}) is not a file")
  
      if audio_content_check and not check_audio_file(path):
          make_error(f"File ({path}) is not an audio or video file")
      return path

• elevenlabs_mcp/utils.py:345-395 (helper)

  Helper function handle_output_mode routes the output to files/resources/both modes, used by isolate_audio.

  def handle_output_mode(
      file_data: bytes,
      output_path: Path,
      filename: str,
      output_mode: str,
      success_message: str = None,
  ) -> Union[TextContent, EmbeddedResource]:
      """
      Handle different output modes for file generation.
  
      Args:
          file_data: Raw file data as bytes
          output_path: Path where file should be saved
          filename: Name of the file
          output_mode: Output mode ('files', 'resources', or 'both')
          success_message: Custom success message for files mode (optional)
  
      Returns:
          Union[TextContent, EmbeddedResource]: TextContent for 'files' mode,
                                              EmbeddedResource for 'resources' and 'both' modes
      """
      file_extension = Path(filename).suffix.lstrip(".")
      full_file_path = output_path / filename
  
      if output_mode == "files":
          # Save to disk and return TextContent with success message
          output_path.mkdir(parents=True, exist_ok=True)
          with open(full_file_path, "wb") as f:
              f.write(file_data)
  
          if success_message and "{file_path}" in success_message:
              message = success_message.replace("{file_path}", str(full_file_path))
          else:
              message = success_message or f"Success. File saved as: {full_file_path}"
          return TextContent(type="text", text=message)
  
      elif output_mode == "resources":
          # Return as EmbeddedResource without saving to disk
          return create_resource_response(file_data, filename, file_extension, directory=output_path)
  
      elif output_mode == "both":
          # Save to disk AND return as EmbeddedResource
          output_path.mkdir(parents=True, exist_ok=True)
          with open(full_file_path, "wb") as f:
              f.write(file_data)
          return create_resource_response(file_data, filename, file_extension, directory=output_path)
  
      else:
          raise ValueError(
              f"Invalid output mode: {output_mode}. Must be 'files', 'resources', or 'both'"
          )

• elevenlabs_mcp/utils.py:31-37 (helper)

  Helper function make_output_file generates the output file name with 'iso_' prefix and mp3 extension, used by isolate_audio.

  def make_output_file(
      tool: str, text: str, extension: str, full_id: bool = False
  ) -> Path:
      id = text if full_id else text[:5]
  
      output_file_name = f"{tool}_{id.replace(' ', '_')}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.{extension}"
      return Path(output_file_name)