@mthines/reaper-mcp 0.6.0 → 0.7.0

package/README.md

@@ -24,17 +24,23 @@ npx @mthines/reaper-mcp install-skills
 # 4. Open Claude Code — you're ready to mix
 ```
 
-That's it. Claude Code now has 26 REAPER tools and a professional mix engineer's knowledge base.
+That's it. Claude Code now has 67 REAPER tools and a professional mix engineer's knowledge base.
 
 ## What it does
 
 ```
 Claude Code
-  ├── MCP Tools (26) ──→ controls REAPER in real-time
-  │   ├── Track management (list, get/set properties)
-  │   ├── FX management (add/remove, get/set parameters, presets)
+  ├── MCP Tools (67) ──→ controls REAPER in real-time
+  │   ├── Track management (list, get/set properties, arm, phase, input)
+  │   ├── FX management (add/remove, get/set parameters, enable/offline, presets)
   │   ├── Transport (play, stop, record, cursor position)
   │   ├── Metering (peak/RMS, FFT spectrum, LUFS, correlation, crest factor)
+  │   ├── Selection (selected tracks, time selection)
+  │   ├── Markers & regions (list, add, delete)
+  │   ├── Tempo map (all tempo/time sig changes)
+  │   ├── Envelopes (list, read/write automation points)
+  │   ├── MIDI editing (14 tools: notes, CC, items, analysis, batch ops)
+  │   ├── Media items (11 tools: properties, split, move, trim, stretch)
   │   ├── Plugin discovery (list installed FX, search, presets)
   │   ├── Snapshots (save/restore mixer state for A/B comparison)
   │   └── Routing (sends, receives, bus structure)
@@ -43,7 +49,7 @@ Claude Code
       ├── Plugin knowledge (ReaEQ, Pro-Q 3, Helix Native, etc.)
       ├── Genre rules (rock, pop, hip-hop, electronic, orchestral, metal)
       ├── Workflows (gain staging, vocal chain, drum bus, mastering)
-      └── Reference (frequencies, compression, LUFS targets, common mistakes)
+      └── Reference (frequencies, compression, LUFS targets, perceived loudness, common mistakes)
 ```
 
 ## Architecture
@@ -72,6 +78,7 @@ npx @mthines/reaper-mcp setup
 ```
 
 This copies into your REAPER resource folder:
+
 - `mcp_bridge.lua` — persistent Lua bridge script
 - `mcp_analyzer.jsfx` — FFT spectrum analyzer
 - `mcp_lufs_meter.jsfx` — ITU-R BS.1770 LUFS meter
@@ -95,6 +102,7 @@ npx @mthines/reaper-mcp install-skills
 ```
 
 This creates in your project:
+
 - `.claude/agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
 - `.claude/rules/` — architecture and development rules
 - `.claude/skills/` — skills like `/learn-plugin`
@@ -109,29 +117,34 @@ npx @mthines/reaper-mcp doctor
 
 Checks that the bridge is connected, knowledge is installed, and MCP config exists.
 
-## MCP Tools (26)
+## MCP Tools (67)
+
+### Project & Tracks
 
-### Track Management
 | Tool | Description |
 |------|-------------|
 | `get_project_info` | Project name, tempo, time sig, sample rate, transport state |
-| `list_tracks` | All tracks with volume, pan, mute/solo, FX count, routing |
+| `list_tracks` | All tracks with volume, pan, mute/solo, arm, phase, FX count, routing |
 | `get_track_properties` | Detailed track info + full FX chain list |
-| `set_track_property` | Set volume (dB), pan, mute, solo |
+| `set_track_property` | Set volume (dB), pan, mute, solo, recordArm, phase, input |
 
 ### FX Management
+
 | Tool | Description |
 |------|-------------|
 | `add_fx` | Add FX by name (partial match: "ReaEQ", "Pro-Q 3") |
 | `remove_fx` | Remove FX from chain by index |
 | `get_fx_parameters` | List all FX params with values and ranges |
 | `set_fx_parameter` | Set FX parameter (normalized 0.0-1.0) |
+| `set_fx_enabled` | Enable or disable (bypass) an FX plugin |
+| `set_fx_offline` | Set FX online/offline (offline = no CPU, preserves settings) |
 | `list_available_fx` | Discover all installed plugins (VST, VST3, JS, CLAP, AU) |
 | `search_fx` | Fuzzy search installed plugins by name |
 | `get_fx_preset_list` | List available presets for an FX |
 | `set_fx_preset` | Load a preset by name |
 
 ### Transport
+
 | Tool | Description |
 |------|-------------|
 | `play` | Start playback |
@@ -140,7 +153,42 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 | `get_transport_state` | Play/record/pause, cursor positions, tempo, time sig |
 | `set_cursor_position` | Move edit cursor to position (seconds) |
 
+### Selection & Navigation
+
+| Tool | Description |
+|------|-------------|
+| `get_selected_tracks` | Currently selected tracks with indices and names |
+| `get_time_selection` | Time/loop selection start, end, length |
+| `set_time_selection` | Set the time selection range |
+
+### Markers & Regions
+
+| Tool | Description |
+|------|-------------|
+| `list_markers` | All project markers (index, name, position, color) |
+| `list_regions` | All regions (index, name, start/end, color) |
+| `add_marker` | Add marker at position with optional name/color |
+| `add_region` | Add region with start/end, optional name/color |
+| `delete_marker` | Delete a marker by index |
+| `delete_region` | Delete a region by index |
+
+### Tempo Map
+
+| Tool | Description |
+|------|-------------|
+| `get_tempo_map` | All tempo/time sig changes (position, BPM, time sig, linear) |
+
+### Envelopes / Automation
+
+| Tool | Description |
+|------|-------------|
+| `get_track_envelopes` | List envelopes on a track (name, point count, active/visible/armed) |
+| `get_envelope_points` | Get automation points with pagination |
+| `insert_envelope_point` | Insert automation point (time, value, shape, tension) |
+| `delete_envelope_point` | Delete an automation point by index |
+
 ### Metering & Analysis
+
 | Tool | Description |
 |------|-------------|
 | `read_track_meters` | Peak/RMS L/R in dB |
@@ -149,7 +197,33 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 | `read_track_correlation` | Stereo correlation, width, mid/side levels |
 | `read_track_crest` | Crest factor (peak-to-RMS ratio) |
 
+### MIDI Editing (14 tools)
+
+| Tool | Description |
+|------|-------------|
+| `create_midi_item` | Create empty MIDI item on a track |
+| `list_midi_items` | List MIDI items with position, length, note/CC counts |
+| `get_midi_notes` | Get notes with pagination (offset/limit) |
+| `analyze_midi` | Per-pitch velocity stats, histogram, machine gun detection |
+| `insert_midi_note` / `insert_midi_notes` | Insert single or batch notes |
+| `edit_midi_note` / `edit_midi_notes` | Edit single or batch notes |
+| `delete_midi_note` | Delete a note by index |
+| `get_midi_cc` / `insert_midi_cc` / `delete_midi_cc` | CC event management |
+| `get_midi_item_properties` / `set_midi_item_properties` | MIDI item props |
+
+### Media Item Editing (11 tools)
+
+| Tool | Description |
+|------|-------------|
+| `list_media_items` | List items on a track (position, length, name, volume, type) |
+| `get_media_item_properties` | Detailed properties (fades, play rate, pitch, source) |
+| `set_media_item_properties` / `set_media_items_properties` | Set single or batch |
+| `split_media_item` | Split at position, returns left/right info |
+| `delete_media_item` / `move_media_item` / `trim_media_item` | Edit operations |
+| `add_stretch_marker` / `get_stretch_markers` / `delete_stretch_marker` | Time-stretching |
+
 ### Snapshots (A/B Testing)
+
 | Tool | Description |
 |------|-------------|
 | `snapshot_save` | Save current mixer state (volumes, pans, FX, mutes) |
@@ -157,6 +231,7 @@ Checks that the bridge is connected, knowledge is installed, and MCP config exis
 | `snapshot_list` | List all saved snapshots |
 
 ### Routing
+
 | Tool | Description |
 |------|-------------|
 | `get_track_routing` | Sends, receives, parent/folder info for a track |
@@ -167,12 +242,12 @@ Once you've run `setup` and `install-skills`, open Claude Code in your project d
 
 ### Available Agents
 
-| Agent | Invocation | What it does |
-|-------|-----------|-------------|
+| Agent            | Invocation      | What it does                                                              |
+| ---------------- | --------------- | ------------------------------------------------------------------------- |
 | **Mix Engineer** | `@mix-engineer` | General-purpose mix agent — analyzes, suggests, and executes any mix task |
-| **Gain Stage** | `@gain-stage` | Sets all tracks to -18 dBFS average with proper headroom |
-| **Mix Analyzer** | `@mix-analyzer` | "Roast my mix" — analysis only, no changes, produces detailed report |
-| **Master** | `@master` | Mastering chain targeting specific LUFS/platform standards |
+| **Gain Stage**   | `@gain-stage`   | Perceived-loudness-aware gain staging with proper headroom                |
+| **Mix Analyzer** | `@mix-analyzer` | "Roast my mix" — analysis only, no changes, produces detailed report      |
+| **Master**       | `@master`       | Mastering chain targeting specific LUFS/platform standards                |
 
 ### How to use them
 
@@ -196,12 +271,14 @@ claude --agent mix-engineer
 ### What happens under the hood
 
 Each agent has:
+
 - **Its own system prompt** — thinks like a mix engineer, not a general assistant
 - **Pre-approved REAPER tools** — no permission prompts for every MCP call
 - **Scoped MCP access** — only the `reaper` MCP server is loaded
 - **Embedded reference data** — frequency bands, LUFS targets, compression settings
 
 The workflow is always:
+
 1. **Save a snapshot** (so you can always A/B or undo)
 2. **Analyze** — read meters, spectrum, LUFS, correlation, crest factor
 3. **Reason** — apply genre rules, frequency knowledge, and plugin expertise
@@ -212,6 +289,7 @@ The workflow is always:
 ### A/B Comparison
 
 Every change is bracketed by snapshots:
+
 1. Agent saves a "Before" snapshot automatically
 2. Makes all changes
 3. Saves an "After" snapshot
@@ -236,12 +314,12 @@ The knowledge base is what makes this more than just a remote control — it's a
 
 Ships with knowledge for stock REAPER plugins and popular third-party suites:
 
-| Plugin | Category | Preference |
-|--------|----------|-----------|
-| ReaEQ, ReaComp, ReaDelay, ReaVerb, ReaGate, ReaLimit | Stock | 30-50 |
-| FabFilter Pro-Q 3, Pro-C 2, Pro-L 2 | Premium EQ/Comp/Limiter | 85-92 |
-| Line 6 Helix Native | Amp Sim | 82 |
-| JS: 1175 Compressor | Character Comp | 50 |
+| Plugin                                               | Category                | Preference |
+| ---------------------------------------------------- | ----------------------- | ---------- |
+| ReaEQ, ReaComp, ReaDelay, ReaVerb, ReaGate, ReaLimit | Stock                   | 30-50      |
+| FabFilter Pro-Q 3, Pro-C 2, Pro-L 2                  | Premium EQ/Comp/Limiter | 85-92      |
+| Line 6 Helix Native                                  | Amp Sim                 | 82         |
+| JS: 1175 Compressor                                  | Character Comp          | 50         |
 
 The agent automatically discovers your installed plugins and uses the best available option for each task. If you have Pro-Q 3, it uses that. If not, it falls back to ReaEQ.
 
@@ -263,14 +341,14 @@ Or manually add a markdown file to `knowledge/plugins/`. See `knowledge/plugins/
 
 Processing decisions adapt to the genre:
 
-| Genre | LUFS Target | Key Characteristics |
-|-------|------------|---------------------|
-| Rock | -11 to -9 | Parallel drum compression, hard-panned guitars |
-| Pop | -14 to -10 | Vocal-forward, two-stage compression, bus glue |
-| Hip-Hop | -10 to -7 | 808 saturation, aggressive vocal comp, mono sub |
-| Electronic | -10 to -6 | Sidechain pump, sub mono, stereo width |
-| Orchestral | -23 to -16 | Preserve dynamics, hall reverb staging |
-| Metal | -11 to -8 | V-scoop guitars, tight drums, 4-guitar wall |
+| Genre      | LUFS Target | Key Characteristics                             |
+| ---------- | ----------- | ----------------------------------------------- |
+| Rock       | -11 to -9   | Parallel drum compression, hard-panned guitars  |
+| Pop        | -14 to -10  | Vocal-forward, two-stage compression, bus glue  |
+| Hip-Hop    | -10 to -7   | 808 saturation, aggressive vocal comp, mono sub |
+| Electronic | -10 to -6   | Sidechain pump, sub mono, stereo width          |
+| Orchestral | -23 to -16  | Preserve dynamics, hall reverb staging          |
+| Metal      | -11 to -8   | V-scoop guitars, tight drums, 4-guitar wall     |
 
 ## Autonomous Mode (Allow All Tools)
 
@@ -307,7 +385,48 @@ Add to your project's `.claude/settings.json` (or `~/.claude/settings.json` for
       "mcp__reaper__snapshot_save",
       "mcp__reaper__snapshot_restore",
       "mcp__reaper__snapshot_list",
-      "mcp__reaper__get_track_routing"
+      "mcp__reaper__get_track_routing",
+      "mcp__reaper__set_fx_enabled",
+      "mcp__reaper__set_fx_offline",
+      "mcp__reaper__get_selected_tracks",
+      "mcp__reaper__get_time_selection",
+      "mcp__reaper__set_time_selection",
+      "mcp__reaper__list_markers",
+      "mcp__reaper__list_regions",
+      "mcp__reaper__add_marker",
+      "mcp__reaper__add_region",
+      "mcp__reaper__delete_marker",
+      "mcp__reaper__delete_region",
+      "mcp__reaper__get_tempo_map",
+      "mcp__reaper__get_track_envelopes",
+      "mcp__reaper__get_envelope_points",
+      "mcp__reaper__insert_envelope_point",
+      "mcp__reaper__delete_envelope_point",
+      "mcp__reaper__create_midi_item",
+      "mcp__reaper__list_midi_items",
+      "mcp__reaper__get_midi_notes",
+      "mcp__reaper__analyze_midi",
+      "mcp__reaper__insert_midi_note",
+      "mcp__reaper__insert_midi_notes",
+      "mcp__reaper__edit_midi_note",
+      "mcp__reaper__edit_midi_notes",
+      "mcp__reaper__delete_midi_note",
+      "mcp__reaper__get_midi_cc",
+      "mcp__reaper__insert_midi_cc",
+      "mcp__reaper__delete_midi_cc",
+      "mcp__reaper__get_midi_item_properties",
+      "mcp__reaper__set_midi_item_properties",
+      "mcp__reaper__list_media_items",
+      "mcp__reaper__get_media_item_properties",
+      "mcp__reaper__set_media_item_properties",
+      "mcp__reaper__set_media_items_properties",
+      "mcp__reaper__split_media_item",
+      "mcp__reaper__delete_media_item",
+      "mcp__reaper__move_media_item",
+      "mcp__reaper__trim_media_item",
+      "mcp__reaper__add_stretch_marker",
+      "mcp__reaper__get_stretch_markers",
+      "mcp__reaper__delete_stretch_marker"
     ]
   }
 }
@@ -350,13 +469,31 @@ After `install-skills`, your project has a `.mcp.json`:
 
 Claude Code reads this automatically. Open Claude Code in your project and the REAPER tools are available.
 
+### Running from source (development)
+
+If you're developing reaper-mcp and want changes reflected immediately without rebuilding, point your `.mcp.json` at the TypeScript source using `npx tsx`:
+
+```json
+{
+  "mcpServers": {
+    "reaper": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/reaper-mcp/apps/reaper-mcp-server/src/main.ts", "serve"]
+    }
+  }
+}
+```
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the full dev workflow.
+
 ## Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
+| Variable               | Description                        | Default              |
+| ---------------------- | ---------------------------------- | -------------------- |
 | `REAPER_RESOURCE_PATH` | Override REAPER resource directory | Auto-detected per OS |
 
 Platform defaults:
+
 - **macOS**: `~/Library/Application Support/REAPER`
 - **Windows**: `%APPDATA%/REAPER`
 - **Linux**: `~/.config/REAPER`
@@ -366,14 +503,14 @@ Platform defaults:
 ```
 reaper-mcp/
 ├── apps/
-│   ├── reaper-mcp-server/        # MCP server (26 tools, esbuild bundle)
+│   ├── reaper-mcp-server/        # MCP server (67 tools, esbuild bundle)
 │   └── reaper-mix-agent/         # AI mix agent (knowledge loader, plugin resolver)
 ├── libs/protocol/                # Shared TypeScript types
 ├── knowledge/                    # AI mix engineer knowledge base
 │   ├── plugins/                  # Plugin-specific knowledge (extensible)
 │   ├── genres/                   # Genre mixing conventions
 │   ├── workflows/                # Step-by-step mixing workflows
-│   └── reference/                # Frequency, compression, metering cheat sheets
+│   └── reference/                # Frequency, compression, metering, perceived loudness cheat sheets
 ├── reaper/                       # Files installed into REAPER
 │   ├── mcp_bridge.lua            # Persistent Lua bridge
 │   ├── mcp_analyzer.jsfx         # FFT spectrum analyzer
@@ -384,16 +521,34 @@ reaper-mcp/
 └── nx.json                       # Nx workspace config
 ```
 
+## Updating the Lua Bridge
+
+The MCP server (TypeScript) and the Lua bridge (REAPER) are two separate components. After updating to a new version — or after adding new tools during development — you need to reinstall the bridge files and reload the script in REAPER:
+
+```bash
+# Reinstall bridge files into REAPER
+npx @mthines/reaper-mcp setup
+```
+
+Then in REAPER:
+
+1. **Stop** the running bridge: Actions > Running Scripts > stop `mcp_bridge.lua`
+2. **Reload** the updated script: Actions > Load ReaScript > select `mcp_bridge.lua` > Run
+
+If existing tools (like `get_project_info`) work but new tools fail or timeout, this is almost always because the Lua bridge needs to be updated and reloaded.
+
 ## Development
 
 ```bash
 pnpm install
 pnpm nx run-many --target=build      # Build all
 pnpm nx run-many --target=lint       # Lint all
-pnpm nx run-many --target=test       # Test all (130+ tests)
+pnpm nx run-many --target=test       # Test all (200+ tests)
 pnpm nx run-many --target=build,lint,test  # Everything
 ```
 
+See [DEVELOPMENT.md](DEVELOPMENT.md) for the full dev workflow including running from source, MCP Inspector, and bridge update details.
+
 ## License
 
 MIT

package/claude-agents/gain-stage.md

@@ -10,7 +10,9 @@ permissionMode: acceptEdits
 
 # Gain Staging Agent
 
-You are a gain staging specialist for REAPER DAW. Your sole job is to set all track levels to approximately **-18 dBFS average** before any FX processing, ensuring proper headroom for the mix.
+You are a gain staging specialist for REAPER DAW. Your job is to set all track levels to proper averages before any FX processing, ensuring proper headroom for the mix.
+
+**Critical**: Don't just set every track to -18 dBFS. Account for **perceived loudness** — the human ear is 10-15 dB more sensitive at 2-5 kHz than at low frequencies. Bass instruments need higher meter readings than vocals/cymbals to sound balanced. Read `knowledge/reference/perceived-loudness.md` for the full reference.
 
 ---
 
@@ -42,14 +44,25 @@ params: { trackIndex: N }
 ```
 Wait a few seconds of playback before reading. Record the RMS level for each track.
 
-### Step 5: Calculate adjustments
-Formula: `gain_dB = -18 - current_average_dBFS`
+### Step 5: Calculate adjustments (perceived-loudness-aware)
+
+Use instrument-appropriate targets, NOT a flat -18 dBFS for everything:
+
+| Instrument Category | Target RMS | Why |
+|-------------------|-----------|-----|
+| Sub/bass (kick sub, bass, 808) | -16 to -14 dBFS | Low frequencies sound quieter; needs more energy on meters |
+| Full-range (piano, full guitar, strings) | -18 dBFS | Standard target; spans the perceptual range |
+| Presence-range (vocals, snare crack, lead guitar) | -19 to -20 dBFS | 2-5 kHz content sounds louder than meters show |
+| High-frequency (cymbals, hi-hats, shakers) | -20 to -22 dBFS | Very sensitive frequency range; a little goes a long way |
+
+Formula: `gain_dB = target_dBFS - current_average_dBFS`
 Round to nearest 0.5 dB.
 
 Examples:
-- Track at -24 dBFS → needs +6 dB
-- Track at -10 dBFS → needs -8 dB
-- Track at -18 dBFS → no change needed
+- Bass at -24 dBFS → target -15 dBFS → needs +9 dB
+- Vocal at -10 dBFS → target -19 dBFS → needs -9 dB
+- Piano at -24 dBFS → target -18 dBFS → needs +6 dB
+- Hi-hat at -14 dBFS → target -21 dBFS → needs -7 dB
 
 ### Step 6: Apply adjustments via the track fader
 ```
@@ -77,8 +90,11 @@ List each track with:
 
 ---
 
-## Targets
-- **RMS per track**: -18 dBFS (acceptable range: -21 to -15 dBFS)
+## Targets (Perceived-Loudness-Aware)
+- **Sub/bass instruments**: -16 to -14 dBFS RMS (sounds quieter than meters show)
+- **Full-range instruments**: -18 dBFS RMS (standard target)
+- **Presence-range instruments**: -19 to -20 dBFS RMS (sounds louder due to ear sensitivity)
+- **High-frequency instruments**: -20 to -22 dBFS RMS (very sensitive range)
 - **Peak per track**: -12 dBFS max
 - **Mix bus peak**: -6 to -3 dBFS in the chorus
 
@@ -88,3 +104,4 @@ List each track with:
 - Do NOT read a single moment — play the densest section for 10+ seconds
 - Bus tracks sum multiple sources — check them AFTER adjusting source tracks
 - If a track has wildly inconsistent levels, note it as needing clip gain editing (manual task)
+- Do NOT set all tracks to the same dBFS target — bass instruments need more energy on meters than vocals/cymbals to sound perceptually balanced (see perceived loudness targets above)

package/claude-agents/master.md

@@ -73,6 +73,8 @@ Apply to the mix bus. Typical mastering moves:
 | Presence | 2–4 kHz | +0.5 dB | Vocal clarity (only if needed) |
 | Air shelf | 10–12 kHz | +0.5 to +1 dB | Subtle sparkle |
 
+**Perceived loudness note**: The 2-5 kHz range is where the ear is most sensitive (10-15 dB more than bass). Even +0.5 dB here has outsized perceptual impact. Conversely, low-end cuts of -1 dB may barely be noticed. When assessing the spectrum, remember a "flat" analyzer response does NOT equal perceptually flat — the ear naturally amplifies presence frequencies.
+
 **Rule**: If you're EQing more than +-2 dB, there's a mix problem — go back and fix it.
 
 ### Step 5: Mastering compression (optional, for glue only)
@@ -124,3 +126,4 @@ params: { name: "master-v1", description: "Mastered — targeting {LUFS} for {pl
 - Linear phase EQ if available (avoids phase shift on the master)
 - Always A/B with `snapshot_restore` — mastering can be subtle enough to fool yourself
 - If the user asks for a specific LUFS target that's louder than genre convention, warn them but comply
+- **Perceived loudness awareness**: When evaluating the mix bus spectrum, account for equal-loudness contours. A mix that looks flat on the analyzer will sound presence-heavy. A well-balanced master typically shows a gentle downward slope from low to high frequencies on a spectrum analyzer, compensating for the ear's heightened sensitivity at 2-5 kHz

package/claude-agents/mix-analyzer.md

@@ -27,7 +27,7 @@ tool: list_tracks
 ```
 Note: track count, tempo, sample rate, bus structure.
 
-### 2. Gain staging check
+### 2. Gain staging check (perceived-loudness-aware)
 Start playback of the chorus/loudest section:
 ```
 tool: play
@@ -36,22 +36,30 @@ Then read meters for ALL tracks:
 ```
 tool: read_track_meters (for each track)
 ```
-Flag:
+Flag standard issues:
 - Any track averaging below -24 dBFS or above -10 dBFS
 - Any track peaking at or above -3 dBFS
 - Mix bus peaking above -6 dBFS
 
-### 3. Frequency balance
+**Also check perceived loudness balance** (see `knowledge/reference/perceived-loudness.md`):
+- Bass instruments (kick, bass, 808) should read **higher** on meters than vocals/guitars (-16 to -14 dBFS) — if they're at the same level as presence-range instruments, they'll sound too quiet
+- Vocals/snare should read **lower** (-19 to -20 dBFS) — the 2-5 kHz content sounds louder than the meter shows
+- Hi-hats/cymbals at similar meter levels as bass = way too loud perceptually
+- Flag any mix where all tracks are at the same RMS level regardless of spectral content — this is a common amateur mistake
+
+### 3. Frequency balance (with perceived loudness context)
 Read spectrum on the mix bus:
 ```
 tool: read_track_spectrum (mix bus index)
 ```
 Check for:
-- **Sub buildup** (20–60 Hz): excessive rumble
-- **Low-mid mud** (200–400 Hz): cloudy, boxy sound
-- **Harshness** (2–5 kHz): fatiguing, piercing
-- **Missing air** (10–20 kHz): dull, lifeless
-- **Missing presence** (1–4 kHz): vocals buried
+- **Sub buildup** (20–60 Hz): excessive rumble — but remember sub energy sounds quieter than it meters; some buildup is needed for bass-heavy genres
+- **Low-mid mud** (200–400 Hz): cloudy, boxy sound — the ear is less sensitive here, so mud accumulates before it's noticed on meters
+- **Harshness** (2–5 kHz): fatiguing, piercing — the ear's peak sensitivity zone. Even modest energy here sounds loud and causes listening fatigue
+- **Missing air** (10–20 kHz): dull, lifeless — sensitivity drops off, but accumulated boosts across many tracks cause fatigue
+- **Missing presence** (1–4 kHz): vocals buried — often a masking issue (guitars/keys competing in the most sensitive range), not just a level issue
+
+**Perceived loudness note**: A "flat" spectrum on an analyzer does NOT mean a perceptually balanced mix. The ear naturally amplifies 2-5 kHz, so a truly flat spectrum will sound harsh/forward in the presence range.
 
 ### 4. Dynamics check
 ```
@@ -136,3 +144,4 @@ Structure your output as:
 - Don't just say "it's muddy" — say "200–400 Hz shows +4 dB above the average curve"
 - Always suggest a specific fix, not just identify the problem
 - Find something positive to mention — even in rough mixes
+- **Account for perceived loudness** — don't flag bass instruments as "too hot" just because they meter higher than vocals. Bass needs more dB to sound balanced. Conversely, flag presence-range instruments that meter the same as bass — they'll sound much louder than intended

package/claude-agents/mix-engineer.md

@@ -22,18 +22,22 @@ You are a professional mix engineer with 20 years of experience working inside R
 4. **Use the best available plugin** for each task. Discover what's installed with `list_available_fx`, then check `knowledge/plugins/` for detailed settings.
 5. **Iterate** — make a change, verify with meters, adjust if needed.
 6. **Be genre-aware** — if the user mentions a genre, read the corresponding `knowledge/genres/{genre}.md` for conventions.
+7. **Optimize for perceived loudness, not just meters** — the human ear is 10-15 dB more sensitive at 2-5 kHz than at 100 Hz. Bass instruments need higher meter readings than vocals/guitars to sound balanced. Always read `knowledge/reference/perceived-loudness.md` when making balance or EQ decisions.
 
 ---
 
 ## Available MCP Tools
 
-You have access to 26 REAPER tools via the `reaper` MCP server:
+You have access to 67 REAPER tools via the `reaper` MCP server:
 
 ### Session Info
 - `get_project_info` — project name, tempo, time sig, sample rate, transport
-- `list_tracks` — all tracks with levels, FX counts, routing
+- `list_tracks` — all tracks with levels, arm, phase, FX counts, routing
 - `get_track_properties` — single track detail + full FX chain
 - `get_track_routing` — sends, receives, bus structure
+- `get_selected_tracks` — currently selected tracks
+- `get_time_selection` — current time/loop selection (start, end, length)
+- `set_time_selection` — set the time selection range
 
 ### Transport
 - `play`, `stop`, `record` — transport control
@@ -41,13 +45,15 @@ You have access to 26 REAPER tools via the `reaper` MCP server:
 - `set_cursor_position` — move cursor (seconds)
 
 ### Track Control
-- `set_track_property` — volume (dB), pan, mute, solo
+- `set_track_property` — volume (dB), pan, mute, solo, recordArm, phase, input
 
 ### FX Management
 - `add_fx` — add plugin by name (partial match: "ReaEQ", "Pro-Q 3")
 - `remove_fx` — remove from chain by index
 - `get_fx_parameters` — list all params with values/ranges
 - `set_fx_parameter` — set parameter (normalized 0.0–1.0)
+- `set_fx_enabled` — enable or disable (bypass) an FX
+- `set_fx_offline` — set FX online/offline (offline = no CPU, preserves settings)
 - `list_available_fx` — discover ALL installed plugins
 - `search_fx` — fuzzy search plugins by name
 - `get_fx_preset_list` — list presets for an FX
@@ -65,6 +71,36 @@ You have access to 26 REAPER tools via the `reaper` MCP server:
 - `snapshot_restore` — restore saved state
 - `snapshot_list` — list all snapshots
 
+### Markers & Regions
+- `list_markers` — all project markers (index, name, position, color)
+- `list_regions` — all regions (index, name, start/end, color)
+- `add_marker`, `add_region` — add markers/regions with name/color
+- `delete_marker`, `delete_region` — remove by index
+
+### Tempo Map
+- `get_tempo_map` — all tempo/time sig changes (position, BPM, time sig, linear)
+
+### Envelopes / Automation
+- `get_track_envelopes` — list envelopes on a track (volume, pan, FX params)
+- `get_envelope_points` — get automation points with pagination
+- `insert_envelope_point` — add automation point (time, value, shape, tension)
+- `delete_envelope_point` — remove an automation point
+
+### MIDI Editing (14 tools)
+- `create_midi_item`, `list_midi_items` — create and list MIDI items
+- `get_midi_notes`, `analyze_midi` — read/analyze notes (with pagination)
+- `insert_midi_note`, `insert_midi_notes` — insert single/batch notes
+- `edit_midi_note`, `edit_midi_notes` — edit single/batch notes
+- `delete_midi_note` — delete a note
+- `get_midi_cc`, `insert_midi_cc`, `delete_midi_cc` — CC events
+- `get_midi_item_properties`, `set_midi_item_properties` — MIDI item props
+
+### Media Item Editing (11 tools)
+- `list_media_items`, `get_media_item_properties`, `set_media_item_properties` — read/write items
+- `set_media_items_properties` — batch set on multiple items
+- `split_media_item`, `delete_media_item`, `move_media_item`, `trim_media_item` — editing
+- `add_stretch_marker`, `get_stretch_markers`, `delete_stretch_marker` — time-stretching
+
 ---
 
 ## Knowledge Base
@@ -77,6 +113,7 @@ If the project has a `knowledge/` directory (installed via `reaper-mcp install-s
 - **`knowledge/reference/frequencies.md`** — EQ frequency cheat sheet
 - **`knowledge/reference/compression.md`** — compression settings per instrument
 - **`knowledge/reference/metering.md`** — LUFS targets, crest factor thresholds
+- **`knowledge/reference/perceived-loudness.md`** — psychoacoustic loudness perception, equal-loudness contours, per-instrument compensation
 - **`knowledge/reference/common-mistakes.md`** — amateur mixing mistakes checklist
 
 Use `Glob` to find files and `Read` to load them when needed. Don't load everything upfront — load what's relevant to the current task.
@@ -143,19 +180,22 @@ Report what changed, before/after measurements, and suggestions for next steps.
 
 ## Quick Reference (Embedded)
 
-### Frequency Bands
-| Band | Range | Character | Common Issues |
-|------|-------|-----------|--------------|
-| Sub | 20–60 Hz | Felt, rumble | HPF everything that doesn't need it |
-| Bass | 60–250 Hz | Punch, warmth | Competing kick/bass |
-| Low-mids | 250–500 Hz | **Mud zone** | Most common problem area |
-| Mids | 500 Hz–2 kHz | Presence, character | Boxy, honky if excess |
-| Upper-mids | 2–5 kHz | **Harshness zone** | Most sensitive hearing range |
-| Presence | 5–8 kHz | Sibilance, definition | De-esser territory |
-| Air | 8–20 kHz | Sparkle, shimmer | Shelf boost for "expensive" sound |
-
-### Gain Staging Targets
-- Individual tracks: -18 dBFS average, -12 dBFS peak
+### Frequency Bands (with Perceived Loudness)
+| Band | Range | Character | Perceived Loudness | Common Issues |
+|------|-------|-----------|-------------------|--------------|
+| Sub | 20–60 Hz | Felt, rumble | **Much quieter** than metered | HPF everything that doesn't need it |
+| Bass | 60–250 Hz | Punch, warmth | **Quieter** than metered | Competing kick/bass; needs +3-6 dB over mids on meters |
+| Low-mids | 250–500 Hz | **Mud zone** | Slightly quieter | Most common problem area |
+| Mids | 500 Hz–2 kHz | Presence, character | ~Accurate to meters | Boxy, honky if excess |
+| Upper-mids | 2–5 kHz | **Peak sensitivity** | **10-15 dB louder** than bass at same dB | Most sensitive hearing range — small boosts are very audible |
+| Presence | 5–8 kHz | Sibilance, definition | **Louder** than metered | De-esser territory; a little goes a long way |
+| Air | 8–20 kHz | Sparkle, shimmer | Sensitivity drops off | Shelf boost for "expensive" sound; fatigue risk if overdone |
+
+### Gain Staging Targets (Perceived-Loudness-Aware)
+- Sub/bass instruments: -16 to -14 dBFS average (higher to compensate for lower perceived loudness)
+- Full-range instruments (piano, guitar): -18 dBFS average
+- Presence-range instruments (vocals, snare): -19 to -20 dBFS average (presence frequencies sound louder)
+- High-frequency instruments (cymbals, shakers): -20 to -22 dBFS average
 - Mix bus: -6 to -3 dBFS peak before mastering
 - Headroom for mastering: 4–6 dB