@mthines/reaper-mcp 0.19.0 → 0.70.2

package/claude/knowledge/reference/memory-protocol.md

@@ -0,0 +1,377 @@
+# Memory Protocol
+
+How the mix skills recall and persist what they know.
+
+| What | Where |
+|------|-------|
+| **Reference knowledge** — genres, workflows, reference material | `~/.claude/knowledge/` (symlink to the repo's `knowledge/`, versioned in git) |
+| **Plugin knowledge + process lessons** | **LoreKit**, scope `project::reaper-mcp`, via the `memory.*` MCP tools — in two layers, below |
+
+## The two layers
+
+| Layer | Owner | Keys | Tag | Who writes it |
+|-------|-------|------|-----|---------------|
+| **Built-in** | the `reaper-mcp` LoreKit org — curated by the maintainer | `plugins::<vendor>/<plugin>`, `mixing-lessons::<slug>` | `layer::built-in` | Only the maintainer, via `/mix-memory publish`. **Read-only for the skills.** |
+| **User** | each user's personal store | `user::plugins::<vendor>/<plugin>`, `user::mixing-lessons::<slug>` | `layer::user` | The mix skills, automatically, for whoever runs them |
+
+**Reading the built-in layer — everyone, no LoreKit account needed:** the `reaper`
+MCP server ships a public read-only LoreKit token and exposes the layer as two tools:
+
+| Tool | Does |
+|------|------|
+| `list_builtin_knowledge { kind?, tags?, query?, limit? }` | `kind`: `plugins` / `lessons` / `all`. Without `query`: summaries (key, tags, preview), `tags` OR-filtered (e.g. `["category::eq"]`). With `query`: full-text search with full bodies |
+| `get_builtin_knowledge { key }` | One record by its built-in key (`plugins::…` / `mixing-lessons::…`), or `record: null` |
+
+**Reading and writing the user layer** goes through the user's own LoreKit
+connection (`memory.*`). Org members also get the built-in rows back from `memory.*`
+(org and personal rows come back together); the `layer::` tag tells them apart
+(responses carry no owner field), so every record carries one — skip
+`layer::built-in` rows there, the built-in tools already returned them.
+
+Without the user's own LoreKit connected, the skills still get the built-in layer;
+they just can't write anything.
+
+### Hard rules for the two layers
+
+1. **Never write a built-in key** (`plugins::…`, `mixing-lessons::…`) from a skill.
+   Every skill write goes to the `user::` key, with no `org`.
+2. **Never `memory.delete` a built-in key.** A delete without `org` archives
+   *every* row with that scope + key the caller can write — for an org member that
+   includes the built-in row. Only ever delete `user::` keys.
+3. **The `user::` prefix is mandatory, not cosmetic.** When a personal row and an org
+   row share scope + key, `memory.read` silently returns whichever was updated
+   last; distinct keys are what keep both layers visible.
+
+**Not connected?** If the `memory.*` tools are unavailable, say so in one line and
+continue on the built-in layer plus general mixing knowledge — nothing is written.
+If the built-in tools error (offline), continue on the user layer alone.
+
+## Privacy guard
+
+Only write audio knowledge — plugins and mixing. Never secrets, license keys,
+names of the user's clients/songs, or paths containing personal data. A candidate
+record that contains one is **dropped, not written**.
+
+---
+
+## The self-improvement loop (every skill)
+
+This loop is **general to all the mix skills** — `/mixer`, `/mastering`,
+`/critique`, `/learn-plugin`. The **only** thing that breaks it is failing to
+capture — so capture is **mandatory and reported**, never deferred to "later".
+
+1. **Recall (start of every task)** — the read step below. A skill that changes
+   nothing (`/critique`) still recalls; lessons sharpen what it looks for.
+2. **Capture at the correction point — immediately, before your next action.**
+   The moment the user reverts / rejects / overrides you, or a re-measure shows
+   you made it worse, write the lesson; then **say you did** (key + one-line
+   takeaway). *No capture at all is the dominant failure of this loop — treat a
+   silent skip as a bug.*
+3. **End-of-session retrospective — always, even on a clean run.** Before the
+   final report, ask: did the user correct or override me; did a measurement
+   surprise me; did I guess at something that nearly didn't pay off; should a
+   lesson I already had have fired earlier? Did a lesson I applied work? Write or
+   UPDATE a lesson for anything that surfaces. Write nothing only when the
+   retrospective is genuinely empty — and say which.
+4. **Report what you captured.** The final message names the record(s) written
+   (or states that none were), so a skipped capture is visible to the user.
+
+"Read-only" skills (`/critique`) still write **process lessons about their own
+analysis**. Read-only means they don't change the *mix*, not that they don't learn.
+
+---
+
+## Read step (start of every task)
+
+Lessons are capped — at most 5 per layer per read, so memory never crowds out the session.
+
+```text
+# built-in
+list_builtin_knowledge { kind: "lessons", query: "<task / area keywords>", limit: 5 }
+# yours
+memory.list   { scope: "project::reaper-mcp", tags: ["loop::mixing-lessons"], order: "rank", limit: 5 }
+# when the task names an area (drum bus, vocals, limiting, track numbering…), one targeted search:
+memory.search { q: "<area keywords>", scopes: ["project::reaper-mcp"], tags: ["loop::mixing-lessons", "layer::user"], limit: 5 }
+```
+
+Match each lesson's **Applies when** line against the task and apply the matching
+**Do this instead** lines as **soft constraints** — they bias the run unless they
+conflict with the user's stated intent (the user wins; say so). When a built-in
+lesson and a `user::` lesson with the same slug both match, the user's wins.
+
+### Plugin lookup
+
+**Pick a plugin for a job** (which EQ / compressor / limiter to use):
+
+```text
+list_available_fx                                              # what is installed
+list_builtin_knowledge { kind: "plugins", tags: ["category::<category>"], limit: 100 }        # built-in
+memory.list { scope: "project::reaper-mcp", tags: ["category::<category>"], view: "summary", limit: 100 }   # yours
+```
+
+A record matches an installed FX when any of its `fx::<pattern>` tags is a
+case-insensitive substring of the installed name. Group the results by
+`plugin::<vendor>/<plugin>`; when a plugin has both layers, the **user record's
+tags win** (its `preference::` overrides the built-in one). The highest
+`preference` wins; when the user asks for a character (`transparent`,
+`vintage`, …) prefer a matching `style::` tag. Nothing matches → fall back to the
+stock REAPER plugin for that category.
+
+**Before touching a plugin** (adding it, setting a parameter, interpreting one on
+the chain), read both layers:
+
+```text
+get_builtin_knowledge { key: "plugins::<vendor>/<plugin>" }                             # built-in (may be null)
+memory.read { scope: "project::reaper-mcp", key: "user::plugins::<vendor>/<plugin>" }   # yours (may be absent)
+```
+
+No key at hand (you only have the FX name from a track)? Find it via the `fx::`
+tags of `list_builtin_knowledge { kind: "plugins", limit: 100 }` and
+`memory.list { scope: "project::reaper-mcp", tags: ["plugin-knowledge"], view: "summary", limit: 100 }`.
+Neither layer has it → bootstrap it (below) before using the plugin.
+
+**Combining the two:** the user record is an overlay. A section it contains
+replaces the built-in section of the same heading; `## Learned notes` from both
+apply (user notes first, and they win on a conflict); everything else comes from
+the built-in record.
+
+---
+
+## Plugin knowledge
+
+### The record
+
+One record per plugin per layer, pure markdown (no frontmatter, no HTML comments,
+no dates or counts — the store and tags carry those). The header line repeats the
+tag facts for human readers; the tags are what lookups filter on, so keep the two
+in step.
+
+```markdown
+# <Plugin name>
+
+**Category:** <category> · **Style:** <style> · **Vendor:** <Vendor> · **Preference:** <n>/100  
+**Matches FX:** `<exact REAPER FX name>`, `<alternate>`  
+**Replaces:** `<stock id>`
+
+## What it does
+
+<one paragraph — purpose, sonic character, primary use cases>
+
+## Key parameters by name
+
+| Parameter | Range | Description |
+|-----------|-------|-------------|
+
+## Recommended settings
+
+### <Use case>
+
+| Parameter | Value | Why |
+|-----------|-------|-----|
+
+## Presets worth knowing
+
+## When to prefer this
+
+## Learned notes
+
+**Param indices (<VST3|VST|AU|JS>, N params):** 0 Name · 1 Name · …
+
+**Normalized (0–1) scaling, verified by probing:**
+
+- <Param>: <mapping> (<probe → readback>)
+
+**Gotchas:** <…>
+
+**Kept settings (with context):**
+
+- <Context — genre, source, goal>: <setting the user kept and why it worked>
+```
+
+A **user overlay** for a plugin that already has a built-in record needs only the
+header (so its tags can be set) and the sections it adds or overrides — usually
+just `## Learned notes`. A plugin the built-in layer doesn't know gets a full record.
+
+Field guide:
+- **category** — `eq`, `compressor`, `limiter`, `saturator`, `reverb`, `delay`,
+  `gate`, `de-esser`, `amp-sim`, `channel-strip`, `analyzer`, `stereo-imager`,
+  `multiband`, `pitch-correction`.
+- **style** — `transparent`, `character`, `vintage`, `modern`, `surgical`.
+- **preference** — 30–50 stock/fallback, 55–70 good third-party, 70–85 go-to,
+  85–95 industry standard. Decides which plugin wins in a category.
+- **fx patterns** — the exact strings REAPER shows (`VST3: Pro-Q 3 (FabFilter)`)
+  plus a short form (`Pro-Q 3`); add VST and VST3 variants. Matching is a
+  case-insensitive substring.
+- **replaces** — stock plugin slugs this supersedes (`rea-eq`, `rea-comp`).
+- **extension** — tag `extension::<name>` when an opt-in extension (`docs/EXTENSIONS.md`) drives the
+  plugin's internals, e.g. `extension::vital`. The note in `## Learned notes` says which tools to use; a skill
+  uses them only when `list_tool_categories` shows that extension's category.
+
+Write (user layer — the only layer a skill writes):
+
+```text
+memory.write {
+  scope:   "project::reaper-mcp",
+  key:     "user::plugins::<vendor>/<plugin>",
+  value:   "<the markdown record or overlay>",
+  tags:    ["plugin-knowledge", "layer::user", "plugin::<vendor>/<plugin>", "category::<cat>",
+            "vendor::<vendor>", "preference::<n>", "style::<style>", "fx::<pattern>", …, "replaces::<id>", …],
+  kind:    "signal",
+  host:    "mixing",
+  trigger: "<manual | gotcha | paid-off>",
+  source_agent: "<mixer | mastering | critique | learn-plugin>"
+}
+```
+
+No `ttl_days` — plugin knowledge does not expire. An overlay copies the built-in
+record's tags (changing only what the user overrides) so lookups by category and
+FX name still find it. A write **replaces** the whole record (value *and* tags), so
+always read-merge-write the `user::` key.
+
+### Bootstrapping an unknown plugin
+Asked to use a plugin neither layer knows, create a user record *before* mixing
+with it. Dispatch the **`plugin-researcher`** agent with the plugin name (and
+what you need it for) and wait for its one-paragraph report. That keeps the web
+pages and parameter dumps out of your context. Its steps, which you follow
+inline when the agent isn't available:
+
+1. **Research the web** (`WebSearch` / `WebFetch`): what it is, its category and
+   character, key parameters, typical settings. Prefer the manufacturer's manual.
+2. **Test it on a scratch track** (`[MCP] plugin-research`, never the user's
+   tracks): `get_fx_parameters` for the **real parameter names and indices** of
+   this build (ground truth). Probe the key params at 0/0.25/0.5/0.75/1 and read
+   the formatted values back to get their scaling. Then delete the scratch track.
+3. **Write the record** above: research in the main sections, the verified param
+   map and scaling under `## Learned notes`. The preference is a proposal from
+   the field guide.
+4. **Then use it**, and keep refining it as you go. Mention the proposed
+   preference to the user once; don't block the mix on it.
+
+`/learn-plugin` runs the same agent, then asks the user only what it couldn't
+work out.
+
+### Update — on a durable, reusable learning
+Fold into the `user::` record's `## Learned notes` (creating the overlay if the
+plugin only has a built-in record) when you discover something worth knowing next
+time:
+- a **param-index map / normalized scaling** verified via `get_fx_parameters`
+- a **setting the user kept or approved** (not one you tried and reverted)
+- a **gotcha** (non-linear param, VST2/VST3 index differs, a mode that breaks something)
+
+No learning → no write. Refine notes in place, don't duplicate; if a new
+observation contradicts an old one (or the built-in notes), keep both with their
+differing context. Context is mandatory on kept settings — a setting that works on
+a bright pop vocal can be wrong on a dark rock one.
+
+---
+
+## Process memory (mixing lessons)
+
+Procedural "do better next time" lessons about **your own process** — not facts
+about the user's mix. Advisory input, never an automatic action.
+
+### Write — at a correction point (immediately) or in the retrospective
+Triggers:
+- the user **reverted** a snapshot you made, said "no, that's wrong", or
+  **overrode** a target/decision you proposed
+- a **re-measure** (meters/LUFS/correlation/crest) showed your change made it worse
+- you hit a **recurring trap** (over-compressed, widened before checking mono, clipped the bus)
+- the **retrospective** surfaced friction, or a lesson you applied paid off
+
+1. **Deduplicate** — a recurrence must UPDATE, not add:
+
+   ```text
+   memory.search { q: "<key words of the lesson>", scopes: ["project::reaper-mcp"], tags: ["loop::mixing-lessons"], limit: 10 }
+   ```
+
+   Also run `list_builtin_knowledge { kind: "lessons", query: "<same words>" }`.
+   A match on a `user::mixing-lessons::<slug>` → rewrite that key. A match on a
+   **built-in** `mixing-lessons::<slug>` → write `user::mixing-lessons::<slug>`
+   (same slug, so the two read as one lesson; it carries your recurrence count).
+
+2. **Write** — to the user layer only:
+
+   ```text
+   memory.write {
+     scope:    "project::reaper-mcp",
+     key:      "user::mixing-lessons::<kebab-slug>",
+     value:    "<markdown body — shape below>",
+     tags:     ["loop::mixing-lessons", "layer::user", "source::<trigger>", "topic::<area>"],   # + "status::structural" for a design gap
+     trigger:  "<assumption-wrong | gotcha | near-miss | stuck-loop | paid-off>",
+     ttl_days: 90,
+     source_agent: "<mixer | mastering | critique | learn-plugin>",
+     cited:    ["project::reaper-mcp::mixing-lessons::<slug>", …]   # lessons that actually shaped this run
+   }
+   ```
+
+   Same scope + key overwrites in place: **the store increments `seen_count`**
+   and re-passing `ttl_days` refreshes the expiry. Never write a count, date or
+   status into the body. A lesson you applied that *worked* is still worth an
+   UPDATE — successful application is recurrence evidence.
+
+Body shape — one lesson per record, ~1,500 characters max:
+
+```markdown
+# <one-line takeaway — what to do, not what it is about>
+
+**Applies when:** <concrete signal — task, bus/track type, tool name, measurement>
+
+**What happened:** <the concrete observable>
+**Why:** <root cause, or "unknown">
+**Do this instead:** <prescriptive, testable instruction>
+**Promotion target:** <skill → Hard Rules, or "none">
+```
+
+No run residue (no song names, session narrative or timestamps) — a lesson is
+written for the *next* session, which has none of that context.
+
+### Self-heal (the slow tier)
+When a `user::` lesson has **`seen_count >= 3`** (the store's column) or carries
+`status::structural`, surface it — never act silently:
+
+> "I've hit *'read crest before bus comp'* 3× now. Promote it to a permanent rule
+> in the mixer skill?"
+
+On approval, add a one-line hard rule to the owning skill's `## Hard Rules`
+(`.claude/skills/{mixer|mastering|critique}/SKILL.md`), then UPDATE the lesson
+adding the `status::promoted` tag (keep it as the audit trail of why the rule
+exists; it stops re-suggesting). A lesson worth sharing with every user can also be
+published to the built-in layer (below) — suggest it, never do it unasked.
+
+### Entrenchment guards (non-negotiable)
+1. Lessons are **advisory**; the only path to a behavior guarantee is the
+   confirmed promotion edit above.
+2. **Recurrence** (`seen_count >= 3`), not one bad run, gates promotion.
+3. User lessons **expire** (`ttl_days: 90`, refreshed on recurrence) — the store
+   drops stale ones. Built-in lessons and plugin records are curated, so they do
+   not expire.
+4. **Contradictions are flagged, not overwritten** — the dedup search finds the
+   prior lesson; a genuine reversal is the user's call.
+5. A lesson must **never** relax an existing hard rule (e.g. "always snapshot
+   before changes"). Those are invariants.
+6. **Lesson reads are capped** (5 per query) so memory never crowds out the session.
+
+---
+
+## Publishing to the built-in layer (maintainer only)
+
+`/mix-memory publish <key>` turns a proven `user::` record into a built-in one. It
+needs write access to the `reaper-mcp` org (member/admin/owner) — for everyone
+else the write lands in their personal store, so check `org.list` first and stop
+if the role is `viewer` or the org is absent.
+
+1. Read the `user::` record and, if one exists, the built-in record of the same
+   name; merge them (for a plugin: the overlay's sections over the built-in ones,
+   notes folded together) and show the result for approval.
+2. Write it with `org: "reaper-mcp"`, the key **without** `user::`, tag
+   `layer::built-in` instead of `layer::user`, and **no** `ttl_days`.
+3. `memory.delete` the `user::` key (safe — never delete the built-in key).
+
+## Consolidation
+
+Run via `/mix-memory consolidate` when the user's notes sprawl or lessons overlap.
+It only ever touches `user::` records:
+- **Plugin overlays** → fold proven, repeated kept settings from `## Learned notes`
+  into the overlay's own `## Recommended settings`; keep param maps and gotchas.
+- **Lessons** → merge near-duplicate `user::` lessons into the older key (rewrite
+  its body, then `memory.delete` the duplicate). Expiry is automatic.

package/{knowledge → claude/knowledge}/reference/metering.md

@@ -161,14 +161,14 @@ For a healthy mix signal chain:
 
 | 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 |
+| Bass and vocal at same RMS | "Equal volume" | Not equal: RMS ignores how the ear weights frequency | Compare short-term LUFS (LU), never RMS; see `perceived-loudness.md` |
+| Hi-hat and kick at same peak | "Equal transients" | Hi-hat is much louder | Compare in LU and in `kDb` bands; expect the hats lower |
 | "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 matches target | "Correct loudness" | Correct overall, not per element | Per-element balance: LU of each element against the mix bus, same section, post-fader |
 
 ### 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.
+LUFS measurements already incorporate psychoacoustic weighting via K-weighting (a +4 dB shelf above ~1.5 kHz and a high-pass that rolls off the deep lows). This makes LUFS the measure for **every** level comparison, per track as well as for the whole mix. Read each element's short-term LUFS over the same section as the mix bus and compare in LU. For per-band decisions, use the K-weighted `kDb` band values. `perceived-loudness.md` has the per-band K gains and the stem reference points.
 
 ## Common Metering Mistakes
 
@@ -181,5 +181,5 @@ LUFS measurements already incorporate some psychoacoustic compensation via K-wei
 | 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 |
+| Balancing tracks on dBFS / RMS readings | Gain-stage on dBFS (headroom); balance on LU against the mix bus (`perceived-loudness.md`) |
 | 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/claude/knowledge/reference/perceived-loudness.md

@@ -0,0 +1,182 @@
+# Perceived Loudness Reference
+
+Human hearing does not perceive all frequencies equally. A bass note and a vocal at the same dB SPL sound like very different volumes. Every balance and EQ decision is made on **perceived** loudness, the level the listener hears, and never on raw meter values.
+
+## The Rule: Perceived Values Only, Never Raw
+
+| Decision | Measure with | Never with |
+|----------|--------------|------------|
+| Level of one track/bus against another (balance) | **Short-term LUFS** (`read_track_lufs`, `measure_tracks` with `lufs`), as **LU relative to the mix bus**, all read over the same section | Peak dBFS, RMS dBFS, fader positions on their own |
+| Tonal balance, masking, "which band is too much" | **`kDb`** of `read_track_spectrum` / `measure_tracks` bands (K-weighted) | The band's raw `db`, raw FFT bins |
+| Mix loudness against a target | Integrated LUFS over the whole song (`reference/metering.md`) | RMS |
+| Headroom and clipping only | Peak / true-peak dBFS, `read_track_meters` | (allowed here: this is not a balance decision) |
+| Dynamics only | Crest factor (peak minus RMS) | (allowed here) |
+
+Why: a raw value counts every frequency equally, but the ear does not. Equal RMS on a bass and a vocal does not mean equal loudness, and raw band levels understate 2–5 kHz by ~4 dB against the low mids and overstate the deep lows by 4–10 dB (see the K-weighting table). Even a perceptual number can mislead when it is read wrong: in Emptiness (2026-10-29) a raw band table made the bass look fine while it sounded far too loud. The real cause was a changed EQ band, which only the ear and a parameter diff revealed.
+
+Rules that follow from it:
+
+1. **Same section, same window.** Compare LU only between readings taken over the same passage, ideally in one `measure_tracks` call. A chorus reading against a verse reading compares the arrangement, not the balance. Measure where every compared element is playing (check the regions first).
+2. **Track meters are pre-fader.** The LUFS and spectrum meters sit in the track's FX chain, before the fader. A track's level in the mix is its reading **plus its fader (dB)**. A bus, which sums its children after their faders, reads them post-fader. Seen live: VOX at +5 dB read -10.4 LU against MIX A, so it really sat at -5.4 LU.
+3. **A spectrum read is a ~0.5 s snapshot.** One band moves several dB with the note being played. Read 3 or more times across the section and judge the pattern, not one value.
+4. **The ear wins.** When the user reports a balance by ear, that is the finding. Measurements size the fix and check it worked; they never overrule the report. If a measurement and the ear disagree, suspect the measurement first (a changed plugin parameter, a bypassed meter, a pre-fader reading, a different section).
+
+## Reference Points
+
+### K-weighting per 1/3-octave band
+
+K-weighting is the ITU-R BS.1770 filter behind every LUFS reading: a high-pass that rolls off the deep lows plus a +4 dB shelf above ~1.5 kHz. The spectrum tools add these gains to each band's raw `db` to get `kDb` (`K_WEIGHT_DB` in `apps/reaper-mcp-server/src/tools/spectrum.ts`; keep both tables equal). Values are the filter's gain at the band centre, computed from the standard's 48 kHz coefficients.
+
+| Band (Hz) | 25 | 31.5 | 40 | 50 | 63 | 80 | 100 | 125 | 160 | 200 | 250 | 315 | 400 | 500 | 630 |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| **K gain (dB)** | -10.4 | -7.8 | -5.6 | -3.9 | -2.7 | -1.7 | -1.1 | -0.7 | -0.4 | -0.3 | -0.2 | -0.1 | 0 | 0 | +0.1 |
+
+| Band (Hz) | 800 | 1k | 1.25k | 1.6k | 2k | 2.5k | 3.15k | 4k | 5k | 6.3k | 8k | 10k | 12.5k | 16k |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| **K gain (dB)** | +0.3 | +0.7 | +1.3 | +2.3 | +3.1 | +3.6 | +3.8 | +4.0 | +4.0 | +4.0 | +4.0 | +4.0 | +4.0 | +4.0 |
+
+So a 4 kHz band and a 100 Hz band with the same raw `db` differ by **5.1 dB** in `kDb`, and a 40 Hz band by **9.6 dB**.
+
+K-weighting is a deliberately gentle model: it is nearly flat from 100 Hz to 1 kHz, while the ear at moderate levels is less sensitive at 100 Hz than that (see the equal-loudness section below). Two consequences:
+
+- At the **same LU**, a bass-dominant source can still sound a little quieter than a mid-range one. Don't add a fixed correction for this. Place the element with the stem reference points below, then confirm by ear.
+- At **low monitoring levels** the gap grows (bass drops out first). Make balance decisions at a moderate level (~75–85 dB SPL).
+
+### Stem balance (dense rock / metal)
+
+Starting points for short-term LUFS of each element (post-fader), in **LU below the mix bus**, read together over the densest section (chorus). They are working heuristics from mixing practice and the measured sessions below, not a published standard. They place an element; they are not a pass/fail target. Confirm by ear, and when the user settles a balance, record it as a `user::mixing-lessons::` lesson so the next mix starts from their taste.
+
+| Element | LU below mix bus | Notes |
+|---------|-----------------|-------|
+| Lead vocal | -2 to -5 | The lead element sits closest to the mix level. In metal the vocal and the guitar bus are often within ~1–2 LU of each other |
+| Rhythm guitars (bus) | -3 to -7 | Guitars ~2 LU or more above the vocal is the usual cause of "vocal too quiet, guitars too loud" |
+| Drums (bus) | -5 to -9 | Snare and kick attack carry it. If the drums read under -10 LU, check the snare before the bus fader |
+| Bass | -7 to -11 | Usually the lowest in LU yet still audible. A bass within ~3 LU of the guitars will sound heavy. Above -6 LU: check the low end before anything else |
+
+Other genres: pop and hip-hop keep the lead vocal closest (-1 to -3 LU); in hip-hop and EDM the bass/808 can come up to the drums. Put a genre's own numbers in its `genres/{genre}.md` when they become known.
+
+Measured data points (Emptiness, metal, 2026-10-29), LU below the MIX A bus, post-fader:
+
+| Stage | Guitars | Vocal | Drums | Bass |
+|-------|---------|-------|-------|------|
+| Whole song, offline stem renders (ungated), before any change | -3.4 | -5.4 | -9.0 | -9.0 |
+| Chorus 2 (208–222 s, live), after VOX +5 / GUITAR -1.5 | -3.6 | -5.4 | -8.6 | -8.7 |
+
+By ear, the user first found the vocal too quiet and the guitars a bit loud, which matches the table: the guitars read above the vocal. After the +5 the vocal is still ~2 LU under the guitars in the chorus, because the guitars own 2–4 kHz (see masking below).
+
+### Spectral checks on `kDb`
+
+- **Compare a band only with the same band.** Compare one track's band with the same band on another track, or on a reference. Never compare one band with a different band in the same spectrum. K-weighting gives a correct broadband loudness, but it is not an equal-loudness curve per band. Also, 1/3-octave bands get wider towards the top, so a raw or K-weighted music spectrum often peaks at 60–125 Hz even in a well-balanced rock or metal mix. "The loudest band is the low end" is not, by itself, a finding.
+- **Comparing to a reference.** Measure a reference track the same way: same section type, same `fftSize`, `kDb`, and both level-matched to the same short-term LUFS first. A difference of more than ~3 dB across 3 or more adjacent bands is a real tonal difference. One band alone is usually arrangement noise.
+- **Masking between two tracks.** Compare their `kDb` in the contested band (kick/bass 60–125 Hz, bass/guitars 125–250 Hz, guitars/vocal 1–4 kHz), each with its fader added. The track that is more than ~3 dB higher there owns the band. To let the other one through, cut the owner there, or boost the other. Live example (Emptiness, chorus 2): the guitars read -41 to -45 `kDb` across 2–4 kHz, against the vocal's -57 to -64 (both with their faders added). The guitars own the vocal's presence range, so more vocal fader alone won't unbury it. Carve the guitars at 2–4 kHz (ideally a dynamic EQ keyed from the vocal) before raising the vocal further.
+- **Analyzer slope.** A balanced mix's raw `db` bands slope downward from lows to highs. In `kDb` the slope is flatter, because the +4 dB shelf lifts the top. Never "flatten" either curve by EQ.
+
+## 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 or judging track balance:
+
+1. **Read short-term LUFS for every element and the mix bus over the same section** (one `measure_tracks` call), and express each element as LU below the mix bus.
+2. **Place each element against the stem reference points above**, starting with the lead element (usually the vocal), then guitars, drums, bass.
+3. **Never match RMS or peak levels across tracks**, and never infer balance from fader positions. Raw levels make low-frequency instruments look louder than they sound and presence-range instruments look quieter.
+4. **Move the fader by the LU difference you want.** 1 dB of fader is 1 LU for that element. Re-measure, then listen.
+5. **Verify by ear.** The numbers place the element; the listener decides.
+
+### Gain Staging Is Not Balance
+
+Gain staging (`workflows/gain-staging.md`) sets each track's raw level (around -18 dBFS RMS, peaks below -6 dBFS) so plugins see a sensible input and the bus keeps headroom. This is the one place raw dBFS is the right measure, because it is about electrical headroom, not loudness. Don't use different raw targets per instrument to "pre-balance" the mix. Balance is a separate step, done afterwards in LU.
+
+### 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 / too loud | Compare the bass RMS or raw bands with the other tracks | Read short-term LU of the bass vs the mix bus; place it against the stem reference points; check the low-end `kDb` |
+| Vocals feel buried | Boost the vocal fader until it's the loudest meter | Compare the vocal LU with the guitars (guitars above the vocal = buried); check 1–4 kHz `kDb` masking from guitars/keys; a small presence move goes far |
+| Cymbals are harsh | "They're not even that loud on meters!" | Read their 6–12 kHz `kDb`. The raw reading understates them by ~4 dB. Pull the fader or EQ there |
+| Mix sounds thin | Boost everything below 200 Hz | Check bass and kick LU against the reference points, and the monitoring level (low volume exaggerates thinness) |
+| Mix sounds muddy | Cut all low-mids on every track | Find which tracks lead the 200–500 Hz `kDb`; cut those. The ear needs bigger cuts here to notice |
+| A change "measures fine" but the user says it sounds wrong | Defend the measurement | The ear wins. Diff plugin parameters against the before-snapshot and re-check the measurement setup |

package/{knowledge → claude/knowledge}/workflows/editing.md

@@ -230,6 +230,10 @@ params:
   description: "Audio editing complete — crossfades, timing, phase, cleanup done"
 ```
 
+### A/B-testing MIDI or arrangement variants
+
+Comparing two versions of a part (a drum groove, a chorus) is done in fixed lanes, one complete version per lane. The procedure and its gotchas are in the `/editing` skill (`.claude/skills/editing/SKILL.md`), not here.
+
 ## Verification
 
 After completing audio editing: