@mthines/reaper-mcp 0.8.0 → 0.9.0

package/claude-agents/stems.md

@@ -0,0 +1,135 @@
+---
+name: stems
+description: Stem preparation specialist — verifies bus structure, routing, naming, and technical specs for stem export. Use for "prepare stems", "check routing for export", or "stem prep".
+tools: Read, Glob
+mcpServers:
+  - reaper
+model: sonnet
+permissionMode: acceptEdits
+---
+
+# Stem Preparation Agent
+
+You are a stem preparation specialist for REAPER DAW. Your job is to verify the session's bus structure, routing, and naming conventions are correct so that exported stems will sum to match the full mix exactly. You ensure everything is export-ready.
+
+**Stems that don't sum to match the full mix are useless.** Your job is to guarantee they will.
+
+---
+
+## Workflow
+
+### Step 1: Save a safety snapshot
+```
+tool: snapshot_save
+params: { name: "pre-stem-prep", description: "State before stem preparation" }
+```
+
+### Step 2: Map the full routing hierarchy
+```
+tool: get_project_info
+tool: list_tracks
+```
+
+For every track, document its routing:
+```
+tool: get_track_routing
+params: { trackIndex: N }
+```
+
+Build a complete routing map: source tracks → buses → master.
+
+### Step 3: Verify stem groups
+
+Standard stem groups:
+
+| Stem | Contains |
+|------|----------|
+| Drums | Kick, Snare, Toms, OH, Room |
+| Bass | Bass DI, Bass Amp |
+| Guitars | All guitar tracks |
+| Keys/Synths | Piano, Organ, Pads, Leads |
+| Vocals | Lead, BVs, Harmonies |
+| Effects | Printed reverbs, delays |
+
+For each bus:
+```
+tool: get_track_properties
+params: { trackIndex: BUS_INDEX }
+```
+
+### Step 4: Check for routing problems
+
+Flag these issues:
+
+1. **Orphan tracks** — routing directly to master, bypassing buses
+2. **Double-routing** — a track sending to both a bus AND master (will be counted twice)
+3. **Missing tracks** — muted or no-output tracks that should be active
+4. **Send-only tracks** — reverb/delay returns not captured in any stem
+5. **Master bus processing** — FX on master that won't be in individual stems
+
+### Step 5: Verify naming conventions
+
+Check bus names are clear for delivery:
+```
+tool: get_track_properties
+params: { trackIndex: BUS_INDEX }
+```
+
+Expected format: `[Song Title]_[Stem Name]_[Bit Depth]-[Sample Rate]`
+
+Rename if needed:
+```
+tool: set_track_property
+params: { trackIndex: BUS_INDEX, property: "name", value: "Drum Bus" }
+```
+
+### Step 6: Verify technical specs
+```
+tool: get_project_info
+```
+
+Confirm:
+- Sample rate matches delivery requirement
+- All stems will have the same duration (full song length)
+- No sample rate mismatches between tracks
+
+### Step 7: Generate stem map report
+
+```
+## Stem Map
+
+| Stem | Bus Track | Source Tracks | Bus FX | Status |
+|------|-----------|---------------|--------|--------|
+| Drums | Track 15 | Kick, Snare, Tom 1, Tom 2, OH L, OH R | Comp, EQ | OK |
+| Bass | Track 16 | Bass DI, Bass Amp | Comp | OK |
+| ... | ... | ... | ... | ... |
+
+### Technical Specs
+- Sample Rate: [X] kHz
+- Bit Depth: 24-bit
+- Duration: [X] seconds
+
+### Master Bus Processing (NOT in stems)
+- [List of master bus FX]
+
+### Issues Found
+- [Any routing problems, orphan tracks, etc.]
+```
+
+### Step 8: Save post-prep snapshot
+```
+tool: snapshot_save
+params: { name: "post-stem-prep", description: "Stems verified — routing correct, naming consistent" }
+```
+
+---
+
+## Rules
+
+- **Don't export** — your job is verification and preparation, not the actual bounce/export
+- **Always save a snapshot first**
+- **Every source track must route through exactly one bus** — no orphans, no double-routing
+- **Document everything** — the stem map report should be clear enough for anyone to export correctly
+- **Flag master bus processing** — the user needs to know which FX are on the master bus and won't be in individual stems
+- **Check mute states** — a muted track won't export. Verify all intended tracks are unmuted.
+- Read `knowledge/workflows/stem-prep.md` for the detailed reference workflow

package/knowledge/workflows/delivery.md

@@ -0,0 +1,202 @@
+---
+name: Delivery
+id: delivery
+description: Verify final masters meet platform delivery specs — LUFS, true peak, format requirements
+---
+
+# Delivery
+
+## When to Use
+
+As the final step in the production workflow. Delivery verification ensures the finished master meets the technical requirements of target platforms before export.
+
+Use this workflow when:
+- The master is complete and ready for distribution
+- You need to verify specs for a specific platform (Spotify, Apple Music, CD, club, broadcast)
+- A mastering engineer or distributor has requested specific delivery specs
+- You want a final QA pass before bouncing the final file
+
+## Prerequisites
+
+- Mastering is complete (master bus chain is finalized)
+- Target platform(s) are known
+- The session plays back correctly from start to finish
+- LUFS metering is available
+
+## Step-by-Step
+
+### Step 1: Identify target platforms
+
+Determine which platforms the master will be delivered to. Each has different specs:
+
+| Platform | Integrated LUFS | True Peak | Sample Rate | Bit Depth | Format |
+|----------|----------------|-----------|-------------|-----------|--------|
+| Spotify / YouTube | -14 LUFS | -1.0 dBTP | 44.1+ kHz | 24-bit | WAV/FLAC |
+| Apple Music | -16 LUFS | -1.0 dBTP | 44.1-96 kHz | 24-bit | WAV |
+| Apple Digital Masters | -16 LUFS | -1.0 dBTP | 96 kHz | 24-bit | WAV |
+| Tidal / Amazon HD | -14 LUFS | -1.0 dBTP | 44.1-96 kHz | 24-bit | WAV/FLAC |
+| CD (Red Book) | -9 to -14 LUFS | -0.3 dBTP | 44.1 kHz | 16-bit | WAV (dithered) |
+| Club / DJ | -6 to -9 LUFS | -0.1 dBTP | 44.1-48 kHz | 24-bit | WAV |
+| Broadcast (EBU R128) | -23 LUFS | -1.0 dBTP | 48 kHz | 24-bit | BWF |
+| Broadcast (ATSC A/85) | -24 LUFS | -2.0 dBTP | 48 kHz | 24-bit | BWF |
+| Vinyl pre-master | N/A | N/A | 96 kHz | 24/32-bit | WAV |
+
+### Step 2: Measure current loudness
+
+Play the full song from start to finish for integrated LUFS measurement:
+
+```
+tool: read_track_lufs
+params:
+  trackIndex: [master bus index]
+```
+
+Record:
+- Integrated LUFS
+- Short-term LUFS (max)
+- Momentary LUFS (max)
+- True peak (dBTP)
+- Loudness range (LRA)
+
+### Step 3: Verify frequency balance
+
+```
+tool: read_track_spectrum
+params:
+  trackIndex: [master bus index]
+```
+
+Check for:
+- **Sub rumble** below 30 Hz (should be minimal)
+- **Low-end balance** (60-250 Hz appropriate for genre)
+- **Mud buildup** (250-500 Hz — should not be dominant)
+- **Harshness** (2-5 kHz — check against perceived loudness expectations)
+- **Air/presence** (8-20 kHz — should be present but not harsh)
+
+A well-mastered track typically shows a gentle downward slope from low to high frequencies on a spectrum analyzer.
+
+### Step 4: Check dynamics
+
+```
+tool: read_track_crest
+params:
+  trackIndex: [master bus index]
+```
+
+Crest factor targets by genre:
+- **Orchestral/Classical**: 14-20+ dB (maximum dynamic range)
+- **Jazz/Folk**: 12-16 dB
+- **Rock/Pop**: 8-12 dB
+- **Hip-Hop/R&B**: 6-10 dB
+- **EDM/Club**: 6-8 dB
+
+If crest factor is below 6 dB, the master is likely over-compressed.
+
+### Step 5: Verify stereo image
+
+```
+tool: read_track_correlation
+params:
+  trackIndex: [master bus index]
+```
+
+Check:
+- **Correlation > 0.7**: Good mono compatibility (safe for all playback systems)
+- **Correlation 0.3-0.7**: Wide stereo (check mono playback carefully)
+- **Correlation < 0.3**: Very wide or phase issues (will sound thin on mono systems)
+- **Correlation < 0**: Phase cancellation (FIX THIS — will disappear on mono systems)
+
+### Step 6: Check peak levels
+
+```
+tool: read_track_meters
+params:
+  trackIndex: [master bus index]
+```
+
+Verify peak levels are below the true peak ceiling for the target platform:
+- Streaming: peaks below -1.0 dBTP
+- CD: peaks below -0.3 dBTP
+- Club: peaks below -0.1 dBTP
+- Broadcast: peaks below -1.0 dBTP (EBU) or -2.0 dBTP (ATSC)
+
+### Step 7: Verify session specs
+
+```
+tool: get_project_info
+```
+
+Confirm:
+- Sample rate matches delivery requirement
+- Session is playing back without errors
+- Project tempo and time signature are correct (metadata)
+
+### Step 8: Generate delivery checklist
+
+Compile a report for the user:
+
+```
+## Delivery Report
+
+### Target Platform: [platform]
+| Spec | Target | Measured | Status |
+|------|--------|----------|--------|
+| Integrated LUFS | [target] | [measured] | PASS/FAIL |
+| True Peak | [target] dBTP | [measured] dBTP | PASS/FAIL |
+| Crest Factor | [target range] dB | [measured] dB | PASS/FAIL |
+| Stereo Correlation | > 0.3 | [measured] | PASS/FAIL |
+| Sample Rate | [target] kHz | [measured] kHz | PASS/FAIL |
+| Sub Rumble (< 30 Hz) | Minimal | [observation] | PASS/FAIL |
+
+### Export Instructions
+- Format: [WAV/FLAC/BWF]
+- Bit Depth: [16/24/32-bit]
+- Sample Rate: [kHz]
+- Dithering: [Yes (16-bit only) / No]
+- Filename: [SongTitle]_[Platform]_[BitDepth]-[SampleRate].[ext]
+
+### Notes
+- [Any concerns, compromises, or recommendations]
+```
+
+## Platform-Specific Notes
+
+### Spotify / YouTube
+- These platforms normalize loudness to -14 LUFS. Masters louder than -14 will be turned DOWN.
+- Masters quieter than -14 will be turned UP (with potential for clipping if true peak is close to 0).
+- Best practice: master to -14 LUFS with -1.0 dBTP ceiling.
+
+### Apple Music
+- Normalizes to -16 LUFS. Slightly quieter target.
+- Apple Digital Masters program requires 24-bit/96 kHz source files.
+- High-res lossless badge requires meeting Apple's toolchain specs.
+
+### CD (Red Book)
+- 16-bit requires dithering from 24-bit source (TPDF or noise-shaped dither).
+- 44.1 kHz mandatory — sample rate conversion needed if session is at 48+ kHz.
+- True peak ceiling should be -0.3 dBTP to account for inter-sample peaks after D/A conversion.
+
+### Club / DJ
+- Louder targets (-6 to -9 LUFS) are acceptable and expected.
+- Sub bass must be tight and controlled (club systems are very revealing below 60 Hz).
+- True peak ceiling can be tighter (-0.1 dBTP) since playback is on professional systems.
+
+### Broadcast (EBU R128 / ATSC A/85)
+- Strict loudness standards enforced by regulation.
+- EBU R128: -23 LUFS ± 0.5, loudness range (LRA) should be appropriate for content.
+- ATSC A/85: -24 LUFS (used in North American broadcast).
+
+### Vinyl
+- No excessive sub-bass below 30 Hz (causes needle skip)
+- Controlled sibilance (excessive high frequencies cause distortion on inner grooves)
+- Mono bass below 300 Hz recommended (prevents groove wall issues)
+- Dynamic range is welcome — vinyl handles dynamics well
+- Separate master from digital — vinyl mastering is its own discipline
+
+## Common Pitfalls
+
+- **Not measuring full-song integrated LUFS**: Short-term or momentary readings are NOT the delivery spec. Play the entire song for integrated measurement.
+- **Ignoring true peak**: Digital-to-analog conversion creates inter-sample peaks. True peak (ISP) meters catch these; regular peak meters don't. Always check true peak.
+- **Same master for all platforms**: A -14 LUFS streaming master won't work for club play (-6 to -9 LUFS needed). Create separate masters for different delivery targets.
+- **Forgetting dither for 16-bit**: Converting 24-bit to 16-bit without dither introduces quantization distortion. Always apply TPDF dither.
+- **Over-relying on numbers**: Delivery specs are minimum requirements, not the only quality measure. A master that hits -14 LUFS but sounds distorted still needs work.

package/knowledge/workflows/editing.md

@@ -0,0 +1,251 @@
+---
+name: Editing
+id: editing
+description: Edit audio items for mix-readiness — crossfades, timing, phase alignment, cleanup
+---
+
+# Editing
+
+## When to Use
+
+After session preparation and before gain staging. Editing makes raw recorded performances mix-ready by fixing timing, managing transitions, cleaning up noise, and ensuring phase coherence between related microphones.
+
+Use this workflow when:
+- Raw recorded tracks need cleanup before mixing
+- There are audible clicks or pops at edit points (missing crossfades)
+- Drum timing needs tightening
+- Multi-mic recordings have phase issues (kick in/out, snare top/bottom, DI + amp)
+- Tracks have noise, bleed, or unwanted sounds between performances
+- The arrangement needs structural changes (cut a verse, extend a chorus)
+
+## Prerequisites
+
+- Session preparation is complete (tracks named, organized, routed)
+- REAPER session is open with all recorded tracks
+- You understand the song structure (markers placed in session prep)
+- Transport is functional (can play, stop, navigate)
+
+## Step-by-Step
+
+### Step 1: Save a safety snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "pre-editing"
+  description: "State before audio editing"
+```
+
+### Step 2: Inventory media items per track
+
+```
+tool: list_tracks
+```
+
+For each track, get an overview of media items:
+
+```
+tool: list_media_items
+params:
+  trackIndex: [n]
+```
+
+Note: item count, positions, lengths, gaps between items, any overlapping items.
+
+### Step 3: Phase check multi-mic recordings
+
+For tracks that share a source (e.g., kick in + kick out, snare top + snare bottom, DI + amp), check phase coherence:
+
+```
+tool: read_track_correlation
+params:
+  trackIndex: [first track]
+```
+
+If correlation is negative or very low (< 0.3), the tracks may need phase alignment:
+
+1. Check if polarity flip fixes it:
+```
+tool: set_track_property
+params:
+  trackIndex: [n]
+  property: "phase"
+  value: true
+```
+
+2. If polarity flip doesn't help, time-align by nudging the item:
+```
+tool: get_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: 0
+```
+Then adjust position to align transients:
+```
+tool: set_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: 0
+  position: [adjusted seconds]
+```
+
+### Step 4: Crossfade management
+
+Check all edit points for smooth transitions. Every splice point needs a crossfade to prevent clicks:
+
+For items that are adjacent or overlapping:
+```
+tool: get_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+```
+
+Apply short crossfades at edit points:
+```
+tool: set_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+  fadeInLength: 0.005
+  fadeOutLength: 0.005
+```
+
+Standard crossfade lengths:
+- **Percussive edits** (drums, transients): 2-5 ms
+- **Sustained sounds** (vocals, pads): 10-50 ms
+- **Comp edit points** (between takes): 20-100 ms
+
+### Step 5: Timing alignment with stretch markers
+
+For performances that drift from the grid, use stretch markers to align without cutting:
+
+```
+tool: get_stretch_markers
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+```
+
+Add stretch markers at transients that need realignment:
+```
+tool: add_stretch_marker
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+  position: [item-relative seconds — where in the item the marker goes]
+  sourcePosition: [where this point maps to in the source audio]
+```
+
+Timing alignment priorities:
+1. **Kick drum** — the rhythmic anchor, align to grid first
+2. **Snare** — lock to grid or slightly behind for groove
+3. **Bass** — align note attacks to kick drum hits
+4. **Rhythm guitars** — align strums to kick/snare pattern
+5. **Vocals** — nudge phrases to sit naturally, don't over-quantize
+
+### Step 6: Head and tail cleanup
+
+Ensure clean silence before the first downbeat and appropriate decay at the end:
+
+Check the first and last items on each track:
+```
+tool: get_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: 0
+```
+
+Trim heads (remove pre-roll noise):
+```
+tool: trim_media_item
+params:
+  trackIndex: [n]
+  itemIndex: 0
+  trimStart: [seconds to trim inward]
+```
+
+Apply fade-ins to track starts:
+```
+tool: set_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: 0
+  fadeInLength: 0.01
+```
+
+Apply fade-outs to track ends:
+```
+tool: set_media_item_properties
+params:
+  trackIndex: [n]
+  itemIndex: [last]
+  fadeOutLength: 0.05
+```
+
+### Step 7: Arrangement editing (if needed)
+
+If the song structure needs changes (cut a section, extend, rearrange):
+
+Split items at section boundaries:
+```
+tool: split_media_item
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+  position: [seconds — absolute project time]
+```
+
+Move sections:
+```
+tool: move_media_item
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+  newPosition: [seconds]
+```
+
+Delete unwanted sections:
+```
+tool: delete_media_item
+params:
+  trackIndex: [n]
+  itemIndex: [n]
+```
+
+**Important**: When rearranging, process ALL tracks at each section boundary to keep everything in sync. Do not move items on one track without moving corresponding items on all other tracks.
+
+### Step 8: Strip silence / gap cleanup
+
+For tracks with long silences between performances (e.g., vocal tracks with silence between verses):
+
+Identify items with excessive silence by checking positions and lengths. Items far apart with no content between them are candidates for trimming or splitting.
+
+### Step 9: Save post-editing snapshot
+
+```
+tool: snapshot_save
+params:
+  name: "post-editing"
+  description: "Audio editing complete — crossfades, timing, phase, cleanup done"
+```
+
+## Verification
+
+After completing audio editing:
+
+1. No clicks or pops at any edit point (all splices have crossfades)
+2. Multi-mic recordings are phase-coherent (correlation > 0.5)
+3. Timing is tight (kick and bass locked, drums on grid or grooved consistently)
+4. Heads and tails are clean (no pre-roll noise, appropriate decays)
+5. Song structure is correct (if arrangement was edited)
+6. All tracks start and end cleanly
+
+## Common Pitfalls
+
+- **Over-editing timing**: Some genres (jazz, folk, indie) rely on human feel. Don't grid-lock everything — only tighten where timing is distractingly loose
+- **Missing crossfades**: Every edit point needs at least a 2 ms crossfade. One missed crossfade = one audible click
+- **Phase-flipping without checking**: Flipping polarity helps when signals are ~180 degrees out, but can make things worse if they're only partially misaligned. Always measure correlation before and after
+- **Editing tracks independently**: Multi-mic drum recordings must be edited as a group — if you nudge the snare top, the snare bottom and overheads must move with it
+- **Destructive arrangement edits**: Always save a snapshot before rearranging sections. One wrong split or delete can be very hard to undo manually
+- **Ignoring stretch marker artifacts**: Heavy time-stretching introduces artifacts (metallic sound, pitch warbling). If stretch is more than ~10%, consider re-recording instead