analyze_audio

Instructions

Implementation Reference

• gemini_audio/mcp_server.py:20-67 (handler)

  The MCP handler function for the 'analyze_audio' tool, which handles parameters, loads system instructions if provided, and delegates to analyze_audio_content.

  @mcp.tool()
  def analyze_audio( # pylint: disable=too-many-arguments, too-many-positional-arguments
          audio_path: str,
          prompt: str = "Describe this audio.",
          json_path: Optional[str] = None,
          json_context: Optional[str] = None,
          instruction_file: Optional[str] = None,
          model: str = "gemini-3-pro-preview"
  ) -> str:
      """
      Analyze an audio file using Google Gemini.
  
      Args:
          audio_path: Path to the audio file (wav, mp3, etc.)
          prompt: The prompt to send to Gemini.
          json_path: Optional path to a JSON file to provide as context.
          json_context: Optional JSON string to provide as context (overrides json_path if provided).
          instruction_file: Optional path to a text file containing system instructions.
          model: The Gemini model to use.
      """
      api_key = os.getenv("GOOGLE_API_KEY")
      if not api_key:
          return "Error: GOOGLE_API_KEY not set."
  
      system_instruction = None
      if instruction_file:
          if os.path.exists(instruction_file):
              try:
                  with open(instruction_file, 'r', encoding='utf-8') as f:
                      system_instruction = f.read()
              except Exception as e: # pylint: disable=broad-exception-caught
                  return f"Error reading instruction file: {str(e)}"
          else:
              return f"Error: Instruction file not found at {instruction_file}"
  
      try:
          return analyze_audio_content(
              audio_path,
              prompt,
              json_path,
              json_context,
              model,
              api_key,
              system_instruction
          )
      except Exception as e: # pylint: disable=broad-exception-caught
          return f"Error analyzing audio: {str(e)}"

• gemini_audio/analyze_audio.py:43-129 (helper)

  Core helper function implementing the audio analysis logic: uploads audio to Gemini, handles JSON context, waits for processing, configures model, and generates response.

  def analyze_audio_content( # pylint: disable=too-many-arguments, too-many-locals, too-many-positional-arguments
          audio_path,
          prompt,
          json_path=None,
          json_context=None,
          model_name="gemini-3-pro-preview",
          api_key=None,
          system_instruction=None
  ):
      """
      Analyzes audio content using Google Gemini.
  
      Args:
          audio_path (str): Path to the audio file.
          prompt (str): Prompt for the model.
          json_path (str, optional): Path to a JSON context file.
          json_context (str, optional): JSON context string.
          model_name (str, optional): Gemini model name.
          api_key (str, optional): Google API key.
          system_instruction (str, optional): System instruction for the model.
  
      Returns:
          str: The model's response.
      """
      if not api_key:
          raise ValueError("API key is required")
  
      genai.configure(api_key=api_key) # type: ignore
  
      files_to_upload = []
  
      # Upload Audio
      if not os.path.exists(audio_path):
          return f"Error: Audio file not found at {audio_path}"
  
      print(f"Uploading audio: {audio_path}")
      # Simple mime type detection or default to wav/mp3
      mime_type = "audio/wav"
      if audio_path.lower().endswith(".mp3"):
          mime_type = "audio/mp3"
  
      audio_file = upload_to_gemini(audio_path, mime_type=mime_type)
      files_to_upload.append(audio_file)
  
      # Handle JSON
      json_content = ""
      if json_context:
          json_content = json_context
      elif json_path:
          if os.path.exists(json_path):
              print(f"Reading JSON: {json_path}")
              with open(json_path, 'r', encoding='utf-8') as f:
                  json_content = f.read()
          else:
              print(f"Warning: JSON file not found at {json_path}")
  
      # Wait for processing
      wait_for_files_active(files_to_upload)
  
      # Create the model
      generation_config = {
          "temperature": 1,
          "top_p": 0.95,
          "top_k": 64,
          "max_output_tokens": 8192,
          "response_mime_type": "text/plain",
      }
  
      model = genai.GenerativeModel( # type: ignore
          model_name=model_name,
          generation_config=generation_config, # type: ignore
          system_instruction=system_instruction
      )
  
      # Construct the prompt parts
      prompt_parts = []
      if json_content:
          prompt_parts.append(f"Context JSON:\n{json_content}\n")
  
      prompt_parts.append(prompt)
      prompt_parts.append(audio_file)
  
      # Generate content
      print("Generating content...")
      response = model.generate_content(prompt_parts)
  
      return response.text

• gemini_audio/analyze_audio.py:13-20 (helper)

  Helper function to upload audio file to Gemini API.

  def upload_to_gemini(path, mime_type=None):
      """Uploads the given file to Gemini.
  
      See https://ai.google.dev/gemini-api/docs/prompting_with_media
      """
      file = genai.upload_file(path, mime_type=mime_type) # type: ignore
      print(f"Uploaded file '{file.display_name}' as: {file.uri}")
      return file

• gemini_audio/analyze_audio.py:22-41 (helper)

  Helper function to wait for uploaded files to be processed and active in Gemini API.

  def wait_for_files_active(files):
      """Waits for the given files to be active.
  
      Some files uploaded to the Gemini API need to be processed before they can
      be used as prompt inputs. The status can be seen by querying the file's
      "state" field.
  
      This implementation relies on the file's "name" field to perform the query,
      and if the state is not ACTIVE, it waits 10 seconds and checks again.
      """
      print("Waiting for file processing...")
      for name in (file.name for file in files):
          file = genai.get_file(name) # type: ignore
          while file.state.name == "PROCESSING":
              print(".", end="", flush=True)
              time.sleep(10)
              file = genai.get_file(name) # type: ignore
          if file.state.name != "ACTIVE":
              raise RuntimeError(f"File {file.name} failed to process")
      print("...all files ready")

• gemini_audio/mcp_server.py:68-75 (registration)

  MCP server run block that registers and runs the tools, including the help mentioning analyze_audio.

  if __name__ == "__main__":
      if "--help" in sys.argv:
          print("GeminiAudio MCP Server")
          print("Run this server using an MCP client (e.g. Claude Desktop, VS Code MCP extension).")
          print("\nTools:")
          print("  - analyze_audio: Analyze an audio file using Google Gemini.")
          sys.exit(0)
      mcp.run()