@mthines/reaper-mcp 0.1.0

package/knowledge/workflows/gain-staging.md

@@ -0,0 +1,165 @@
+---
+name: Gain Staging
+id: gain-staging
+description: Set all track levels to -18 dBFS average before processing begins
+---
+
+# Gain Staging
+
+## When to Use
+
+At the START of every mix session, before any FX are inserted. Proper gain staging ensures:
+- All dynamics processors (compressors, limiters) operate in their optimal range
+- No internal overloads within the FX chain
+- Consistent headroom through the signal path
+- The mix bus has 6–10 dB of headroom before any limiting
+
+Run this workflow when:
+- Starting a new mix from raw tracks
+- After the session has grown (new tracks added, volumes changed)
+- When the mix bus is regularly clipping or hitting 0 dBFS
+- When compressors are not reacting as expected (threshold may be wrong due to staging)
+
+## Prerequisites
+
+- REAPER session is open with all tracks
+- Audio is playing or has been played (meters have registered levels)
+- No FX chains yet (or FX bypassed for the staging pass)
+- Transport is set to a representative section of the song (dense chorus, not just intro silence)
+
+## Step-by-Step
+
+### Step 1: Save a snapshot before starting
+
+Use `snapshot_save` to capture the current state before any changes.
+
+```
+tool: snapshot_save
+params:
+  name: "pre-gain-staging"
+  description: "State before gain staging workflow"
+```
+
+### Step 2: Get all tracks
+
+```
+tool: list_tracks
+```
+
+Identify: track count, track names, folder structure (look for bus/folder tracks).
+
+Skip tracks that are:
+- Mix bus / master bus
+- Reverb/delay return buses
+- Folder tracks (their volume is set separately)
+
+### Step 3: Play a representative section
+
+```
+tool: play
+```
+
+Play the densest, most representative section of the song (usually the chorus). Let it play for at least 10 seconds to build up meter readings.
+
+### Step 4: Read meters for all tracks
+
+```
+tool: read_track_meters
+params:
+  trackIndex: [each track index]
+```
+
+Record: peak level (dBFS), RMS level (dBFS) for each track.
+
+Target levels:
+- **Average/RMS**: -18 dBFS (±3 dB acceptable)
+- **Peak**: -12 dBFS (not exceeding -6 dBFS)
+
+If a track reads:
+- Average of -30 dBFS → needs gain increase
+- Average of -8 dBFS → needs gain reduction
+- Peak of -3 dBFS → dangerously hot, reduce gain
+
+### Step 5: Calculate gain adjustments
+
+For each track:
+```
+gain_adjustment_dB = -18 - current_average_dBFS
+```
+
+Example: Track averages -24 dBFS → needs +6 dB
+Example: Track averages -10 dBFS → needs -8 dB
+
+Round to nearest 0.5 dB for practical purposes.
+
+### Step 6: Apply gain adjustments via track fader
+
+```
+tool: set_track_property
+params:
+  trackIndex: [n]
+  property: "volume"
+  value: [gain_adjustment_dB]
+```
+
+Note: `set_track_property` with `volume` takes dB values. The fader is the correct place to set gain stage — not per-plugin input gain — so that the signal is correct before any processing.
+
+Apply to each track in order.
+
+### Step 7: Verify mix bus headroom
+
+After adjusting all tracks, read the mix bus meter:
+
+```
+tool: read_track_meters
+params:
+  trackIndex: [mix bus index — usually the last or master track]
+```
+
+Target: Mix bus should peak at -6 to -3 dBFS. If it's hitting 0 dBFS, pull all track faders down proportionally (or reduce master fader by the excess dB).
+
+### Step 8: Check instrument relationships
+
+Re-play the chorus section. Listen for:
+- Does the kick still hit harder than the snare? (relative levels should still feel musical)
+- Do vocals still sit over the instruments? (if not, the relative balance was off before; adjust individual tracks)
+
+If relative balance is wrong, apply additional individual adjustments AFTER the gain staging is complete. Gain staging sets the floor; the mix is built on top of it.
+
+### Step 9: Save post-staging snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "post-gain-staging"
+  description: "Gain staged — all tracks at -18 dBFS average"
+```
+
+## FX Chain Order (for the gain staging process itself)
+
+This workflow requires no FX. It uses only fader adjustments. After completion, insert FX in this order:
+
+1. Input gain trim (if using a gain plugin rather than the fader)
+2. EQ
+3. Compression
+4. Saturation / excitement
+5. Output trim
+
+Each stage should receive signal at approximately -18 dBFS average for optimal plugin behavior.
+
+## Verification
+
+After completing gain staging:
+
+1. Play the mix — average meter on mix bus should read approximately -18 to -12 dBFS RMS
+2. Peak on mix bus should not exceed -6 dBFS in the chorus
+3. Individual tracks should all be within ±6 dB of each other before mixing decisions (unless intentionally quiet elements like room mics)
+4. No individual track should be peaking above -6 dBFS before faders
+
+## Common Pitfalls
+
+- **Using clip gain vs fader**: Gain staging is done with the fader or a dedicated trim plugin, not clip gain (which bakes the level into the audio). Faders allow re-visiting.
+- **Staging with FX active**: Compressors and limiters on a track will affect the meter reading. Bypass all FX or stage to the raw audio level.
+- **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.

package/knowledge/workflows/low-end.md

@@ -0,0 +1,261 @@
+---
+name: Low-End Management
+id: low-end
+description: Fix and optimize the bass and sub frequencies in a mix
+---
+
+# Low-End Management
+
+## When to Use
+
+When the mix has low-frequency problems: too much bass, too little punch, muddy low-mids, kick and bass fighting each other, or bass that doesn't translate to small speakers. This is one of the most common mixing problems, especially for home studio mixes on desktop speakers with poor low-frequency response.
+
+Use this workflow when:
+- User says "the bass is muddy" or "too much low end"
+- User says "I can't hear the bass on earbuds/small speakers"
+- Kick drum is losing against bass guitar or vice versa
+- Mix sounds fine in the studio but thin or boomy elsewhere
+- User says "there's rumbling bass" or "the low end is out of control"
+
+## Prerequisites
+
+- Gain staging complete
+- All bass-producing tracks identified (kick, bass guitar, 808, synth bass, low keys)
+- Transport playing through a representative section (not intro silence)
+- Mix is audible (not just metered in silence)
+
+## Step-by-Step
+
+### Step 1: Save snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "pre-low-end"
+  description: "Before low-end management"
+```
+
+### Step 2: Identify all low-frequency tracks
+
+```
+tool: list_tracks
+```
+
+Identify every track contributing below 200 Hz:
+- Kick drum
+- Bass guitar / synth bass / 808
+- Piano (left hand)
+- Organ bass
+- Pads with sub content
+- Room mics (indirect bass)
+
+These tracks are the "low-end family" and need to be managed together, not individually in isolation.
+
+### Step 3: Spectrum analysis on each bass track
+
+For each bass-producing track:
+
+```
+tool: read_track_spectrum
+params:
+  trackIndex: [track index]
+```
+
+Record the approximate peak frequencies and energy distribution. Look for:
+- Where is the fundamental energy concentrated?
+- Is there energy below 30 Hz (ultra-sub — usually unwanted rumble)?
+- Where is the 200–400 Hz "mud zone" energy?
+
+### Step 4: Apply aggressive HPF to non-bass instruments
+
+The most effective low-end cleanup is removing bass from instruments that don't need it.
+
+For each non-bass track (guitar, piano high range, vocals, synths, cymbals):
+
+```
+tool: add_fx
+params:
+  trackIndex: [track index]
+  fxName: "Pro-Q3"  # or ReaEQ
+```
+
+Apply HPF at appropriate frequency (from reference/frequencies.md):
+
+| Instrument | HPF Frequency | Notes |
+|------------|--------------|-------|
+| Lead vocals | 80–100 Hz | |
+| Backing vocals | 100–120 Hz | |
+| Electric guitar (rhythm) | 80–120 Hz | Higher for metal |
+| Electric guitar (lead) | 80–100 Hz | |
+| Acoustic guitar | 80–120 Hz | |
+| Piano (if not bass role) | 80 Hz | |
+| Pads/synths | 80–150 Hz | Depends on register |
+| Snare | 100–150 Hz | |
+| Overheads | 200–400 Hz | Often 300+ Hz for tight overhead sound |
+| Room mics | 80–200 Hz | Depends on room character |
+| Any FX return | 100–200 Hz | Prevent verb/delay muddying bass |
+
+```
+tool: set_fx_parameter
+# Set Band 1 Type to HPF
+# Set Band 1 Frequency to target value (normalized)
+# Set Band 1 Slope to 24 dB/oct
+```
+
+This step alone often resolves 80% of low-end problems.
+
+### Step 5: Define the kick-bass relationship
+
+Kick and bass guitar must occupy different frequency zones or use sidechain compression to share the space dynamically. There are two approaches:
+
+**Approach A: Frequency splitting (static)**
+
+Assign each instrument to a specific zone:
+- Kick owns: 50–80 Hz (the punch/thump)
+- Bass guitar owns: 80–150 Hz (the warmth and note)
+
+On kick drum EQ:
+```
+tool: set_fx_parameter
+# Boost 60–70 Hz (+2 to +3 dB Bell)
+# Cut bass guitar's zone 100–150 Hz (-2 dB Bell)
+```
+
+On bass guitar EQ:
+```
+tool: set_fx_parameter
+# Boost 100–120 Hz (+2 dB Bell)
+# Dip at 60–80 Hz (-2 dB Bell) where kick lives
+```
+
+**Approach B: Sidechain compression (dynamic)**
+
+Kick triggers compression on the bass guitar — every time the kick hits, the bass ducks slightly, creating a rhythmic pump that's characteristic of many modern genres.
+
+```
+tool: add_fx
+params:
+  trackIndex: [bass guitar index]
+  fxName: "Pro-C2"
+```
+
+- Enable sidechain input from kick track
+- Ratio: 4:1–6:1
+- Attack: 1–5 ms (very fast, duck immediately)
+- Release: 50–150 ms (release before next kick)
+- Threshold: Set for 3–8 dB GR per kick hit
+
+### Step 6: Mono sum below 100 Hz (critical for translation)
+
+Bass below 100 Hz must be in mono for proper playback on:
+- Club sound systems (sub is mono)
+- Car audio (single sub)
+- Earbuds (stereo below 80 Hz causes imaging problems)
+- Bluetooth speakers
+
+Method A: Use a mid/side EQ to isolate the side channel and high-pass it at 100 Hz (removing bass from the sides):
+
+```
+tool: add_fx
+params:
+  trackIndex: [master bus or bass track]
+  fxName: "Pro-Q3"
+```
+
+In Pro-Q 3:
+- Add a band, set to Side channel only
+- Set band type to Low Cut (HPF)
+- Frequency: 100 Hz
+- Slope: 24 dB/oct
+
+This removes bass from the side information while leaving mid bass intact — effectively mono-summing below 100 Hz.
+
+Method B: Ensure bass tracks (kick, bass guitar) are themselves mono. Check that they are not panned or spread. A bass guitar should be center (0% pan).
+
+### Step 7: Cut the mud zone (250–500 Hz)
+
+The "mud zone" (250–500 Hz) is where most low-end muddiness lives. Multiple instruments stacking in this zone creates congestion.
+
+For each instrument with significant energy in this zone (check spectrum from Step 3):
+
+```
+tool: set_fx_parameter
+# On each instrument's EQ:
+# Add Bell band at 300–400 Hz
+# Gain: -2 to -4 dB
+# Q: 0.8–1.2 (wide cut)
+```
+
+The cumulative effect of cutting each instrument -2 to -3 dB in this zone clears the mud without making any single instrument sound thin.
+
+### Step 8: Control sub rumble below 30 Hz
+
+Any energy below 30 Hz is inaudible on most speakers but wastes headroom and causes distortion in amplifiers.
+
+On the master bus (or on bass-heavy individual tracks):
+
+```
+tool: add_fx
+params:
+  trackIndex: [master bus or bass guitar]
+  fxName: "Pro-Q3"
+```
+
+Apply HPF at 25–30 Hz with 12–24 dB/oct slope. This removes inaudible sub rumble without affecting the musical bass content.
+
+### Step 9: Bass translation check
+
+Play the mix and check how it translates on different systems. The agent can report spectrum readings to simulate this:
+
+```
+tool: read_track_spectrum
+params:
+  trackIndex: [master bus]
+```
+
+Check if bass energy (60–250 Hz) is balanced against midrange (500 Hz–2 kHz):
+- Bass-heavy: 60–250 Hz reads significantly higher than mids
+- Too thin: 60–250 Hz reads much lower than mids
+- Balanced: Within 6–10 dB of each other
+
+For small-speaker translation, ensure the 150–300 Hz range has content — this is where bass is "heard" on phone speakers.
+
+### Step 10: Save snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "post-low-end"
+  description: "Low-end management complete: HPF applied, kick-bass relationship defined, mono sum below 100 Hz"
+```
+
+## FX Chain Order (relevant to low-end management)
+
+Per bass instrument track:
+1. **HPF** (on all non-bass instruments — removes unnecessary low-end)
+2. **EQ** (frequency splitting — define kick vs bass zones)
+3. **Compressor** with sidechain (kick triggers bass ducking — optional but common)
+4. **Saturation** (for bass guitar — adds harmonics for small-speaker translation)
+
+On master bus:
+1. **HPF at 25–30 Hz** (remove inaudible rumble)
+2. **Mid/Side HPF on side channel at 100 Hz** (enforce mono bass)
+
+## Verification
+
+After completing low-end management:
+
+1. Mix bus spectrum should show smooth bass response, not a single boomy peak
+2. Kick should be clearly distinguishable from bass guitar rhythm at all dynamics
+3. Bass should still be audible when listening on phone speakers or earbuds (check 150–300 Hz)
+4. No audible rumble in quiet sections (floor noise, mic hum)
+5. Bass translation: if you can feel the kick and hear the bass note on small speakers, the low end is translating
+
+## Common Pitfalls
+
+- **Only fixing one instrument**: Low-end mud is cumulative. Cutting 2 dB from the bass guitar alone does nothing if 8 other tracks are adding to the mud. The HPF sweep across all non-bass instruments is the most powerful step.
+- **HPF too high on bass instruments**: Cutting the bass guitar above 60 Hz will make it disappear. The bass guitar IS the bass — preserve its fundamental.
+- **Stereo bass below 100 Hz**: Wide bass causes playback problems on mono systems. Always verify bass is mono below 100 Hz.
+- **Boosting bass vs cutting mud**: It is tempting to boost the bass to make it louder. Instead, cut the mud (250–500 Hz on competing instruments) — the bass will appear to come forward without actually being louder.
+- **Not checking kick-bass relationship separately**: Listen to kick and bass guitar alone together. They should lock and complement each other, not fight. If they fight, the frequency zones are overlapping.
+- **Missing sub-30 Hz content**: Low-end rumble below 30 Hz is inaudible but eats headroom. Always apply a gentle HPF on the master bus.

package/knowledge/workflows/master-bus.md

@@ -0,0 +1,204 @@
+---
+name: Master Bus
+id: master-bus
+description: Build the final mix bus processing chain for delivery
+---
+
+# Master Bus
+
+## When to Use
+
+When the mix is ready for final processing before export. The master bus chain adds the final glue compression, tonal shaping, and limiting that brings the mix to competitive loudness and prepares it for streaming delivery.
+
+Use this workflow when:
+
+- The mix is complete and all tracks are balanced
+- The user says "master this mix" or "prepare for delivery"
+- The mix needs to meet a specific LUFS target (Spotify -14, YouTube -14, Apple Music -16, club -8 to -6)
+- The mix bus has headroom (peaking at -6 to -3 dBFS before this chain)
+
+Important distinction: This is mix bus mastering (mixing the master), not mastering from a stereo file. Full mastering from a 2-track bounce requires different tools and more headroom. This workflow is appropriate for delivering a final mix from a REAPER session.
+
+## Prerequisites
+
+- Mix is balanced (all elements sitting correctly)
+- Gain staging is complete (mix bus peaks at -6 to -3 dBFS before this chain)
+- Genre is known (LUFS target depends on genre)
+- No existing processing on the master bus (or existing chain is documented and will be replaced)
+
+## Step-by-Step
+
+### Step 1: Save snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "pre-master-bus"
+  description: "Mix ready for master bus chain"
+```
+
+### Step 2: Check current mix bus headroom
+
+```
+tool: read_track_meters
+params:
+  trackIndex: [master bus / mix bus index — usually last track or master]
+```
+
+Play the loudest section (usually chorus). Record the peak level.
+
+If the mix bus is peaking above -3 dBFS: reduce all tracks or the master bus fader before proceeding. You need headroom for the master bus chain to work without clipping.
+If the mix bus is peaking above -3 dBFS: reduce all tracks or the master bus fader before proceeding. You need headroom for the master bus chain to work without clipping.
+
+If the mix bus is below -12 dBFS average: gain staging may be off — consider re-running the gain-staging workflow first.
+
+Ideal pre-master-bus level: -8 to -6 dBFS peaks, -18 to -14 dBFS average RMS.
+
+### Step 3: Add glue compressor
+
+Select: Pro-C 2 Classic mode preferred, ReaComp as fallback.
+
+```
+tool: add_fx
+params:
+  trackIndex: [master bus index]
+  fxName: "Pro-C2"
+```
+
+Settings (transparent glue — very subtle):
+
+| Parameter     | Value             | Why                               |
+| ------------- | ----------------- | --------------------------------- |
+| Style         | Classic (VCA)     | Warm, cohesive glue               |
+| Ratio         | 2:1               | Gentle                            |
+| Attack        | 10–30 ms          | Preserve transients               |
+| Release       | Auto              | Program-dependent — musical       |
+| Threshold     | Set for 1–2 dB GR | Very light touch                  |
+| Knee          | 6–12 dB           | Maximum transparency              |
+| Sidechain HPF | 80 Hz             | Prevent bass from over-triggering |
+
+Play the loudest section. Adjust threshold until GR meter shows 1–2 dB maximum reduction. This should be nearly inaudible but make the mix feel more cohesive when bypassed and engaged.
+
+### Step 4: Add EQ (optional — corrective only)
+
+Only add if the mix has identifiable frequency imbalances that couldn't be fixed at the track level.
+
+```
+tool: add_fx
+params:
+  trackIndex: [master bus index]
+  fxName: "Pro-Q3"  # or ReaEQ — use linear phase mode for mastering
+```
+
+Common master bus EQ moves (use sparingly, max ±2 dB):
+
+| Move                                           | When to Use                            |
+| ---------------------------------------------- | -------------------------------------- |
+| Low shelf cut at 60 Hz, -1 to -2 dB            | Mix is bass-heavy, lacking clarity     |
+| Bell cut at 250–400 Hz, -1 to -2 dB            | Mix sounds muddy or congested          |
+| Bell cut at 2–4 kHz, -0.5 to -1 dB             | Mix sounds harsh on extended listening |
+| High shelf boost at 10–12 kHz, +0.5 to +1.5 dB | Mix sounds dull or lacks air           |
+
+Use Pro-Q 3 in Linear Phase mode on the master bus to avoid phase distortion at low frequencies.
+
+### Step 5: Add limiter for loudness target
+
+Select: Pro-L 2 preferred, ReaLimit as fallback.
+
+```
+tool: add_fx
+params:
+  trackIndex: [master bus index]
+  fxName: "Pro-L2"
+```
+
+Determine LUFS target from genre:
+
+- Spotify / YouTube streaming: -14 LUFS integrated, -1.0 dBTP
+- Apple Music: -16 LUFS integrated, -1.0 dBTP
+- Club / EDM: -8 to -6 LUFS integrated, -0.3 dBTP
+- Hip-hop: -10 to -7 LUFS integrated, -0.3 dBTP
+- Film/TV/broadcast: -23 LUFS (EBU R128)
+
+Settings for streaming (-14 LUFS):
+
+| Parameter    | Value                   | Why                             |
+| ------------ | ----------------------- | ------------------------------- |
+| Style        | Transparent or Allround | Clean limiting                  |
+| Output Level | -1.0 dBFS               | -1 dBTP ceiling                 |
+| ISP          | on                      | True peak detection             |
+| Transients   | 40–60%                  | Preserve some punch             |
+| Lookahead    | 1–4 ms                  |                                 |
+| LUFS Target  | -14 LUFS                | Set via the built-in LUFS meter |
+
+Play the full song and check the integrated LUFS reading. The integrated LUFS is calculated over the full song, not a short section.
+
+Adjust Input Gain on Pro-L 2 to hit the target:
+
+- If integrated reads -17 LUFS and target is -14: add +3 dB Input Gain
+- If integrated reads -11 LUFS and target is -14: reduce Input Gain by 3 dB
+
+Watch the GR meter on the limiter:
+
+- Average 0.5–2 dB GR: Good — the mix is being lightly limited
+- Average 4+ dB GR: The mix is too loud before the limiter; reduce compressor stage or fix upstream
+
+### Step 6: Check mono compatibility
+
+```
+tool: read_track_spectrum
+params:
+  trackIndex: [master bus index]
+```
+
+Play the mix while mentally imagining it summed to mono. If there are frequency-specific dips (comb filtering), it indicates phase issues from stereo reverbs or wide processing. Flag to user if significant problems are found.
+
+The Correlation Meter JSFX (if installed) will show this directly: values near +1.0 = good mono compatibility; values near 0 or negative = phase issues.
+
+### Step 7: Verify delivery specs
+
+| Check           | Target                                       |
+| --------------- | -------------------------------------------- |
+| Integrated LUFS | Genre target (see Step 5)                    |
+| True peak       | -1.0 or -0.3 dBTP (genre dependent)          |
+| Crest factor    | 8+ dB for mixed music; 12+ dB for orchestral |
+| Low end mono    | No audible phase problems below 100 Hz       |
+| Stereo width    | Correlation > 0.7 on full mix                |
+
+### Step 8: Save final snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "master-complete"
+  description: "Master bus chain complete — ready for export"
+```
+
+## FX Chain Order (on the master bus)
+
+1. **Glue compressor** (VCA, very light — 1–2 dB GR)
+2. **EQ** (optional — linear phase, corrective only, ±2 dB max)
+3. **Saturation** (optional — extremely subtle, adds harmonic density)
+4. **Limiter** (brickwall, LUFS targeting, true peak detection)
+
+Optionally before the compressor:
+
+- **Multiband compressor** (only if specific frequency bands need control that single-band comp can't handle)
+- **Stereo imager** (only if mono compatibility is poor — careful)
+
+## Verification
+
+1. Play the full mix A/B against a pre-master-bus snapshot — the master chain should make the mix sound fuller and more cohesive, not just louder
+2. Check the limiter's GR: should be gentle, not constant heavy limiting
+3. Export a 30-second clip and check on headphones, phone speaker, and car audio
+4. Verify LUFS integrated reading matches the target platform
+5. Check that transients are still felt (kick punch, snare snap) despite limiting
+
+## Common Pitfalls
+
+- **Master bus too loud before the chain**: If peaks are above -3 dBFS before the limiter, the limiter is doing too much work. Fix the mix upstream.
+- **Heavy glue compression + heavy limiting**: Double processing. If the compressor is doing 4+ dB GR and the limiter is doing 4+ dB GR, the mix is being over-squashed. Choose one.
+- **Linear phase EQ artifacts**: Linear phase EQ adds pre-ringing at low frequencies with heavy processing. Keep EQ moves subtle on the master bus.
+- **Chasing loud**: Increasing the limiter's Input Gain to match a loud reference track can destroy the dynamics and make the mix sound flat. Trust the LUFS target.
+- **Exporting without checking LUFS**: Integrated LUFS requires measuring the entire song. A 30-second check is not sufficient for integrated measurement. Play the full song with the LUFS meter running.
+- **Not saving a pre-master snapshot**: Always save a snapshot before adding master bus processing. The user may want to A/B compare.