@mthines/reaper-mcp 0.6.0 → 0.8.0

package/reaper/mcp_bridge.lua

@@ -11,7 +11,7 @@
 
 local POLL_INTERVAL = 0.030 -- 30ms between polls
 local HEARTBEAT_INTERVAL = 1.0 -- write heartbeat every 1s
-local MCP_ANALYZER_FX_NAME = "mcp_analyzer" -- JSFX analyzer name
+local MCP_ANALYZER_FX_NAME = "reaper-mcp/mcp_analyzer" -- JSFX analyzer name
 
 -- Determine bridge directory (REAPER resource path / Scripts / mcp_bridge_data)
 local bridge_dir = reaper.GetResourcePath() .. "/Scripts/mcp_bridge_data/"
@@ -26,57 +26,140 @@ local last_heartbeat = 0
 -- JSON Parser (minimal, sufficient for our command format)
 -- =============================================================================
 
-local function json_decode(str)
-  -- Use REAPER 7+ built-in JSON if available, otherwise basic parser
-  if reaper.CF_Json_Parse then
-    local ok, val = reaper.CF_Json_Parse(str)
-    if ok then return val end
+-- Helper: extract a JSON string value starting at pos (after the opening quote).
+-- Handles escaped quotes (\") and other escape sequences.
+local function extract_json_string(str, pos)
+  local result = {}
+  local i = pos
+  while i <= #str do
+    local ch = str:sub(i, i)
+    if ch == '\\' then
+      local next_ch = str:sub(i + 1, i + 1)
+      if next_ch == '"' then
+        result[#result + 1] = '"'
+      elseif next_ch == '\\' then
+        result[#result + 1] = '\\'
+      elseif next_ch == 'n' then
+        result[#result + 1] = '\n'
+      elseif next_ch == 't' then
+        result[#result + 1] = '\t'
+      elseif next_ch == '/' then
+        result[#result + 1] = '/'
+      else
+        result[#result + 1] = next_ch
+      end
+      i = i + 2
+    elseif ch == '"' then
+      return table.concat(result), i + 1  -- return string and position after closing quote
+    else
+      result[#result + 1] = ch
+      i = i + 1
+    end
   end
+  return nil, i  -- unterminated string
+end
 
-  -- Fallback: use Lua pattern matching for our simple JSON format
-  -- This handles the flat command objects we receive
+-- Parse a flat JSON object with string/number values in params.
+-- Handles escaped quotes in string values (e.g. JSON arrays passed as strings).
+local function parse_flat_object(str)
   local obj = {}
-  -- Extract string values: "key": "value"
-  for k, v in str:gmatch('"([^"]+)"%s*:%s*"([^"]*)"') do
-    obj[k] = v
-  end
-  -- Extract number values: "key": 123.456
-  for k, v in str:gmatch('"([^"]+)"%s*:%s*(-?%d+%.?%d*)') do
-    if not obj[k] then obj[k] = tonumber(v) end
-  end
-  -- Extract nested params object
-  local params_str = str:match('"params"%s*:%s*(%b{})')
-  if params_str then
-    obj.params = {}
-    for k, v in params_str:gmatch('"([^"]+)"%s*:%s*"([^"]*)"') do
-      obj.params[k] = v
-    end
-    for k, v in params_str:gmatch('"([^"]+)"%s*:%s*(-?%d+%.?%d*)') do
-      if not obj.params[k] then obj.params[k] = tonumber(v) end
+  local i = 1
+  while i <= #str do
+    -- Find a key
+    local key_start = str:find('"', i)
+    if not key_start then break end
+    local key_end = str:find('"', key_start + 1)
+    if not key_end then break end
+    local key = str:sub(key_start + 1, key_end - 1)
+
+    -- Find the colon
+    local colon = str:find(':', key_end + 1)
+    if not colon then break end
+
+    -- Skip whitespace after colon
+    local val_start = str:match('^%s*()', colon + 1)
+
+    local ch = str:sub(val_start, val_start)
+    if ch == '"' then
+      -- String value (handles escaped quotes)
+      local val, next_pos = extract_json_string(str, val_start + 1)
+      if val then
+        obj[key] = val
+        i = next_pos
+      else
+        i = val_start + 1
+      end
+    elseif ch == '{' then
+      -- Nested object — extract with balanced braces
+      local nested = str:match('%b{}', val_start)
+      if nested then
+        obj[key] = parse_flat_object(nested)
+        i = val_start + #nested
+      else
+        i = val_start + 1
+      end
+    elseif ch == '[' then
+      -- Array — extract with balanced brackets
+      local arr = str:match('%b[]', val_start)
+      if arr then
+        obj[key] = arr  -- keep as string for json_decode_array to parse later
+        i = val_start + #arr
+      else
+        i = val_start + 1
+      end
+    elseif ch:match('[%d%-]') then
+      -- Number
+      local num_str = str:match('-?%d+%.?%d*', val_start)
+      if num_str then
+        obj[key] = tonumber(num_str)
+        i = val_start + #num_str
+      else
+        i = val_start + 1
+      end
+    elseif str:sub(val_start, val_start + 3) == 'true' then
+      obj[key] = true
+      i = val_start + 4
+    elseif str:sub(val_start, val_start + 4) == 'false' then
+      obj[key] = false
+      i = val_start + 5
+    elseif str:sub(val_start, val_start + 3) == 'null' then
+      i = val_start + 4
+    else
+      i = val_start + 1
     end
   end
   return obj
 end
 
--- Fallback JSON array-of-objects parser for when CF_Json_Parse is unavailable.
--- Handles: [{"key":val,...}, {"key":val,...}, ...]
-local function json_decode_array(str)
+local function json_decode(str)
+  -- Use REAPER 7+ built-in JSON if available, otherwise basic parser
   if reaper.CF_Json_Parse then
     local ok, val = reaper.CF_Json_Parse(str)
     if ok then return val end
   end
 
+  -- Fallback: parse the command JSON using our robust parser
+  -- that handles escaped quotes in string values (needed for batch commands)
+  return parse_flat_object(str)
+end
+
+-- Parse a JSON array of objects. Accepts either a Lua table (already parsed by
+-- CF_Json_Parse) or a JSON string. Falls back to extracting each {...} and
+-- parsing with parse_flat_object.
+local function json_decode_array(input)
+  -- If already a table (e.g. CF_Json_Parse decoded it), return directly
+  if type(input) == "table" then return input end
+  if type(input) ~= "string" then return nil end
+
+  if reaper.CF_Json_Parse then
+    local ok, val = reaper.CF_Json_Parse(input)
+    if ok then return val end
+  end
+
   -- Fallback: extract each {...} from the array and parse individually
   local arr = {}
-  for obj_str in str:gmatch("%b{}") do
-    local obj = {}
-    for k, v in obj_str:gmatch('"([^"]+)"%s*:%s*"([^"]*)"') do
-      obj[k] = v
-    end
-    for k, v in obj_str:gmatch('"([^"]+)"%s*:%s*(-?%d+%.?%d*)') do
-      if not obj[k] then obj[k] = tonumber(v) end
-    end
-    arr[#arr + 1] = obj
+  for obj_str in input:gmatch("%b{}") do
+    arr[#arr + 1] = parse_flat_object(obj_str)
   end
   if #arr > 0 then return arr end
   return nil
@@ -924,9 +1007,9 @@ end
 -- Phase 4: Custom JSFX analyzer handlers
 -- =============================================================================
 
-local MCP_LUFS_METER_FX_NAME        = "mcp_lufs_meter"
-local MCP_CORRELATION_METER_FX_NAME = "mcp_correlation_meter"
-local MCP_CREST_FACTOR_FX_NAME      = "mcp_crest_factor"
+local MCP_LUFS_METER_FX_NAME        = "reaper-mcp/mcp_lufs_meter"
+local MCP_CORRELATION_METER_FX_NAME = "reaper-mcp/mcp_correlation_meter"
+local MCP_CREST_FACTOR_FX_NAME      = "reaper-mcp/mcp_crest_factor"
 
 -- Helper: find or auto-insert a named JSFX on a track.
 -- Returns the FX index (0-based) on success, or nil + error message on failure.
@@ -1176,9 +1259,17 @@ function handlers.get_midi_notes(params)
 
   local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
   local to_beats = ppq_to_beats(take, item)
-  local notes = {}
 
-  for i = 0, note_cnt - 1 do
+  local offset = params.offset or 0
+  local limit = params.limit
+  local start_idx = math.min(offset, note_cnt)
+  local end_idx = note_cnt - 1
+  if limit then
+    end_idx = math.min(start_idx + limit - 1, note_cnt - 1)
+  end
+
+  local notes = {}
+  for i = start_idx, end_idx do
     local _, sel, muted, start_ppq, end_ppq, chan, pitch, vel = reaper.MIDI_GetNote(take, i)
     local start_beats = to_beats(start_ppq)
     local end_beats = to_beats(end_ppq)
@@ -1194,7 +1285,114 @@ function handlers.get_midi_notes(params)
     }
   end
 
-  return { trackIndex = params.trackIndex, itemIndex = params.itemIndex, notes = notes, total = #notes }
+  return {
+    trackIndex = params.trackIndex,
+    itemIndex = params.itemIndex,
+    notes = notes,
+    returned = #notes,
+    total = note_cnt,
+    offset = start_idx,
+    hasMore = end_idx < note_cnt - 1,
+  }
+end
+
+function handlers.analyze_midi(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local _, note_cnt, cc_cnt, _ = reaper.MIDI_CountEvts(take)
+  local to_beats = ppq_to_beats(take, item)
+
+  -- Per-pitch accumulators
+  local pitch_data = {}  -- pitch -> { count, sum_vel, sum_sq, min_vel, max_vel, last_vel, consec, max_consec, sequences }
+  -- Velocity histogram: 13 buckets (0-9, 10-19, ..., 120-127)
+  local vel_histogram = {}
+  for i = 1, 13 do vel_histogram[i] = 0 end
+
+  local max_end_beat = 0
+
+  for i = 0, note_cnt - 1 do
+    local _, _, _, start_ppq, end_ppq, _, pitch, vel = reaper.MIDI_GetNote(take, i)
+
+    -- Track duration
+    local end_beat = to_beats(end_ppq)
+    if end_beat > max_end_beat then max_end_beat = end_beat end
+
+    -- Velocity histogram bucket
+    local bucket = math.min(math.floor(vel / 10) + 1, 13)
+    vel_histogram[bucket] = vel_histogram[bucket] + 1
+
+    -- Per-pitch stats
+    if not pitch_data[pitch] then
+      pitch_data[pitch] = {
+        count = 0, sum_vel = 0, sum_sq = 0,
+        min_vel = 127, max_vel = 0,
+        last_vel = -1, consec = 1, max_consec = 1, sequences = 0,
+      }
+    end
+    local pd = pitch_data[pitch]
+    pd.count = pd.count + 1
+    pd.sum_vel = pd.sum_vel + vel
+    pd.sum_sq = pd.sum_sq + vel * vel
+    if vel < pd.min_vel then pd.min_vel = vel end
+    if vel > pd.max_vel then pd.max_vel = vel end
+
+    -- Machine gun detection: consecutive identical velocities
+    if vel == pd.last_vel then
+      pd.consec = pd.consec + 1
+      if pd.consec > pd.max_consec then pd.max_consec = pd.consec end
+    else
+      if pd.consec >= 3 then pd.sequences = pd.sequences + 1 end
+      pd.consec = 1
+    end
+    pd.last_vel = vel
+  end
+
+  -- Build pitch stats array
+  local pitch_stats = {}
+  local machine_gun = {}
+  local sorted_pitches = {}
+  for p, _ in pairs(pitch_data) do sorted_pitches[#sorted_pitches + 1] = p end
+  table.sort(sorted_pitches)
+
+  for _, pitch in ipairs(sorted_pitches) do
+    local pd = pitch_data[pitch]
+    -- Close final run
+    if pd.consec >= 3 then pd.sequences = pd.sequences + 1 end
+
+    local avg = pd.sum_vel / pd.count
+    local variance = (pd.sum_sq / pd.count) - (avg * avg)
+    local std_dev = math.sqrt(math.max(0, variance))
+
+    pitch_stats[#pitch_stats + 1] = {
+      pitch = pitch,
+      count = pd.count,
+      minVelocity = pd.min_vel,
+      maxVelocity = pd.max_vel,
+      avgVelocity = math.floor(avg * 10 + 0.5) / 10,  -- round to 1 decimal
+      stdDev = math.floor(std_dev * 10 + 0.5) / 10,
+      maxConsecutiveSameVelocity = pd.max_consec,
+    }
+
+    if pd.max_consec >= 3 then
+      machine_gun[#machine_gun + 1] = {
+        pitch = pitch,
+        maxConsecutive = pd.max_consec,
+        sequences = pd.sequences,
+      }
+    end
+  end
+
+  return {
+    trackIndex = params.trackIndex,
+    itemIndex = params.itemIndex,
+    totalNotes = note_cnt,
+    totalCC = cc_cnt,
+    durationBeats = math.floor(max_end_beat * 100 + 0.5) / 100,
+    pitchStats = pitch_stats,
+    velocityHistogram = vel_histogram,
+    machineGunWarnings = machine_gun,
+  }
 end
 
 function handlers.insert_midi_note(params)
@@ -1234,13 +1432,13 @@ function handlers.insert_midi_notes(params)
   local track, item, take, err = get_midi_take(params)
   if err then return nil, err end
 
-  local notes_str = params.notes
-  if not notes_str or notes_str == "" then return nil, "notes JSON string required" end
+  local notes_input = params.notes
+  if not notes_input or notes_input == "" then return nil, "notes array required" end
 
-  -- Parse notes JSON array (uses dedicated array parser with fallback)
-  local notes_list = json_decode_array(notes_str)
+  -- Parse notes array (accepts native table from CF_Json_Parse or JSON string fallback)
+  local notes_list = json_decode_array(notes_input)
   if not notes_list or #notes_list == 0 then
-    return nil, "Failed to parse notes JSON array. Expected: [{\"pitch\":60,\"velocity\":100,\"startPosition\":0,\"duration\":1}, ...]"
+    return nil, "Failed to parse notes array. Expected array of {pitch, velocity, startPosition, duration} objects."
   end
 
   reaper.Undo_BeginBlock()
@@ -1321,6 +1519,65 @@ function handlers.edit_midi_note(params)
   return { success = true, noteIndex = note_idx }
 end
 
+function handlers.edit_midi_notes(params)
+  local track, item, take, err = get_midi_take(params)
+  if err then return nil, err end
+
+  local edits_input = params.edits
+  if not edits_input then return nil, "edits array required" end
+
+  local edits = json_decode_array(edits_input)
+  if not edits then return nil, "Failed to parse edits array" end
+
+  local _, note_cnt, _, _ = reaper.MIDI_CountEvts(take)
+  local to_beats = ppq_to_beats(take, item)
+  local edited = 0
+  local errors = {}
+
+  reaper.Undo_BeginBlock()
+
+  for _, edit in ipairs(edits) do
+    local note_idx = edit.noteIndex
+    if note_idx == nil then
+      errors[#errors + 1] = "edit missing noteIndex"
+    elseif note_idx >= note_cnt then
+      errors[#errors + 1] = "noteIndex " .. note_idx .. " out of range"
+    else
+      local _, sel, muted, cur_start_ppq, cur_end_ppq, cur_chan, cur_pitch, cur_vel = reaper.MIDI_GetNote(take, note_idx)
+
+      local new_pitch = edit.pitch and math.max(0, math.min(127, math.floor(edit.pitch))) or nil
+      local new_vel = edit.velocity and math.max(1, math.min(127, math.floor(edit.velocity))) or nil
+      local new_chan = edit.channel and math.max(0, math.min(15, math.floor(edit.channel))) or nil
+
+      local new_start_ppq = nil
+      local new_end_ppq = nil
+      if edit.startPosition ~= nil then
+        new_start_ppq = beats_to_ppq(take, item, edit.startPosition)
+        if edit.duration ~= nil then
+          new_end_ppq = beats_to_ppq(take, item, edit.startPosition + edit.duration)
+        else
+          local dur_ppq = cur_end_ppq - cur_start_ppq
+          new_end_ppq = new_start_ppq + dur_ppq
+        end
+      elseif edit.duration ~= nil then
+        local cur_start_beats = to_beats(cur_start_ppq)
+        new_end_ppq = beats_to_ppq(take, item, cur_start_beats + edit.duration)
+      end
+
+      reaper.MIDI_SetNote(take, note_idx, sel, muted, new_start_ppq, new_end_ppq, new_chan, new_pitch, new_vel, false)
+      edited = edited + 1
+    end
+  end
+
+  reaper.MIDI_Sort(take)
+  reaper.Undo_EndBlock("MCP: Batch edit " .. edited .. " MIDI notes", -1)
+  reaper.UpdateArrange()
+
+  local result = { success = true, edited = edited, total = #edits }
+  if #errors > 0 then result.errors = errors end
+  return result
+end
+
 function handlers.delete_midi_note(params)
   local track, item, take, err = get_midi_take(params)
   if err then return nil, err end
@@ -1597,6 +1854,71 @@ function handlers.set_media_item_properties(params)
   return { success = true, trackIndex = params.trackIndex, itemIndex = params.itemIndex }
 end
 
+function handlers.set_media_items_properties(params)
+  local items_input = params.items
+  if not items_input then return nil, "items array required" end
+
+  local items = json_decode_array(items_input)
+  if not items then return nil, "Failed to parse items array" end
+
+  local edited = 0
+  local errors = {}
+
+  reaper.Undo_BeginBlock()
+
+  for _, item_params in ipairs(items) do
+    local track_idx = item_params.trackIndex
+    local item_idx = item_params.itemIndex
+    if track_idx == nil or item_idx == nil then
+      errors[#errors + 1] = "item missing trackIndex or itemIndex"
+    else
+      local track = reaper.GetTrack(0, track_idx)
+      if not track then
+        errors[#errors + 1] = "Track " .. track_idx .. " not found"
+      else
+        local item_count = reaper.CountTrackMediaItems(track)
+        if item_idx >= item_count then
+          errors[#errors + 1] = "Item " .. item_idx .. " not found on track " .. track_idx
+        else
+          local item = reaper.GetTrackMediaItem(track, item_idx)
+          if item_params.position ~= nil then
+            reaper.SetMediaItemInfo_Value(item, "D_POSITION", item_params.position)
+          end
+          if item_params.length ~= nil then
+            reaper.SetMediaItemInfo_Value(item, "D_LENGTH", item_params.length)
+          end
+          if item_params.volume ~= nil then
+            reaper.SetMediaItemInfo_Value(item, "D_VOL", from_db(item_params.volume))
+          end
+          if item_params.mute ~= nil then
+            reaper.SetMediaItemInfo_Value(item, "B_MUTE", item_params.mute)
+          end
+          if item_params.fadeInLength ~= nil then
+            reaper.SetMediaItemInfo_Value(item, "D_FADEINLEN", item_params.fadeInLength)
+          end
+          if item_params.fadeOutLength ~= nil then
+            reaper.SetMediaItemInfo_Value(item, "D_FADEOUTLEN", item_params.fadeOutLength)
+          end
+          if item_params.playRate ~= nil then
+            local take = reaper.GetActiveTake(item)
+            if take then
+              reaper.SetMediaItemTakeInfo_Value(take, "D_PLAYRATE", item_params.playRate)
+            end
+          end
+          edited = edited + 1
+        end
+      end
+    end
+  end
+
+  reaper.Undo_EndBlock("MCP: Batch set " .. edited .. " media item properties", -1)
+  reaper.UpdateArrange()
+
+  local result = { success = true, edited = edited, total = #items }
+  if #errors > 0 then result.errors = errors end
+  return result
+end
+
 function handlers.split_media_item(params)
   local track, item, err = get_media_item(params)
   if err then return nil, err end
@@ -1799,6 +2121,509 @@ function handlers.delete_stretch_marker(params)
   return { success = true, totalMarkers = reaper.GetTakeNumStretchMarkers(take) }
 end
 
+-- =============================================================================
+-- FX Enable / Offline
+-- =============================================================================
+
+function handlers.set_fx_enabled(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local fx_count = reaper.TrackFX_GetCount(track)
+  if params.fxIndex >= fx_count then
+    return nil, "FX index " .. params.fxIndex .. " out of range (track has " .. fx_count .. " FX)"
+  end
+  reaper.TrackFX_SetEnabled(track, params.fxIndex, params.enabled == 1)
+  return { trackIndex = params.trackIndex, fxIndex = params.fxIndex, enabled = params.enabled == 1 }
+end
+
+function handlers.set_fx_offline(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local fx_count = reaper.TrackFX_GetCount(track)
+  if params.fxIndex >= fx_count then
+    return nil, "FX index " .. params.fxIndex .. " out of range (track has " .. fx_count .. " FX)"
+  end
+  reaper.TrackFX_SetOffline(track, params.fxIndex, params.offline == 1)
+  return { trackIndex = params.trackIndex, fxIndex = params.fxIndex, offline = params.offline == 1 }
+end
+
+-- =============================================================================
+-- Selection & Navigation
+-- =============================================================================
+
+function handlers.get_selected_tracks(params)
+  local count = reaper.CountSelectedTracks(0)
+  local tracks = {}
+  for i = 0, count - 1 do
+    local track = reaper.GetSelectedTrack(0, i)
+    local idx = reaper.GetMediaTrackInfo_Value(track, "IP_TRACKNUMBER") - 1
+    local _, name = reaper.GetTrackName(track)
+    tracks[#tracks + 1] = { index = idx, name = name }
+  end
+  return { tracks = tracks, count = count }
+end
+
+function handlers.get_time_selection(params)
+  local start_pos, end_pos = reaper.GetSet_LoopTimeRange(false, false, 0, 0, false)
+  return {
+    start = start_pos,
+    ["end"] = end_pos,
+    length = end_pos - start_pos,
+    hasSelection = end_pos > start_pos,
+  }
+end
+
+function handlers.set_time_selection(params)
+  if params.start == nil then return nil, "start required" end
+  if params["end"] == nil then return nil, "end required" end
+  reaper.GetSet_LoopTimeRange(true, false, params.start, params["end"], false)
+  return { start = params.start, ["end"] = params["end"] }
+end
+
+-- =============================================================================
+-- Markers & Regions
+-- =============================================================================
+
+function handlers.list_markers(params)
+  local _, num_markers, num_regions = reaper.CountProjectMarkers(0)
+  local total = num_markers + num_regions
+  local markers = {}
+  for i = 0, total - 1 do
+    local _, isrgn, pos, rgnend, name, markrgnindexnumber, color = reaper.EnumProjectMarkers3(0, i)
+    if not isrgn then
+      markers[#markers + 1] = {
+        index = markrgnindexnumber,
+        name = name,
+        position = pos,
+        color = color,
+      }
+    end
+  end
+  return { markers = markers, count = #markers }
+end
+
+function handlers.list_regions(params)
+  local _, num_markers, num_regions = reaper.CountProjectMarkers(0)
+  local total = num_markers + num_regions
+  local regions = {}
+  for i = 0, total - 1 do
+    local _, isrgn, pos, rgnend, name, markrgnindexnumber, color = reaper.EnumProjectMarkers3(0, i)
+    if isrgn then
+      regions[#regions + 1] = {
+        index = markrgnindexnumber,
+        name = name,
+        start = pos,
+        ["end"] = rgnend,
+        length = rgnend - pos,
+        color = color,
+      }
+    end
+  end
+  return { regions = regions, count = #regions }
+end
+
+function handlers.add_marker(params)
+  if params.position == nil then return nil, "position required" end
+  local color = params.color or 0
+  local name = params.name or ""
+  local idx = reaper.AddProjectMarker2(0, false, params.position, 0, name, -1, color)
+  if idx < 0 then return nil, "Failed to add marker" end
+  return { index = idx, position = params.position, name = name }
+end
+
+function handlers.add_region(params)
+  if params.start == nil then return nil, "start required" end
+  if params["end"] == nil then return nil, "end required" end
+  local color = params.color or 0
+  local name = params.name or ""
+  local idx = reaper.AddProjectMarker2(0, true, params.start, params["end"], name, -1, color)
+  if idx < 0 then return nil, "Failed to add region" end
+  return { index = idx, start = params.start, ["end"] = params["end"], name = name }
+end
+
+function handlers.delete_marker(params)
+  if params.markerIndex == nil then return nil, "markerIndex required" end
+  -- DeleteProjectMarker takes (proj, isrgn, markrgnindexnumber)
+  local deleted = reaper.DeleteProjectMarker(0, false, params.markerIndex, false)
+  if not deleted then return nil, "Marker " .. params.markerIndex .. " not found" end
+  return { success = true }
+end
+
+function handlers.delete_region(params)
+  if params.regionIndex == nil then return nil, "regionIndex required" end
+  local deleted = reaper.DeleteProjectMarker(0, true, params.regionIndex, false)
+  if not deleted then return nil, "Region " .. params.regionIndex .. " not found" end
+  return { success = true }
+end
+
+-- =============================================================================
+-- Tempo Map
+-- =============================================================================
+
+function handlers.get_tempo_map(params)
+  local count = reaper.CountTempoTimeSigMarkers(0)
+  local markers = {}
+  for i = 0, count - 1 do
+    local _, timepos, measurepos, beatpos, bpm, timesig_num, timesig_denom, lineartempo = reaper.GetTempoTimeSigMarker(0, i)
+    markers[#markers + 1] = {
+      index = i,
+      position = timepos,
+      bpm = bpm,
+      timeSigNumerator = timesig_num,
+      timeSigDenominator = timesig_denom,
+      linearTempo = lineartempo,
+    }
+  end
+  -- If no markers, return the project tempo as the single entry
+  if count == 0 then
+    local bpm = reaper.Master_GetTempo()
+    local _, num, denom = reaper.TimeMap_GetTimeSigAtTime(0, 0)
+    markers[1] = {
+      index = 0,
+      position = 0,
+      bpm = bpm,
+      timeSigNumerator = num,
+      timeSigDenominator = denom,
+      linearTempo = false,
+    }
+  end
+  return { markers = markers, count = #markers }
+end
+
+-- =============================================================================
+-- Envelopes / Automation
+-- =============================================================================
+
+function handlers.get_track_envelopes(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local count = reaper.CountTrackEnvelopes(track)
+  local envelopes = {}
+  for i = 0, count - 1 do
+    local env = reaper.GetTrackEnvelope(track, i)
+    local _, name = reaper.GetEnvelopeName(env)
+    local point_count = reaper.CountEnvelopePoints(env)
+    -- Get envelope state info (SWS extension provides BR_Env*, fallback if unavailable)
+    local active, visible, armed = true, true, false
+    if reaper.BR_EnvAlloc then
+      local br_env = reaper.BR_EnvAlloc(env, false)
+      active, visible, armed = reaper.BR_EnvGetProperties(br_env)
+      reaper.BR_EnvFree(br_env, false)
+    end
+    envelopes[#envelopes + 1] = {
+      index = i,
+      name = name,
+      pointCount = point_count,
+      active = active,
+      visible = visible,
+      armed = armed,
+    }
+  end
+  return { trackIndex = params.trackIndex, envelopes = envelopes, count = count }
+end
+
+function handlers.get_envelope_points(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local total = reaper.CountEnvelopePoints(env)
+  local offset = params.offset or 0
+  local limit = params.limit or total
+  local points = {}
+  local end_idx = math.min(offset + limit, total)
+  for i = offset, end_idx - 1 do
+    local _, time, value, shape, tension, selected = reaper.GetEnvelopePoint(env, i)
+    points[#points + 1] = {
+      index = i,
+      time = time,
+      value = value,
+      shape = shape,
+      tension = tension,
+      selected = selected,
+    }
+  end
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    points = points,
+    total = total,
+    offset = offset,
+    hasMore = end_idx < total,
+  }
+end
+
+function handlers.insert_envelope_point(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local shape = params.shape or 0
+  local tension = params.tension or 0
+  reaper.InsertEnvelopePoint(env, params.time, params.value, shape, tension, false, true)
+  reaper.Envelope_SortPoints(env)
+  local total = reaper.CountEnvelopePoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    time = params.time,
+    value = params.value,
+    shape = shape,
+    tension = tension,
+    totalPoints = total,
+  }
+end
+
+function handlers.delete_envelope_point(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local total = reaper.CountEnvelopePoints(env)
+  if params.pointIndex >= total then
+    return nil, "Point index " .. params.pointIndex .. " out of range (envelope has " .. total .. " points)"
+  end
+  reaper.DeleteEnvelopePointRange(env, params.pointIndex, params.pointIndex + 1)
+  return { success = true, totalPoints = reaper.CountEnvelopePoints(env) }
+end
+
+function handlers.create_track_envelope(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+
+  local env = nil
+  local env_name = nil
+
+  if params.fxIndex ~= nil then
+    -- FX parameter envelope
+    if params.paramIndex == nil then
+      return nil, "paramIndex is required when fxIndex is provided"
+    end
+    local fx_count = reaper.TrackFX_GetNumParms(track)
+    if fx_count == 0 then
+      return nil, "Track " .. params.trackIndex .. " has no FX"
+    end
+    -- create=true to create the envelope if it doesn't exist
+    env = reaper.GetFXEnvelope(track, params.fxIndex, params.paramIndex, true)
+    if not env then
+      return nil, "Failed to create FX parameter envelope (fxIndex=" .. params.fxIndex .. ", paramIndex=" .. params.paramIndex .. ")"
+    end
+    local _, pname = reaper.TrackFX_GetParamName(track, params.fxIndex, params.paramIndex)
+    local _, fname = reaper.TrackFX_GetFXName(track, params.fxIndex)
+    env_name = fname .. " / " .. pname
+  elseif params.envelopeName then
+    -- Built-in envelope: use GetTrackEnvelopeByName + show via state chunk
+    env = reaper.GetTrackEnvelopeByName(track, params.envelopeName)
+    if not env then
+      -- Some envelopes need to be activated first via the track state chunk
+      -- Toggle the envelope visibility via action or chunk editing
+      local env_map = {
+        ["Volume"] = "VOLENV",
+        ["Pan"] = "PANENV",
+        ["Mute"] = "MUTEENV",
+        ["Width"] = "WIDTHENV",
+        ["Trim Volume"] = "VOLENV2",
+      }
+      local chunk_key = env_map[params.envelopeName]
+      if not chunk_key then
+        return nil, "Unknown envelope name: " .. params.envelopeName .. ". Use Volume, Pan, Mute, Width, or Trim Volume"
+      end
+      -- Get track chunk, insert envelope chunk if missing
+      local _, chunk = reaper.GetTrackStateChunk(track, "", false)
+      if not chunk:find(chunk_key) then
+        -- Insert a minimal envelope chunk before the closing >
+        local env_chunk = "\n<" .. chunk_key .. "\nACT 1 -1\nVIS 1 1 1\nLANEHEIGHT 0 0\nARM 0\nDEFSHAPE 0 -1 -1\n>\n"
+        chunk = chunk:gsub("\n>$", env_chunk .. ">")
+        reaper.SetTrackStateChunk(track, chunk, false)
+      else
+        -- Envelope exists in chunk but may be hidden; make it visible
+        chunk = chunk:gsub("(" .. chunk_key .. "[^\n]*\n)ACT 0", "%1ACT 1")
+        chunk = chunk:gsub("(" .. chunk_key .. "[^\n]*\n[^\n]*\n)VIS 0", "%1VIS 1")
+        reaper.SetTrackStateChunk(track, chunk, false)
+      end
+      env = reaper.GetTrackEnvelopeByName(track, params.envelopeName)
+      if not env then
+        return nil, "Failed to create envelope: " .. params.envelopeName
+      end
+    else
+      -- Envelope exists, ensure it's visible and active
+      local _, chunk = reaper.GetEnvelopeStateChunk(env, "", false)
+      chunk = chunk:gsub("ACT 0", "ACT 1")
+      chunk = chunk:gsub("VIS 0", "VIS 1")
+      reaper.SetEnvelopeStateChunk(env, chunk, false)
+    end
+    env_name = params.envelopeName
+  else
+    return nil, "Must provide either envelopeName or fxIndex+paramIndex"
+  end
+
+  -- Find the index of the newly created envelope
+  local env_count = reaper.CountTrackEnvelopes(track)
+  local env_index = -1
+  for i = 0, env_count - 1 do
+    if reaper.GetTrackEnvelope(track, i) == env then
+      env_index = i
+      break
+    end
+  end
+
+  reaper.TrackList_AdjustWindows(false)
+  reaper.UpdateArrange()
+
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = env_index,
+    name = env_name,
+    pointCount = reaper.CountEnvelopePoints(env),
+  }
+end
+
+function handlers.set_envelope_properties(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+
+  if reaper.BR_EnvAlloc then
+    -- SWS extension available: use BR_Env* functions
+    local br_env = reaper.BR_EnvAlloc(env, false)
+    local cur_active, cur_visible, cur_armed = reaper.BR_EnvGetProperties(br_env)
+    local new_active = params.active ~= nil and params.active or cur_active
+    local new_visible = params.visible ~= nil and params.visible or cur_visible
+    local new_armed = params.armed ~= nil and params.armed or cur_armed
+    reaper.BR_EnvSetProperties(br_env, new_active, new_visible, new_armed, false)
+    reaper.BR_EnvFree(br_env, true) -- commit=true
+  else
+    -- Fallback: modify envelope state chunk directly
+    local _, chunk = reaper.GetEnvelopeStateChunk(env, "", false)
+    if params.active ~= nil then
+      local val = params.active and "1" or "0"
+      chunk = chunk:gsub("ACT %d", "ACT " .. val)
+    end
+    if params.visible ~= nil then
+      local val = params.visible and "1" or "0"
+      chunk = chunk:gsub("VIS %d", "VIS " .. val)
+    end
+    if params.armed ~= nil then
+      local val = params.armed and "1" or "0"
+      chunk = chunk:gsub("ARM %d", "ARM " .. val)
+    end
+    reaper.SetEnvelopeStateChunk(env, chunk, false)
+  end
+
+  reaper.TrackList_AdjustWindows(false)
+  reaper.UpdateArrange()
+
+  local _, name = reaper.GetEnvelopeName(env)
+  -- Re-read properties
+  local active, visible, armed = true, true, false
+  if reaper.BR_EnvAlloc then
+    local br_env = reaper.BR_EnvAlloc(env, false)
+    active, visible, armed = reaper.BR_EnvGetProperties(br_env)
+    reaper.BR_EnvFree(br_env, false)
+  end
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    name = name,
+    active = active,
+    visible = visible,
+    armed = armed,
+  }
+end
+
+function handlers.clear_envelope(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local prev_count = reaper.CountEnvelopePoints(env)
+  -- Delete all points by using a range from -infinity to +infinity
+  reaper.DeleteEnvelopePointRange(env, -math.huge, math.huge)
+  reaper.Envelope_SortPoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    deletedPoints = prev_count,
+    totalPoints = reaper.CountEnvelopePoints(env),
+  }
+end
+
+function handlers.remove_envelope_points(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+  local prev_count = reaper.CountEnvelopePoints(env)
+  reaper.DeleteEnvelopePointRange(env, params.timeStart, params.timeEnd)
+  reaper.Envelope_SortPoints(env)
+  local new_count = reaper.CountEnvelopePoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    timeStart = params.timeStart,
+    timeEnd = params.timeEnd,
+    deletedPoints = prev_count - new_count,
+    totalPoints = new_count,
+  }
+end
+
+function handlers.insert_envelope_points(params)
+  local track = reaper.GetTrack(0, params.trackIndex)
+  if not track then return nil, "Track " .. params.trackIndex .. " not found" end
+  local env_count = reaper.CountTrackEnvelopes(track)
+  if params.envelopeIndex >= env_count then
+    return nil, "Envelope index " .. params.envelopeIndex .. " out of range (track has " .. env_count .. " envelopes)"
+  end
+  local env = reaper.GetTrackEnvelope(track, params.envelopeIndex)
+
+  -- Parse the points JSON string
+  local points_str = params.points
+  local points = nil
+  if type(points_str) == "string" then
+    points = json_decode(points_str)
+  elseif type(points_str) == "table" then
+    points = points_str
+  end
+  if not points then return nil, "Failed to parse points JSON" end
+
+  local inserted = 0
+  for _, pt in ipairs(points) do
+    if pt.time and pt.value then
+      local shape = pt.shape or 0
+      local tension = pt.tension or 0
+      reaper.InsertEnvelopePoint(env, pt.time, pt.value, shape, tension, false, true)
+      inserted = inserted + 1
+    end
+  end
+
+  reaper.Envelope_SortPoints(env)
+  return {
+    trackIndex = params.trackIndex,
+    envelopeIndex = params.envelopeIndex,
+    insertedPoints = inserted,
+    totalPoints = reaper.CountEnvelopePoints(env),
+  }
+end
+
 -- =============================================================================
 -- Command dispatcher
 -- =============================================================================