detect_clipping

Instructions

Implementation Reference

• src/reaper_mcp/analysis_tools.py:70-104 (handler)

  The main handler for the 'detect_clipping' tool. Renders the project to a temp WAV file, reads it with soundfile, converts to mono, counts samples >= 0.9999 (clip threshold), computes peak level in dB, and returns clipping metrics.

  def detect_clipping() -> dict:
      """
      Render the project and detect digital clipping (samples at or above 0 dBFS).
      Returns clipped sample count, peak level in dB, and whether clipping was found.
      """
      try:
          import soundfile as sf
          from reaper_mcp.render_tools import render_to_temp_file
  
          tmp = render_to_temp_file()
          try:
              data, rate = sf.read(tmp)
          finally:
              if os.path.exists(tmp):
                  os.unlink(tmp)
  
          if data.ndim > 1:
              mono = np.max(np.abs(data), axis=1)
          else:
              mono = np.abs(data)
  
          clip_threshold = 0.9999
          clipped_samples = int(np.sum(mono >= clip_threshold))
          peak_linear = float(np.max(mono))
          peak_db = float(20 * np.log10(peak_linear)) if peak_linear > 0 else -120.0
  
          return {
              "success": True,
              "clipping_detected": clipped_samples > 0,
              "clipped_samples": clipped_samples,
              "peak_db": round(peak_db, 2),
              "peak_linear": round(peak_linear, 4),
          }
      except Exception as e:
          return {"success": False, "error": str(e)}

• src/reaper_mcp/server.py:18-28 (registration)

  Registration of the analysis_tools module's register_tools function, which wraps detect_clipping (and all other analysis tools) with @mcp.tool() decorator.

  from reaper_mcp.analysis_tools import register_tools as _reg_analysis
  
  _reg_project(mcp)
  _reg_track(mcp)
  _reg_midi(mcp)
  _reg_fx(mcp)
  _reg_audio(mcp)
  _reg_mixing(mcp)
  _reg_render(mcp)
  _reg_mastering(mcp)
  _reg_analysis(mcp)

• src/reaper_mcp/analysis_tools.py:69-104 (registration)

  The @mcp.tool() decorator on the detect_clipping function that registers it as an MCP tool within the analysis_tools module.

  @mcp.tool()
  def detect_clipping() -> dict:
      """
      Render the project and detect digital clipping (samples at or above 0 dBFS).
      Returns clipped sample count, peak level in dB, and whether clipping was found.
      """
      try:
          import soundfile as sf
          from reaper_mcp.render_tools import render_to_temp_file
  
          tmp = render_to_temp_file()
          try:
              data, rate = sf.read(tmp)
          finally:
              if os.path.exists(tmp):
                  os.unlink(tmp)
  
          if data.ndim > 1:
              mono = np.max(np.abs(data), axis=1)
          else:
              mono = np.abs(data)
  
          clip_threshold = 0.9999
          clipped_samples = int(np.sum(mono >= clip_threshold))
          peak_linear = float(np.max(mono))
          peak_db = float(20 * np.log10(peak_linear)) if peak_linear > 0 else -120.0
  
          return {
              "success": True,
              "clipping_detected": clipped_samples > 0,
              "clipped_samples": clipped_samples,
              "peak_db": round(peak_db, 2),
              "peak_linear": round(peak_linear, 4),
          }
      except Exception as e:
          return {"success": False, "error": str(e)}

• src/reaper_mcp/render_tools.py:47-56 (helper)

  The render_to_temp_file helper function used by detect_clipping to render the project to a temporary WAV file for analysis.

  def render_to_temp_file(sample_rate: int = 48000) -> str:
      """
      Render the current project to a temporary WAV file and return its path.
      Used by analysis and mastering tools. Caller is responsible for deleting the file.
      """
      import tempfile
      tmp = tempfile.mktemp(suffix=".wav")
      _set_render_settings(tmp, "wav", sample_rate, 24, 2, bounds=0)
      RPR.Main_OnCommand(41824, 0)
      return tmp