@mthines/reaper-mcp 0.6.0 → 0.7.0

package/knowledge/reference/common-mistakes.md

@@ -286,11 +286,39 @@ Each mistake is listed with:
 
 ---
 
+## Category 7: Perceived Loudness Mistakes
+
+### 22. Balancing all tracks to the same meter level
+
+**Symptom**: Bass feels thin/absent; cymbals/vocals feel too loud; mix sounds "papery" with no weight despite good metering. The mixer set every track to -18 dBFS without accounting for psychoacoustic loudness perception.
+
+**Detection**:
+- All tracks read approximately the same RMS on meters
+- Bass instruments and vocal/cymbal tracks within 2 dB of each other on meters
+- Bass sounds much quieter than its meter reading suggests; cymbals/vocals pierce through
+
+**Fix**: Account for equal-loudness contours (ISO 226). The ear is 10-15 dB more sensitive at 2-5 kHz than at 100 Hz. Bass instruments should read 3-6 dB hotter than presence-range instruments on meters to sound balanced. Target: bass at -16 to -14 dBFS, vocals at -19 to -20 dBFS, cymbals at -20 to -22 dBFS. See `perceived-loudness.md` for full reference.
+
+---
+
+### 23. Treating a flat spectrum analyzer as "balanced"
+
+**Symptom**: Mix sounds harsh and presence-heavy despite a "flat" spectrum reading; listening fatigue within minutes.
+
+**Detection**:
+- Spectrum analyzer shows relatively flat response
+- But the mix sounds harsh, forward, or fatiguing
+- 2-5 kHz range is at the same level as bass range on analyzer
+
+**Fix**: A perceptually balanced mix shows a gentle downward slope on a spectrum analyzer, because the ear naturally amplifies the 2-5 kHz range. A truly "flat" spectrum will sound presence-heavy. Don't mix to a flat line — mix to what sounds balanced, which will show lower presence energy on the analyzer than bass energy.
+
+---
+
 ## Summary Checklist (Quick Audit)
 
 The agent runs through this checklist when performing a mix analysis ("roast my mix"):
 
-- [ ] Gain staging: all tracks averaging -18 dBFS before processing
+- [ ] Gain staging: perceived-loudness-aware targets (bass at -16 to -14, presence instruments at -19 to -20 dBFS)
 - [ ] Mix bus headroom: peaks at -6 to -3 dBFS before limiting
 - [ ] HPF applied to all non-bass instruments
 - [ ] Mud zone (250–500 Hz) checked and managed

package/knowledge/reference/frequencies.md

@@ -2,21 +2,23 @@
 
 A cheat sheet for the agent: what lives where, what to cut, what to boost, and why. All values are starting points — trust measurements over tables.
 
+**Key principle**: The human ear does not hear all frequencies equally (see `perceived-loudness.md`). The ear is 10-15 dB more sensitive at 2-5 kHz than at 100 Hz. This means EQ moves in the presence range have outsized perceptual impact, while low-end moves require larger dB changes to be noticed.
+
 ## Frequency Band Definitions
 
-| Band | Range | Sensory Description | Common Issues |
-|------|-------|-------------------|---------------|
-| Ultra-sub | 20–40 Hz | Felt in chest; inaudible on most speakers | Rumble, mic handling noise — usually remove |
-| Sub | 40–60 Hz | Bass and kick fundamental; club system territory | Too much = boomy; too little = thin |
-| Bass | 60–120 Hz | Warmth, punch, weight | Mud if over-accumulated |
-| Upper bass | 120–250 Hz | Body of bass instruments; low-end of most other instruments | The "mud zone begins here" |
-| Low-mids | 250–500 Hz | MUD ZONE — where amateur mixes go wrong | Cut aggressively on non-bass instruments |
-| Mids | 500 Hz–1 kHz | Honk, nasality, the "telephone frequency" | Source of unpleasant boxiness |
-| Upper-mids | 1–2 kHz | Presence, forward bite | Nasal buildup on male vocals, guitars |
-| Presence | 2–5 kHz | The MOST SENSITIVE zone to human hearing | Harshness lives here — treat with care |
-| Upper presence | 5–8 kHz | Sibilance, consonant clarity, definition | Over-boosting causes fatigue |
-| Brilliance | 8–12 kHz | Crispness, snap, transient sparkle | Can sound harsh if overdone |
-| Air | 12–20 kHz | Shimmer, openness, studio sound | Subtle — ±1–2 dB is audible here |
+| Band | Range | Sensory Description | Perceived Loudness (ISO 226) | Common Issues |
+|------|-------|-------------------|----------------------------|---------------|
+| Ultra-sub | 20–40 Hz | Felt in chest; inaudible on most speakers | **Very low** — needs huge dB to hear | Rumble, mic handling noise — usually remove |
+| Sub | 40–60 Hz | Bass and kick fundamental; club system territory | **Low** — requires +10-15 dB over 3 kHz to sound equal | Too much = boomy; too little = thin |
+| Bass | 60–120 Hz | Warmth, punch, weight | **Low** — requires +8-12 dB over 3 kHz | Mud if over-accumulated |
+| Upper bass | 120–250 Hz | Body of bass instruments; low-end of most other instruments | **Below average** — +5-8 dB to match 3 kHz | The "mud zone begins here" |
+| Low-mids | 250–500 Hz | MUD ZONE — where amateur mixes go wrong | **Slightly below** — +3-5 dB to match 3 kHz | Cut aggressively on non-bass instruments |
+| Mids | 500 Hz–1 kHz | Honk, nasality, the "telephone frequency" | **Near peak sensitivity** | Source of unpleasant boxiness |
+| Upper-mids | 1–2 kHz | Presence, forward bite | **Very sensitive** | Nasal buildup on male vocals, guitars |
+| Presence | 2–5 kHz | The MOST SENSITIVE zone to human hearing | **PEAK SENSITIVITY** — ear is loudest here | Harshness lives here — even +1 dB is very audible |
+| Upper presence | 5–8 kHz | Sibilance, consonant clarity, definition | **High sensitivity** — still louder than bass range | Over-boosting causes fatigue |
+| Brilliance | 8–12 kHz | Crispness, snap, transient sparkle | **Moderate** — sensitivity dropping off | Can sound harsh if overdone |
+| Air | 12–20 kHz | Shimmer, openness, studio sound | **Low** — sensitivity falls off steeply | Subtle — ±1–2 dB is audible here; fatigue risk with accumulation |
 
 ## High-Pass Filter Reference (Where to HPF each instrument)
 

package/knowledge/reference/metering.md

@@ -153,6 +153,23 @@ For a healthy mix signal chain:
 | Limiter output | 1 dBTP headroom | -1.0 dBTP |
 | Final export | Compliant with platform | Per platform spec |
 
+## Perceived Loudness vs. Metered Loudness
+
+**Critical concept**: Meters measure electrical/digital signal level, not what the listener actually hears. The human ear is 10-15 dB more sensitive at 2-5 kHz (presence range) than at 100 Hz (bass range). This has direct implications for how you interpret meter readings. See `perceived-loudness.md` for full reference.
+
+### What This Means for Metering
+
+| Scenario | Meter Says | Listener Hears | Correct Action |
+|----------|-----------|---------------|----------------|
+| Bass and vocal at same RMS | "Equal volume" | Bass is much quieter | Bass should read 3-6 dB hotter on meters |
+| Hi-hat and kick at same peak | "Equal transients" | Hi-hat is much louder | Pull hi-hat fader down 3-5 dB |
+| "Flat" spectrum on analyzer | "Balanced mix" | Presence-heavy, harsh | A well-balanced mix has a gentle downward slope on the analyzer |
+| LUFS matches target | "Correct loudness" | Depends on spectral content | LUFS uses K-weighting which partially compensates, but per-track balance still needs perceptual awareness |
+
+### LUFS and K-Weighting
+
+LUFS measurements already incorporate some psychoacoustic compensation via K-weighting (a +4 dB shelf at ~1.7 kHz + a 100 Hz high-pass). This means LUFS is better than raw RMS for perceived loudness — but it's a broadband measure. It tells you the overall perceived loudness, NOT whether individual instruments within the mix are perceptually balanced against each other. Per-track balance decisions still require perceived loudness awareness.
+
 ## Common Metering Mistakes
 
 | Mistake | Correct Practice |
@@ -164,3 +181,5 @@ For a healthy mix signal chain:
 | Not accounting for intersample peaks | Always use a true peak limiter (ISP mode) |
 | Comparing short-term LUFS between songs | Compare integrated LUFS for an apples-to-apples comparison |
 | Ignoring crest factor | A mix with good integrated LUFS but low crest factor is over-compressed |
+| Setting all tracks to the same dBFS target | Account for perceived loudness — bass instruments need higher meter readings than presence-range instruments |
+| Treating a "flat" spectrum as balanced | The ear amplifies 2-5 kHz naturally; a flat spectrum sounds harsh. Expect a gentle downward slope from low to high |

package/knowledge/reference/perceived-loudness.md

@@ -0,0 +1,122 @@
+# Perceived Loudness Reference
+
+Human hearing does not perceive all frequencies equally. A bass note and a vocal at the same dB SPL will sound like very different volumes. This reference helps the agent compensate for psychoacoustic loudness perception when balancing a mix — optimizing for what the listener actually hears, not just what the meters show.
+
+## Equal-Loudness Contours (ISO 226:2003)
+
+Equal-loudness contours (historically "Fletcher-Munson curves") map the SPL required at each frequency to sound equally loud to the human ear. Key takeaways:
+
+| Frequency Range | Perceived Loudness at Same dB | Implication for Mixing |
+|----------------|------------------------------|----------------------|
+| 20-80 Hz (sub/bass) | Sounds **much quieter** than meter shows | Bass instruments need higher dB to feel balanced |
+| 80-250 Hz (upper bass) | Sounds **somewhat quieter** | Warmth region; needs modest boost over mids |
+| 250 Hz-1 kHz (mids) | Sounds **roughly accurate** to meter | Meters are fairly reliable here |
+| 1-5 kHz (presence) | Sounds **louder** than meter shows | Most sensitive hearing range — a little goes a long way |
+| 2-5 kHz (peak sensitivity) | Sounds **significantly louder** | The ear is 10-15 dB more sensitive here than at 100 Hz |
+| 5-8 kHz (sibilance) | Sounds **louder** | Sibilance cuts through even at low levels |
+| 8-20 kHz (air) | Sensitivity **drops off** | Needs more energy to be perceived, but fatigues quickly if excessive |
+
+### The Critical Insight
+
+At moderate listening levels (~70-85 dB SPL, typical mixing/monitoring level):
+- **3-4 kHz is ~10-15 dB more sensitive** than 100 Hz
+- **A snare drum** (energy at 200 Hz + 2-5 kHz) sounds louder than **a bass guitar** (energy at 60-250 Hz) even at the same RMS dB reading
+- **Vocals** (fundamental 100-400 Hz, formants at 1-5 kHz) naturally cut through a mix because their energy is in the ear's most sensitive band
+- **Kick drum sub** (40-80 Hz) needs significantly more energy than hi-hats (8-12 kHz) to feel "present" — but hi-hats fatigue faster
+
+## Perceived Loudness by Instrument
+
+Instruments ranked by how loud they **sound** relative to their **metered level**, from "sounds louder than meters suggest" to "sounds quieter":
+
+| Instrument | Dominant Frequency Range | Perceived vs. Metered | Mixing Compensation |
+|-----------|------------------------|----------------------|-------------------|
+| Vocals | 1-5 kHz (formants) | Sounds **louder** | Can sit 2-4 dB below other elements on meters and still cut through |
+| Snare drum | 200 Hz + 2-5 kHz (crack) | Sounds **louder** | Crack frequency is in the sensitive zone; don't over-boost |
+| Hi-hat / cymbals | 6-12 kHz | Sounds **moderately louder** | Small dB changes are very audible; mix lower than you think |
+| Acoustic guitar | 2-5 kHz (string attack) | Sounds **moderately louder** | Attack frequency carries; back off presence boosts |
+| Electric guitar | 1-4 kHz (midrange) | Sounds **about right** | Meter-reading is fairly reliable for perceived level |
+| Piano | 250 Hz-4 kHz (wide range) | Sounds **about right** | Depends on register; upper notes sound louder than lower |
+| Kick drum | 60-100 Hz (thump) | Sounds **quieter** | Needs 3-6 dB more than meters suggest for balanced feel |
+| Bass guitar | 60-250 Hz (fundamental) | Sounds **quieter** | Needs 2-5 dB more on meters than mid-range instruments |
+| 808 / sub bass | 30-80 Hz | Sounds **much quieter** | On small speakers, nearly inaudible; rely on harmonics (150-300 Hz) |
+| Pads / drones | Varies | Depends on spectral content | Low pads need more level; bright pads need less |
+
+## How to Apply This When Mixing
+
+### Balance by Perception, Not Meters
+
+When setting initial track balance:
+
+1. **Don't match RMS levels across all tracks** — this makes bass instruments too quiet and presence-range instruments too loud
+2. **Bass instruments should read 3-6 dB hotter** on meters than vocals/guitars to sound "even" in the mix
+3. **Vocals can sit 2-4 dB lower on meters** than the instrumental bed and still sound prominent due to presence-range sensitivity
+4. **Hi-hats and cymbals at -3 dB lower on meters** than you'd expect — they punch through perceptually
+5. **After setting meter levels, always verify with your ears** — meters are a starting point, perception is the target
+
+### Gain Staging Adjustments
+
+The standard -18 dBFS target is a good starting point, but perceived-loudness-aware gain staging considers the instrument's spectral content:
+
+| Instrument Category | Meter Target (RMS) | Rationale |
+|-------------------|-------------------|-----------|
+| Sub/bass instruments | -16 to -14 dBFS | Higher on meters to compensate for lower perceived loudness |
+| Full-range instruments (piano, guitar) | -18 dBFS | Standard target; spectral content spans perceptual range |
+| Mid/presence instruments (vocals, snare) | -19 to -20 dBFS | Lower on meters; presence-range content sounds louder |
+| High-frequency instruments (cymbals, shakers) | -20 to -22 dBFS | Much lower on meters; high sensitivity frequencies carry easily |
+
+These are **starting points** — verify by ear and adjust for genre/arrangement context.
+
+### EQ Decisions Informed by Perception
+
+- **Boosting 2-5 kHz**: Even +1 dB is very audible here. Be conservative — the ear amplifies this range naturally.
+- **Cutting 200-400 Hz**: The ear is less sensitive here, so cuts may need to be larger (-3 to -6 dB) to make an audible difference.
+- **Boosting sub-bass (30-80 Hz)**: Large boosts (+4-6 dB) may be needed to feel present, but check on multiple speaker systems — headphones and club systems reproduce this range very differently.
+- **Air boosts (10-16 kHz)**: Sensitivity drops off, so +2-3 dB can sound subtle. But accumulated boosts across many tracks cause listening fatigue.
+
+### Compression and Dynamics
+
+- **Fast attack on presence-range instruments** (vocals, snare) tames perceived loudness spikes more effectively than on bass instruments
+- **Bass compression** with slower attack preserves the transient that helps the ear "locate" the note — critical since the fundamental is in a low-sensitivity range
+- **Sidechain filtering** on bus compressors: if the compressor is triggered by low-frequency content, it may pump on bass hits even though those hits don't sound that loud — use a sidechain HPF to make the compressor react to what the listener hears
+
+### Monitoring Level Matters
+
+Equal-loudness contours change shape at different SPL levels:
+- **Low monitoring levels** (~65 dB SPL): Bass and treble perception drops off dramatically. Mixes balanced at low volume tend to have too much bass and treble when played loud.
+- **Moderate levels** (~75-85 dB SPL): Best for critical balance decisions. The ear's response is most "flat" here.
+- **Loud levels** (~90+ dB SPL): Perception flattens further, but ear fatigue sets in quickly. Not reliable for balance.
+
+**Best practice**: Mix at a moderate, conversational level (~79 dB SPL is often cited). Check at low and high volumes occasionally, but make balance decisions at moderate levels.
+
+## Volume-Dependent Perception (The "Loudness Button" Effect)
+
+At lower playback volumes (casual listening, phone speakers):
+- Bass nearly disappears
+- Presence range dominates
+- The mix sounds "thin" compared to studio monitoring
+
+At higher playback volumes (club, concert):
+- Bass becomes overwhelming
+- Presence range can feel harsh
+- The mix sounds "boomy" compared to studio monitoring
+
+**Implication**: A well-balanced mix at moderate monitoring levels translates best across playback systems. Don't chase balance at extreme volumes.
+
+## Frequency Masking and Perceived Loudness
+
+Two instruments in the same frequency range don't just compete for spectral space — they mask each other's perceived loudness:
+
+- **Kick + bass** competing at 60-120 Hz: Neither sounds as loud as it would solo. Use sidechain compression or frequency separation (kick at 60 Hz, bass at 100 Hz) so each is perceived clearly.
+- **Vocals + guitars** competing at 1-4 kHz: Guitars mask vocal presence. Cut guitars 2-4 kHz or boost vocals there — a small EQ move has outsized perceptual impact because this is the sensitivity peak.
+- **Multiple instruments in the mud zone** (200-500 Hz): Cumulative energy in a low-sensitivity range creates "mud" — the ear can't separate the sources. HPF everything that doesn't need this range.
+
+## Quick Decision Guide
+
+| Situation | Wrong Approach | Perceived-Loudness-Aware Approach |
+|-----------|---------------|----------------------------------|
+| Bass feels too quiet | Boost bass until meters match vocals | Boost bass 3-5 dB above vocal meter reading; verify by ear |
+| Vocals feel buried | Boost vocal fader until it's the loudest meter | Check for 1-4 kHz masking from guitars/keys; small presence boost goes far |
+| Cymbals are harsh | They're not even that loud on meters! | Trust your ears — high-sensitivity frequencies are perceived louder. Pull fader down 2-3 dB |
+| Mix sounds thin | Boost everything below 200 Hz | Boost bass instruments specifically; check monitoring level (low volume exaggerates thinness) |
+| Mix sounds muddy | Cut all low-mids on every track | Focus cuts on instruments that don't need 200-500 Hz; the ear needs significant cuts here to notice |
+| Snare cracks through | But the meter says it's only -20 dBFS! | Normal — snare crack is at 2-5 kHz (peak sensitivity). It sounds right at lower meter readings |

package/knowledge/workflows/gain-staging.md

@@ -71,8 +71,11 @@ params:
 
 Record: peak level (dBFS), RMS level (dBFS) for each track.
 
-Target levels:
-- **Average/RMS**: -18 dBFS (±3 dB acceptable)
+Target levels (perceived-loudness-aware):
+- **Sub/bass instruments**: -16 to -14 dBFS RMS (sounds quieter than metered)
+- **Full-range instruments**: -18 dBFS RMS (±3 dB acceptable)
+- **Presence-range instruments**: -19 to -20 dBFS RMS (sounds louder than metered)
+- **High-frequency instruments**: -20 to -22 dBFS RMS
 - **Peak**: -12 dBFS (not exceeding -6 dBFS)
 
 If a track reads:
@@ -80,15 +83,25 @@ If a track reads:
 - Average of -8 dBFS → needs gain reduction
 - Peak of -3 dBFS → dangerously hot, reduce gain
 
-### Step 5: Calculate gain adjustments
+### Step 5: Calculate gain adjustments (perceived-loudness-aware)
+
+Use instrument-appropriate targets rather than a flat -18 dBFS for all tracks. The human ear is 10-15 dB more sensitive at 2-5 kHz than at 100 Hz, so bass instruments need higher meter readings to sound perceptually balanced (see `knowledge/reference/perceived-loudness.md`):
+
+| Instrument Category | Target RMS | Rationale |
+|-------------------|-----------|-----------|
+| Sub/bass (kick sub, bass, 808) | -16 to -14 dBFS | Low frequencies sound quieter than metered |
+| Full-range (piano, guitar, strings) | -18 dBFS | Standard target; spans the perceptual range |
+| Presence-range (vocals, snare, lead guitar) | -19 to -20 dBFS | 2-5 kHz content sounds louder than metered |
+| High-frequency (cymbals, hi-hats, shakers) | -20 to -22 dBFS | Very sensitive frequency range |
 
 For each track:
 ```
-gain_adjustment_dB = -18 - current_average_dBFS
+gain_adjustment_dB = target_dBFS - current_average_dBFS
 ```
 
-Example: Track averages -24 dBFS → needs +6 dB
-Example: Track averages -10 dBFS → needs -8 dB
+Example: Bass averages -24 dBFS → target -15 → needs +9 dB
+Example: Vocal averages -10 dBFS → target -19 → needs -9 dB
+Example: Piano averages -24 dBFS → target -18 → needs +6 dB
 
 Round to nearest 0.5 dB for practical purposes.
 
@@ -163,3 +176,4 @@ After completing gain staging:
 - **Ignoring bus tracks**: A drum bus that's receiving 8 inputs at -18 dBFS each will be summing to a much higher level. The bus fader controls the drum bus output level — check and adjust it.
 - **Single-moment readings**: Read meters over a representative 10+ second passage, not a single snapshot that may catch silence or a single loud peak.
 - **Not checking after gain staging**: Always play the mix after staging to confirm balance feels correct. The numbers are targets, not rules — use ears to verify.
+- **Setting all tracks to the same level**: A flat -18 dBFS on every track ignores psychoacoustic loudness perception. Bass instruments need higher readings; presence-range instruments need lower readings. See `knowledge/reference/perceived-loudness.md`.