@mthines/reaper-mcp 0.6.0 → 0.8.0

package/README.md

@@ -17,24 +17,29 @@ npx @mthines/reaper-mcp setup
 
 # 2. In REAPER: Actions > Load ReaScript > select mcp_bridge.lua > Run
 
-# 3. Install AI mix knowledge in your project
-cd your-project
+# 3. Install AI mix knowledge (globally by default, or --project for local)
 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 +48,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 +77,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
@@ -87,18 +93,27 @@ This copies into your REAPER resource folder:
 
 You should see in REAPER's console: `MCP Bridge: Started`
 
-### Step 3: Install AI mix knowledge in your project
+### Step 3: Install AI mix knowledge
 
 ```bash
-cd your-music-project
+# Install globally (default) — available from any directory
 npx @mthines/reaper-mcp install-skills
+
+# Or install into a specific project
+cd your-music-project
+npx @mthines/reaper-mcp install-skills --project
 ```
 
-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`
-- `knowledge/` — plugin knowledge, genre rules, workflows, reference data
+**Global install** (`--global`, default) installs to `~/.claude/`:
+
+- `~/.claude/agents/` — mix engineer subagents (`@mix-engineer`, `@gain-stage`, `@mix-analyzer`, `@master`)
+- `~/.claude/rules/` — architecture and development rules
+- `~/.claude/skills/` — skills like `/learn-plugin`
+- `~/.claude/knowledge/` — plugin knowledge, genre rules, workflows, reference data
+
+**Project install** (`--project`) installs to your current directory:
+
+- `.claude/agents/`, `.claude/rules/`, `.claude/skills/`, `knowledge/` — same as above, scoped to the project
 - `.mcp.json` — MCP server configuration for Claude Code
 
 ### Step 4: Verify
@@ -109,29 +124,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 +160,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 +204,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,22 +238,23 @@ 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 |
 
 ## Using the Mix Agents
 
-Once you've run `setup` and `install-skills`, open Claude Code in your project directory. Four specialized mix agents are available:
+Once you've run `setup` and `install-skills`, open Claude Code. Four specialized mix agents are available:
 
 ### 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 +278,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 +296,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 +321,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 +348,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 +392,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"
     ]
   }
 }
@@ -321,7 +447,8 @@ The format is `mcp__reaper__{tool_name}`. Once added, Claude Code will run these
 npx @mthines/reaper-mcp                  # Start MCP server (default)
 npx @mthines/reaper-mcp serve            # Start MCP server (stdio mode)
 npx @mthines/reaper-mcp setup            # Install Lua bridge + JSFX into REAPER
-npx @mthines/reaper-mcp install-skills   # Install AI knowledge + agents into your project
+npx @mthines/reaper-mcp install-skills   # Install AI knowledge + agents (globally by default)
+npx @mthines/reaper-mcp install-skills --project  # Install into current project directory
 npx @mthines/reaper-mcp doctor           # Verify everything is configured
 npx @mthines/reaper-mcp status           # Check bridge connection
 ```
@@ -335,7 +462,7 @@ reaper-mcp setup
 
 ## Claude Code Integration
 
-After `install-skills`, your project has a `.mcp.json`:
+After `install-skills --project`, your project has a `.mcp.json`:
 
 ```json
 {
@@ -350,13 +477,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 +511,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 +529,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