add_volume_automation

Instructions

Implementation Reference

• src/reaper_mcp/mixing_tools.py:20-43 (handler)

  The actual tool handler function 'add_volume_automation' that adds a volume automation point on a track. It gets the project, finds the track by index, looks up the 'Volume' envelope, converts dB to linear, inserts the point, sorts points, and returns success/error.

  def add_volume_automation(track_index: int, position: float, value_db: float) -> dict:
      """
      Add a volume automation point on a track.
      The volume envelope must be visible in REAPER (right-click track > Show envelope).
      position: time in seconds. value_db: volume level in dB.
      """
      try:
          project = get_project()
          track = project.tracks[track_index]
          envelope = RPR.GetTrackEnvelopeByName(track.id, "Volume")
          if not envelope:
              return {
                  "success": False,
                  "error": (
                      "Volume envelope not found. Show it first: right-click the track "
                      "in REAPER and choose 'Show envelope for track volume'."
                  ),
              }
          linear_val = _db_to_linear(value_db)
          RPR.InsertEnvelopePoint(envelope, position, linear_val, 0, 0, False, True)
          RPR.Envelope_SortPoints(envelope)
          return {"success": True, "track_index": track_index, "position": position, "value_db": value_db}
      except Exception as e:
          return {"success": False, "error": str(e)}

• src/reaper_mcp/mixing_tools.py:20-25 (schema)

  The function signature serves as the schema: accepts track_index (int), position (float seconds), and value_db (float dB). Returns a dict with success, track_index, position, value_db or error.

  def add_volume_automation(track_index: int, position: float, value_db: float) -> dict:
      """
      Add a volume automation point on a track.
      The volume envelope must be visible in REAPER (right-click track > Show envelope).
      position: time in seconds. value_db: volume level in dB.
      """

• src/reaper_mcp/mixing_tools.py:17-20 (registration)

  The 'add_volume_automation' tool is registered via the @mcp.tool() decorator inside the register_tools(mcp) function in mixing_tools.py.

  def register_tools(mcp):
  
      @mcp.tool()
      def add_volume_automation(track_index: int, position: float, value_db: float) -> dict:

• src/reaper_mcp/server.py:15-25 (registration)

  In server.py, mixing_tools.register_tools is imported as _reg_mixing and called with the mcp instance (line 25), which triggers the decorator-based registration of all mixing tools including add_volume_automation.

  from reaper_mcp.mixing_tools import register_tools as _reg_mixing
  from reaper_mcp.render_tools import register_tools as _reg_render
  from reaper_mcp.mastering_tools import register_tools as _reg_mastering
  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)

• src/reaper_mcp/mixing_tools.py:11-14 (helper)

  The _db_to_linear helper function converts dB values to linear scale, used by add_volume_automation to convert the value_db parameter before inserting the envelope point.

  def _db_to_linear(db: float) -> float:
      if db <= -150:
          return 0.0
      return 10 ** (db / 20.0)