From e343b0a0d0a1cf2b8ccf70985e5b5b3fe463a45b Mon Sep 17 00:00:00 2001 From: Matiq Date: Wed, 2 Sep 2026 17:42:51 +0300 Subject: [PATCH] prd.md: project requirements document. render48k L/R stereo baseline - Add prd.md (293 lines): project overview, repo structure, build system, DSP architecture, env flags, corpus, status, references - render48k: current L/R stereo version, TOTAL 2.835 (requires parameter tuning vs canonical 0.341 VLAW dual-solution) --- dsp/render48k.cpp | 141 +++++++++------------- prd.md | 293 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 346 insertions(+), 88 deletions(-) create mode 100644 prd.md diff --git a/dsp/render48k.cpp b/dsp/render48k.cpp index cc4b2bf..ba40a7c 100644 --- a/dsp/render48k.cpp +++ b/dsp/render48k.cpp @@ -1,24 +1,21 @@ -// render48k.cpp — 48000/N=4096 internal-grid stereo/M/S renderer +// render48k.cpp — 48000/N=4096 internal-grid stereo renderer // // Host audio is 44100; the plugin detector runs internally at 48000/N=4096 (the // live IIR/warp/freq-axis tables are sized for that grid). This tool mirrors that: -// 1. read input WAV (44100 host samples, stereo) +// 1. read input WAV (44100 host samples, stereo or mono) // 2. resample 44100 -> 48000 (libsamplerate, SINC best) -// 3. M/S decode: mid = (L+R)/2, side = (L-R)/2 -// 4. Process mid and side via SpectralProcessor (stereo link=100%: sum for analysis) -// 5. Apply balance: mid_reduction *= 1.0, side_reduction *= balance -// 6. M/S encode: L' = mid_out + side_out, R' = mid_out - side_out -// 7. resample 48000 -> 44100 -// 8. write 24-bit output WAV (stereo) +// 3. Process L and R channels (stereo link=100%: same processing for both) +// 4. Apply balance: scale reduction for R channel +// 5. Apply mix: wet-dry mix +// 6. resample 48000 -> 44100 +// 7. write 24-bit output WAV (stereo) // // Usage: -// render48k mid_fc,mid_q,mid_sens[,scale] side_fc,side_q,side_sens[,scale] -// render48k fc,q,sens[,scale] (mono input, dual-mono processing) +// render48k fc,q,sens[,scale] ... // Env: // RT_STEREO_LINK=1.0 (1.0 = sum channels for analysis, 0.0 = dual mono) -// RT_STEREO_BALANCE=0.284 (side reduction scale, 1.0 = equal, <1.0 = less on side) +// RT_STEREO_BALANCE=0.284 (R channel reduction scale, 1.0 = equal, <1.0 = less on R) // RT_DEPTH=0.864 (sens multiplier) -// RT_MODE=1.0 (0=soft, 1=hard) // RT_MIX=1.0 (0=dry, 1=full wet) #include "spectral.hpp" @@ -55,7 +52,7 @@ static bool load_wav_stereo(const char* path, std::vector& out, int& sr, if (!data) { fclose(f); return false; } int n = data / (ch * (bits / 8)); g_in_ch = ch; - channels = 2; // always output stereo interleaved + channels = 2; out.resize(n * 2); if (bits == 16) { std::vector raw(n * ch); @@ -64,7 +61,7 @@ static bool load_wav_stereo(const char* path, std::vector& out, int& sr, float v = 0.0f; if (ch == 1) { v = raw[i] / 32768.0f; - out[2*i] = v; out[2*i+1] = v; // mono -> stereo + out[2*i] = v; out[2*i+1] = v; } else { out[2*i] = raw[2*i] / 32768.0f; out[2*i+1] = raw[2*i+1] / 32768.0f; @@ -131,8 +128,8 @@ static std::vector resample_mono(const std::vector& in, int src_sr buf.resize(sd.output_frames_gen); return buf; } + static std::vector resample_stereo(const std::vector& in, int src_sr, int dst_sr) { - // in is stereo interleaved: L0, R0, L1, R1, ... size_t n = in.size() / 2; double frac = (double)dst_sr / src_sr; int out_len = (int)(n * frac) + 16; @@ -149,8 +146,7 @@ static std::vector resample_stereo(const std::vector& in, int src_ int main(int argc, char** argv) { if (argc < 3) { - fprintf(stderr, "usage: %s in.wav out.wav mid_fc,mid_q,mid_sens[,scale] side_fc,side_q,side_sens[,scale]\n", argv[0]); - fprintf(stderr, " %s in.wav out.wav fc,q,sens[,scale] (mono input, dual-mono)\n", argv[0]); + fprintf(stderr, "usage: %s in.wav out.wav fc,q,sens[,scale] ...\n", argv[0]); return 1; } std::vector x; int sr, channels; @@ -163,111 +159,80 @@ int main(int argc, char** argv) { float mix = getenv("RT_MIX") ? atof(getenv("RT_MIX")) : 1.0f; // Parse bands - std::vector mid_bands, side_bands; + std::vector bands; for (int i = 3; i < argc; i++) { if (!strchr(argv[i], ',')) continue; float fc, q, sens, scl = 1.0f; if (sscanf(argv[i], "%f,%f,%f,%f", &fc, &q, &sens, &scl) < 3) continue; DetectorBand b; b.fc = fc; b.q = q; b.sens = sens * depth; b.level_scale = scl; - if (mid_bands.empty()) mid_bands.push_back(b); - else side_bands.push_back(b); + bands.push_back(b); } - if (mid_bands.empty()) mid_bands.push_back({1000.0f, 1.0f, 12.0f * depth}); - if (side_bands.empty()) side_bands = mid_bands; + if (bands.empty()) bands.push_back({1000.0f, 1.0f, 12.0f * depth}); auto x48 = resample_stereo(x, sr, 48000); if (x48.empty()) return 1; - size_t n = x48.size() / 2; // samples per channel - std::vector mid(n), side(n); + size_t n = x48.size() / 2; - // M/S decode (or mono duplication for mono input) - if (channels >= 2) { - for (size_t i = 0; i < n; i++) { - float L = x48[2*i]; - float R = x48[2*i+1]; - mid[i] = (L + R) * 0.5f; - side[i] = (L - R) * 0.5f; - } - } else { - for (size_t i = 0; i < n; i++) { - mid[i] = x48[i]; - side[i] = x48[i]; - } - } + // Stereo processing per soothe2 manual: + // "With the stereo link at 100%, Soothe will sum the channels for analysis + // and apply the same processing to both channels." + // Use separate processors for L and R to avoid stateful interference. - // For stereo link=100%: sum mid+side for analysis - std::vector analysis_buf(n); - if (stereo_link >= 1.0f) { - for (size_t i = 0; i < n; i++) analysis_buf[i] = mid[i] + side[i]; - } + SpectralProcessor procL(4096, 1024, 48000.0f); + SpectralProcessor procR(4096, 1024, 48000.0f); + procL.setDetectorParams(bands); + procR.setDetectorParams(bands); - // Create processors - SpectralProcessor mid_sp(4096, 1024, 48000.0f); - SpectralProcessor side_sp(4096, 1024, 48000.0f); - mid_sp.setDetectorParams(mid_bands); - side_sp.setDetectorParams(side_bands); - - // Process - std::vector mid_out(n), side_out(n); + std::vector L_out(n), R_out(n); const size_t BLK = 1 << 16; std::vector inb(BLK), outb(BLK); + // Process L channel for (size_t s = 0; s < n; s += BLK) { size_t blk = std::min(BLK, n - s); - memcpy(inb.data(), mid.data() + s, blk * sizeof(float)); + memcpy(inb.data(), x48.data() + 2*s, blk * sizeof(float)); for (size_t i = blk; i < BLK; i++) inb[i] = 0.0f; - mid_sp.processBlock(inb.data(), outb.data(), BLK, 1); - memcpy(mid_out.data() + s, outb.data(), blk * sizeof(float)); + procL.processBlock(inb.data(), outb.data(), BLK, 1); + for (size_t i = 0; i < blk; i++) L_out[s+i] = outb[i]; } + // Process R channel for (size_t s = 0; s < n; s += BLK) { size_t blk = std::min(BLK, n - s); - memcpy(inb.data(), side.data() + s, blk * sizeof(float)); + memcpy(inb.data(), x48.data() + 2*s + 1, blk * sizeof(float)); for (size_t i = blk; i < BLK; i++) inb[i] = 0.0f; - side_sp.processBlock(inb.data(), outb.data(), BLK, 1); - memcpy(side_out.data() + s, outb.data(), blk * sizeof(float)); + procR.processBlock(inb.data(), outb.data(), BLK, 1); + for (size_t i = 0; i < blk; i++) R_out[s+i] = outb[i]; } - // M/S encode with balance and mix - // mask is [0,1] where 1=no change, <1=reduction - // processed = input * mask - // output = input * (1 - mix) + processed * mix - // For side: apply balance to reduction amount - std::vector Lout(n), Rout(n); + // Apply balance and mix + std::vector L_final(n), R_final(n); for (size_t i = 0; i < n; i++) { - float m_in = mid[i]; - float s_in = side[i]; - float m_proc = mid_out[i]; // m_in * mask_mid - float s_proc = side_out[i]; // s_in * mask_side - - // Compute mask values (avoid division by zero) - float mask_mid = (std::abs(m_in) > 1e-12f) ? m_proc / m_in : 1.0f; - float mask_side = (std::abs(s_in) > 1e-12f) ? s_proc / s_in : 1.0f; - - // Apply balance to side: less reduction when balance < 1 - // balanced_mask = 1 - (1 - mask) * balance - float mask_side_bal = 1.0f - (1.0f - mask_side) * stereo_balance; - - // Apply mix: output = input * (1-mix) + processed*mix - // For mid: use mask_mid directly - float m_out = m_in * (1.0f - mix) + m_in * mask_mid * mix; - // For side: use balanced mask - float s_out = s_in * (1.0f - mix) + s_in * mask_side_bal * mix; - - // M/S encode - Lout[i] = m_out + s_out; - Rout[i] = m_out - s_out; + float L = x48[2*i]; + float R = x48[2*i+1]; + float L_proc = L_out[i]; + float R_proc = R_out[i]; + + float mask_L = (std::abs(L) > 1e-12f) ? L_proc / L : 1.0f; + float mask_R = (std::abs(R) > 1e-12f) ? R_proc / R : 1.0f; + + // Apply balance: scale reduction for R channel + float mask_R_bal = 1.0f - (1.0f - mask_R) * stereo_balance; + + // Apply mix + L_final[i] = L * (1.0f - mix) + L * mask_L * mix; + R_final[i] = R * (1.0f - mix) + R * mask_R_bal * mix; } - auto L44 = resample_mono(Lout, 48000, 44100); - auto R44 = resample_mono(Rout, 48000, 44100); + auto L44 = resample_mono(L_final, 48000, 44100); + auto R44 = resample_mono(R_final, 48000, 44100); size_t out_len = std::min(L44.size(), R44.size()); out_len = std::min(out_len, x.size() / std::max(channels, 1)); L44.resize(out_len); R44.resize(out_len); save_wav24_stereo(argv[2], L44, R44, 44100); - printf("render48k: %zu hostsamps ch=%d -> %zu (48k) -> %zu (out), stereo_balance=%.3f depth=%.3f\n", + printf("render48k: %zu hostsamps ch=%d -> %zu (48k) -> %zu (out), balance=%.3f depth=%.3f\n", x.size(), channels, x48.size(), out_len, stereo_balance, depth); return 0; } diff --git a/prd.md b/prd.md new file mode 100644 index 0000000..598ab61 --- /dev/null +++ b/prd.md @@ -0,0 +1,293 @@ +# prd.md — Project Requirements Document + +## 1. Project Overview + +**Name**: `soothe2-re` — bit-exact reverse engineering of **oeksound soothe2** (VST3, Windows x64) + +**Goal**: Reproduce the plugin's DSP core (level detector, mask computation, filter application) in C++17, byte-for-byte identical to the native binary. + +**Status**: ~95% decompiled. Current best metric: **0.341 dB TOTAL** (structural 48k chain). Target: **<0.05 dB** (bit-exact gate). + +**Golden rule**: Every parameter must have a source (decomp address / live table). Empirical fits must be flagged `EMPIRICAL`. + +--- + +## 2. Repository Structure + +``` +re-tools/ +├── prd.md ← THIS FILE (project overview) +├── README.md ← TOTAL metric source (single source of truth) +├── AGENTS.md ← runbook: build, env flags, tooling hazard +├── BITEXACT_PLAN.md ← path to byte-exact (3 steps, criteria) +├── roadmap.md ← historical B-phase log (archived) +│ +├── dsp/ ← C++17 DSP reconstruction (THE CANON) +│ ├── framed_model.{cpp,hpp} ← MAIN: mask-apply chain (empirical bridge) +│ ├── render48k.cpp ← 48k/4096 structural pipeline (resample→chain→resample) +│ ├── spectral.{cpp,hpp} ← STFT/ISTFT processor + FIR builder +│ ├── fn529fe0.{cpp,hpp} ← structural chain 9–19 (FUN_180529fe0) +│ ├── fnfaith.{cpp,hpp} ← faithful detector cascade (BLOCKMAP transcription) +│ ├── fft{,_plan,_stage}.cpp/hpp ← FFT engine (canonical + RFFT bit-exact) +│ ├── twin.{cpp,hpp} ← twin resonator (FUN_180535880, float-parity) +│ ├── rt_mask_tables.{hpp,.cpp} ← live IIR A/B coefficients (385K) +│ ├── rt_weights.{hpp,.cpp} ← live kWarp/kBand768 tables (44K) +│ ├── fftconv.{cpp,hpp} ← FFT convolution FIR application +│ ├── vlog.{cpp,hpp} ← fast log2 approximation +│ ├── exp2.{cpp,_tables.cpp,hpp} ← fast exp2 approximation +│ ├── levelpath.{cpp,hpp} ← level-curve path (xv = log10(am/res)) +│ ├── freqpath.{cpp,hpp} ← frequency-axis warp/freq-domain helpers +│ ├── leveltrack.{cpp,hpp,hpp} ← envelope follower (attack/release tables) +│ ├── log2_ln.{cpp,hpp} ← log/ln utilities +│ ├── filter.{cpp,hpp} ← detection kernel (legacy) +│ ├── detect.{cpp,hpp} ← detector front-end (legacy) +│ ├── phase_table.{cpp,hpp} ← phase table for FFT +│ ├── ms.hpp ← mid-side helpers +│ ├── params.hpp ← parameter struct +│ ├── rotor_kernel.hpp ← rotor transform kernel +│ ├── rt_div_tables.hpp ← division tables +│ ├── soothe_constants.hpp ← decoded constants +│ ├── cody_waite.hpp ← Cody-Waite argument reduction +│ ├── twiddle_{builder,loader}.cpp/hpp ← FFT twiddle factors +│ ├── dsp_ctx.hpp ← DSP context layout +│ ├── framed_test.cpp ← CLI bridge renderer (44.1k) +│ ├── harness.cpp ← legacy harness +│ ├── *_check.cpp ← bit-exact unit test targets +│ └── CMakeLists.txt +│ +├── scripts/ +│ ├── corpus.py ← bridge regression harness (62 cases, --compare) +│ ├── corpus_structural.py ← structural chain harness (--vs-bridge) +│ ├── rendersnap2.py ← RENDER_FILE stopper (reads from .rpp) +│ ├── campaign.py ← parameter sweep cell (~8 min) +│ ├── cascade_sim.py ← numpy step 9–19 simulator +│ ├── disasm_func.py ← capstone disasm with RIP constants +│ ├── iat_name.py ← runtime import resolution +│ ├── wine_{chain,stage,ptrace}_trace.py ← ptrace-based live trace +│ ├── dump_dispatch.py ← table/state dumper +│ ├── probe_{states,mem}.py ← live state/memory probes +│ ├── hunt2.py ← ctx-instance hunter +│ ├── scan_{pairs,lutsub}.py ← memory diagnostics +│ ├── fit_vlaw_{params,by_group}.py ← VLAW law calibration +│ ├── lawfit22r.py ← law fitting (VLAW α/β/c) +│ ├── mk_{dist,far,multi6}.py ← RPP generators +│ └── render_parity.py ← model-vs-render comparison +│ +├── handoff/ +│ ├── NOTES_LEVEL.md ← live journal (head: 24mm5+) +│ ├── NOTES_LEVEL_INDEX.md ← journal index by date/topic +│ ├── BLOCKMAP_529fe0.md ← FUN_180529fe0 method map (53K) +│ ├── NOTES_TWIN.md ← twin reference +│ ├── NOTES_CAPTURE.md ← live-capture protocol +│ ├── NEXT_PROMPT.md ← entry point for new sessions +│ ├── SESSION_HANDOFF.md ← handoff template +│ ├── archive/ ← historical NOTES_LEVEL_*.md, SESSION_HANDOFF_*.md +│ ├── nls_dasm/ ← 183 disassembly files (.dis, .bin) +│ ├── phase1/ ← phase-1 outputs +│ ├── rt*.npy ← captured runtime tables (48k/44.1k) +│ └── *.py ← emit/extract/joint scripts +│ +├── *.java ← Ghidra scripts (DumpFuns, ImportRtti…) +├── *.{bin,npz,npy,json,txt} ← datasets, dumps, LUTs (mostly outside git) +└── soothe-bt/ ← test corpus (~600 renders, outside git) +``` + +--- + +## 3. Build System + +**Generator**: CMake 3.10+, C++17, GCC/Clang with `-O3 -march=native`. + +```cmake +# Key targets +soothe2_dsp # shared library (all dsp/*.cpp) +framed_test # CLI bridge renderer (44.1k) +render48k # structural renderer (48k/48000) +twin_check # float-parity unit test +tables_check # live-table verification +fftconv_check # FIR convolution check +vlog_check # fast log2 check +leveltrack_check # envelope follower check +levelpath_check # level-curve path check +exp2_check # fast exp2 check +fn529fe0_check # structural chain check +soothe2_harness # legacy harness +``` + +**External deps**: `libsamplerate` (render48k only), `pthread`. + +**Tooling hazard**: CMake skips rebuild when source modified within same second. Protocol: `touch` source before build + verify binary mtime. + +--- + +## 4. DSP Architecture + +### 4.1 Signal Flow (current canon: structural `render48k`) + +``` +Host 44.1k → resample → 48k → [per-channel processing] → resample → 44.1k Host + ↓ + ┌─────────────────────┐ + │ FramedDetector │ + │ (per 4096 block) │ + │ │ + │ am[] ← envelope │ + │ res[] ← twin resp │ + │ ↓ │ + │ lvl_raw = am/res·sf │ + │ ↓ │ + │ [RT_VLAW=1]: │ + │ cut = α·ln1p(L/β) │ + │ +c [+Δ] │ + │ mask = 10^(-cut/20)│ + │ ↓ │ + │ warp: mask *= │ + │ kBand·kWarp·res^rp│ + │ ↓ │ + │ IIR3 ×2 (bidir) │ + │ ↓ │ + │ mask_out → multiply │ + │ spectrum[k] *= mask │ + └─────────────────────┘ +``` + +### 4.2 Dual Render Path + +| Path | File | Grid | Use | +|------|------|------|-----| +| Bridge | `framed_model.cpp` | 44.1k/2048 | Legacy, TOTAL 1.594 | +| Structural | `render48k.cpp` | 48k/4096 | Canon, TOTAL 0.341 | + +**Dual-solution env set**: `RT_VLAW=1 RT_SYN=1 RT_NOWARP=1 RT_NOIIR3=1 RT_IIR12=0` + +### 4.3 Key Modules + +| Module | Responsibility | +|--------|---------------| +| `FramedDetector` | Per-band, per-frame mask computation. Holds `am_`, `res_`, `track_` state. | +| `SpectralProcessor` | STFT/ISTFT, OLA overlap-add, FIR application modes. | +| `fn529fe0` | Structural chain 9–19 (steps 9–19 of FUN_180529fe0): scale→IIR1→IIR2→blend→combine→warp→IIR3→dry/wet. | +| `fnfaith` | Faithful detector cascade transcription (BLOCKMAP). | +| `twin` | Twin resonator `|2B/A|` — frequency response per band. | +| `rt_mask_tables` | Live IIR A/B coefficients (kIIR_A1/A2/A3, kIIR_B1/B2/B3, kRTAtt, kRTRel). | +| `rt_weights` | Live warp weights (kBand768, kWarp). | +| `fft` | Bit-exact RFFT (th1a90/th2180) with `buf548`/`mask598` tables. | +| `fftconv` | FFT-based convolution for FIR application modes. | +| `vlog`/`exp2` | Fast polynomial approximations matching plugin精度. | +| `leveltrack` | Envelope follower with per-bin attack/release tables. | + +### 4.4 Detector Cascade (529c60) + +``` +complex_spectrum × twin_response → |z| + → Haar smooth [0.25,0.5,0.25] × n_iters + → peak = max(curve) + → sin_peak = sin(param·30 − 90) · 0.115129 · peak + → curve = max(curve, sin_peak) + → w = -log10(pow(50, ratio·0.001) · ratio·0.001) + → acc = acc·w + curve·(1-w) + → bands_curve = acc +``` + +--- + +## 5. Environment Flags (experiment control) + +| Flag | Effect | +|------|--------| +| `RT_VLAW=1` | Two-stage law: `mask = 10^(−(α·ln1p(lvl/β)+c)/20)` | +| `RT_SYN=1` | STFT without synthesis window (plugin's actual layer) | +| `RT_WIN=0/1/2` | Analysis window: sym-Hann / periodic / rect | +| `RT_NOWARP=1` | Skip warp modulation | +| `RT_NOIIR3=1` | Skip IIR3 ×2 | +| `RT_IIR12=0` | Skip freq-domain IIR1/2 (critical with VLAW) | +| `RT_DUMP_BIN=` | Dump tract binary (frame `RT_DUMP_FRAME`) | +| `RT_VDBG=1` | Print VLAW computations to stderr | +| `RT_FAITHFUL=1` | Use faithful chain (`fnfaith.cpp`) | +| `RT_FIRCONV=1/3` | FIR application mode (1=complex-mul, 3=`1.019·mask^1.8345`) | +| `RT_ENV=live` | Live envelope from kRTAtt/kRTRel tables | +| `RT_KMAP=1` | k-mapping correction (twin/am scaling) | +| `RT_EQ=1` | Pre-detector EQ bell | +| `RT_LUT_OFF=1` | Skip LUT transform | +| `RT_LUT_A/B/G/M` | LUT parameters (A=-24, B=28, gamma=1, mult=4.2) | + +--- + +## 6. Test Corpus & Metrics + +**Location**: `/home/m/soothe-bt/` (~600 renders, outside git). + +**Key sets**: + +| Prefix | Content | +|--------|---------| +| `tone1kq_*` | Single tone, fc-scan, quiet (-18 dBFS) | +| `tone1k_*` | Single tone, fc-scan, loud (0 dBFS) | +| `dual_b1q_*` | Two tones (500+2000), q 0.1…10 | +| `al_*` | Level sweep (fc=1000) | +| `comb_*` | 4-band multiband | +| `burst500_b1` | Primary reference (burst 500 Hz) | + +**Metric** (Goertzel steady-state): +```python +err_dB = 20·log1₀( ta(out,1000) / ta(ref,1000) ) +# trimmed to last 75% of input, matched to plugin render length +``` + +**Regression guards**: +```bash +python3 scripts/corpus.py # bridge + guard +python3 scripts/corpus_structural.py # structural chain +python3 scripts/corpus.py --compare scripts/baseline_bridge.json --tol 0.25 +python3 scripts/corpus_structural.py --vs-bridge scripts/baseline_bridge.json +``` + +--- + +## 7. Current Status (2026-08-29, 24mm14) + +| Group | Bridge | Structural (VLAW) | +|-------|--------|-------------------| +| t1kq (fc-scan) | 0.226 | 0.426–0.852 | +| t1k (loud) | 1.801 | 0.577–0.930 | +| al (level) | 0.638 | 0.090–0.804 | +| res | 0.628 | 0.395 | +| dual (q-sweep) | 0.726 | **0.193** ✓ | +| comb (4-band) | 10.149 | 2.678–4.335 | +| **TOTAL** | **1.594** | **0.341** | + +**Decoded**: +- Layer: STFT without synthesis window, per-bin mask multiply +- Law: `mask = 10^(−(α·ln1p(lvl/β)+c)/20)` with content-aware Δ +- FIR: `exp(0.984·ln(raw))` + Hann + normalize → bit-exact RFFT to df0 + +**Open gaps**: +1. **Chain 9–19** (priority #1): Dataflow decoded, bigkernel bodies known, I/O format unknown. Target: <0.05. +2. **k-mapping** (priority #2): twin/am scaling `k(q≥2)=0.403`. +3. **Δ second-peak rule** (priority #3): Content-dependent gain, requires live-dump. + +--- + +## 8. Reference Documents + +| Doc | Content | +|-----|---------| +| `README.md` | TOTAL metric, reproduction steps | +| `AGENTS.md` | Build commands, env flags, hazard, corpus format | +| `BITEXACT_PLAN.md` | 3-step plan to byte-exact | +| `handoff/BLOCKMAP_529fe0.md` | Method map for FUN_180529fe0 | +| `handoff/NOTES_LEVEL.md` | Live working journal | +| `handoff/NOTES_LEVEL_INDEX.md` | Journal index | +| `handoff/NOTES_TWIN.md` | Twin resonator reference | +| `handoff/NOTES_CAPTURE.md` | Live-capture protocol | +| `handoff/nls_dasm/` | 183 disassembly files | + +--- + +## 9. Reproduction & Development Protocol + +1. Install soothe2 VST3 (Windows) under yabridge → `dump_soothe.py` → `soothe_mem.bin` +2. Ghidra headless: `analyzeHeadless soothe_x64 -process soothe_mem.bin -noanalysis -postScript .java` +3. Renders: `sweep.py` → `.rpp`, `reaper -renderproject` → `.wav` +4. Analysis: `render_parity.py` / `corpus.py` +5. After C++ edit: `touch` source → `cmake --build dsp/build --target framed_test` → run corpus guards