Rewrite model card: lead with audio, tighten prose, re-measure on screened koan ladder

README.md

@@ -17,223 +17,176 @@ tags:
 # SAME-L Decoder LoRA (`squeakfix_v3`)
 
 A LoRA on **SAME-L's decoder**. It changes how latents are rendered to audio, not
-how latents are produced.
+how latents are produced — the encoder is untouched, so the latent space, the DiT
+and every existing DiT LoRA stay bit-compatible, and this stacks with them in any
+order.
 
-The encoder is untouched, so the latent space, the DiT and every existing DiT
-LoRA stay bit-compatible. This adapter stacks with them in any order.
+It fixes one thing: the high-frequency squeaks SAME's autoencoder manufactures on
+percussion when audio goes round the encode/decode loop more than once. SAME
+downsamples 44.1 kHz stereo by 4096×, so a snare attack lives entirely inside a
+single latent frame — the decoder doesn't reconstruct that attack, it
+resynthesizes one, slightly differently every pass. Nothing in SAME's training
+objective ever asked that `encode(decode(z)) ≈ z`; every loss is
+`real audio → latent → real audio`. This adapter adds that objective after the
+fact, on the decoder only. Since a continuation or a transform re-encodes its
+input, a chained session compounds the artifact — that's where this earns its
+place.
 
-It exists to fix one specific thing: the high-frequency squeaks and chirps that
-SAME's autoencoder manufactures on percussion when audio goes round the
-encode/decode loop more than once — which is what every chained continuation
-does.
+Trained and used by [the collabage patch](https://huggingface.co/thepatch), in
+production in a live `stable-audio-3` backend since 2026-08-14. Ship at
+strength **1.0** — that's where it was trained and auditioned.
 
-**Trained and used by [the collabage patch](https://huggingface.co/thepatch).**
-In production in a live `stable-audio-3` backend since 2026-08-14.
+## Hear it
 
----
+Since we keep struggling to produce clean metrics surrounding this artifact, we
+place these examples so you can really hear what it's doing.
+
+Same latent, same seed, decoder adapter the only variable; every clip is 15 s,
+peak-matched to −1 dBFS so level can't masquerade as quality. Generated with the
+`koan` DiT LoRA on `medium`.
+
+### Round trips — where it earns its place
+
+| | stock decoder | `squeakfix_v3` |
+|---|---|---|
+| **jungle** — fresh generation | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/jungle_stock_d0.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/jungle_v3_d0.wav"></audio> |
+| **jungle** — after 3 round trips | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/jungle_stock_d3.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/jungle_v3_d3.wav"></audio> |
+| **drums** — fresh generation | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/drums_stock_d0.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/drums_v3_d0.wav"></audio> |
+| **drums** — after 3 round trips | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/drums_stock_d3.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/drums_v3_d3.wav"></audio> |
+| **neurofunk** — fresh generation | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/neurofunk_stock_d0.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/neurofunk_v3_d0.wav"></audio> |
+| **neurofunk** — after 3 round trips | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/neurofunk_stock_d3.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/neurofunk_v3_d3.wav"></audio> |
+
+These three prompts were **not** selected for artifact content — they are
+ordinary koan generations, and the fresh-generation rows are here so you can
+follow the progression rather than because much is audible in them. Three round
+trips is a short chained session: two continuations and a transform get you
+there. jungle is the worst of the three; drums and neurofunk are unremarkable.
+
+It isn't winning by sanding the top end, which is the easy way to fake this. At
+d3 all three hold **2.0 to 9.3 dB more** 12–16 kHz and 16–22 kHz energy than the
+stock render, at a higher RMS, while showing a fraction of the tonal frames. The
+only band that ever drops is 8–12 kHz on the drums clip, by 0.9 dB — and that is
+exactly where the artifact concentrates.
+
+### A fresh generation — subtler, but we do hear it
+
+We swear we hear it on initial generations too, and it is **much** more subtle.
+This pair is the worst of 16 candidates, screened by how far tonality runs away
+over 3 round trips with the adapter off — screening is how you find an audible
+A/B for something this small, and it means this pair is a worst case, not a
+typical one.
+
+| | stock decoder | `squeakfix_v3` |
+|---|---|---|
+| **glitch hop** — fresh generation, screened | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/glitchhop_stock_d0.wav"></audio> | <audio controls src="https://huggingface.co/thepatch/same-l-decoder-lora/resolve/main/samples/glitchhop_v3_d0.wav"></audio> |
+
+What changes here is **air, not squeak count**. Across the three screened
+generations the adapter moves tonality by −0.37 dB at d0 — nothing — while
+restoring **1.5 to 2.4 dB** of 16–22 kHz top octave in every one. On this
+particular pair tonality moves −0.08 dB, i.e. not at all, and air moves +2.4 dB.
+If you are looking for the difference in a tonal-frame count you will not find
+it.
 
 ## Usage
 
-Requires the `target: "decoder"` support in
+Requires `target: "decoder"` support in
 [Stability-AI/stable-audio-3](https://github.com/Stability-AI/stable-audio-3).
-No special loading path — the `target` field in the checkpoint config is what
-routes it.
+The `target` field in the checkpoint config is what routes it; there's no special
+loading path.
 
 ```bash
-python run_gradio.py --model medium-base \
-    --lora-ckpt-path squeakfix_v3.safetensors
-```
-
-Stacked with a DiT LoRA, in either order:
+python run_gradio.py --model medium-base --lora-ckpt-path squeakfix_v3.safetensors
 
-```bash
+# stacks with a DiT LoRA, either order
 python run_gradio.py --model medium-base \
     --lora-ckpt-path my_style.safetensors squeakfix_v3.safetensors
 ```
 
-Directly on the autoencoder:
-
 ```python
 from stable_audio_3 import AutoencoderModel
 from stable_audio_3.models.lora.loader import load_and_apply_loras
+from stable_audio_3.models.lora.model import set_lora_strength
 
 ae = AutoencoderModel.from_pretrained("same-l", device="cuda").autoencoder
 load_and_apply_loras(ae, ["squeakfix_v3.safetensors"], "autoencoder")
+set_lora_strength(ae.decoder, 1.0)   # separate call; 0.0 is the stock decode
 
-latents = ae.encode(waveform)
-audio = ae.decode(latents)
+audio = ae.decode(ae.encode(waveform))
 ```
 
-Strength is a **separate call** — `lora_configs` at inference only gates the
-sigma interval and layer filter:
-
-```python
-from stable_audio_3.models.lora.model import set_lora_strength
-set_lora_strength(ae.decoder, 1.0)   # 0.0 renders at the stock decode
-```
-
-Ship at strength **1.0**. It was trained there and it is where it was auditioned.
-
----
-
-## What it fixes
-
-SAME downsamples 44.1 kHz stereo by 4096×, so there is one latent frame per
-93 ms and a snare attack lives entirely inside a single frame. The decoder does
-not reconstruct that attack — it resynthesizes one, slightly differently every
-pass.
-
-A single generation is fine. The problem is **feedback**: a continuation
-re-encodes previously decoded audio, so N chained continuations put the audio
-through N round trips. Measured on the round-trip ladder with no DiT involved,
-invented HF energy climbs ~15 dB over six iterations while lost HF stays flat,
-and every one of the twelve worst frames lands within 35 ms of a detected onset.
-
-Nothing in SAME's training objective ever asked that `encode(decode(z)) ≈ z` —
-every loss is `real audio → latent → real audio` — so round-trip idempotence has
-no reason to hold, and it does not. This adapter adds that objective after the
-fact, on the decoder only.
-
-### What it sounds like
-
-Squeaks and chirps on hi hats, snares and percussion fills — a hat turning into a
-little whistle. Present on a single generation and worse every time the audio goes
-back through the autoencoder, which a continuation and a transform both do.
-
-### Measured effect
-
-Tonal frames (>12 dB tonality, 6–16 kHz) on 2-minute generations, mean of 4, the
-decoder adapter the only variable:
-
-| depth | stock | `squeakfix_v3` | | 12–16 kHz | SI-SDR vs own d0 |
-|---|---|---|---|---|---|
-| d0 — fresh generation | 364 | 422 | −16% | −5.6 → −5.3 | — |
-| d1 — one transform or continuation | 432 | 445 | −3% | −6.2 → −5.5 | 14.7 → 18.3 |
-| d2 | 821 | 519 | **37% fewer** | −6.6 → −5.6 | 10.1 → 13.7 |
-| d3 | 1665 | 619 | **63% fewer** | −7.1 → −5.8 | 7.8 → 11.2 |
-
-The last two columns are there because a tonal-frame count can fall for the wrong
-reason — an adapter that sands the top end posts a great count. This one does the
-opposite: at every depth it holds **more** 12–16 kHz energy than stock, sits
-marginally louder, and stays closer to its own depth-0 render, so it drifts less
-with depth rather than erasing what drifts. The band that drops is 8–12 kHz,
-where the artifact concentrates.
-
-Same shape at fp16 serving precision, on two different DiT LoRAs, at 30 s and
-120 s. Because a transform and a continuation each re-encode their input,
-anything past the first generation already sits at d≥1 and a chained session
-climbs from there — that is where this earns its place.
-
-### The honest gap
-
-**The squeak is clearly audible at d0 — hi hats and snares especially, reported
-by several listeners — and no metric here shows it.** Tried and flat or slightly
-negative at d0: tonality p95 in 6–16 kHz and 1–8 kHz, frame counts over 10/12/15
-dB, onset-locked tonality excess, fp32 and fp16, both LoRAs, both lengths.
-
-The likely reason is that the measurement has no headroom at d0: ~640 of ~10,300
-frames already read as tonal before any re-encoding, because cymbals and
-distorted guitar genuinely are tonal, and a few dozen added squeak frames cannot
-move a count that size. Separating artifact from content works at depth but not
-at d0 without a clean reference, which generated audio does not have.
-
-There is also precedent in this project for the tonality detector pointing the
-wrong way — on SAME-S the clip that sounds squeakiest scores lowest. So the d0
-−16% is not evidence the adapter hurts; it is a regime where this instrument does
-not resolve.
-
-Listen before deciding. Do not take the d0 number as the verdict.
-
-On the round-trip ladder against real held-out audio — the eval this checkpoint
-was selected against:
-
-| metric | stock | `squeakfix_v3` | Δ |
-|---|---|---|---|
-| tonality p95 | 17.08 | **9.41** | −7.67 |
-| transient excess (dB) | 6.32 | **1.24** | −5.08 |
-| latent drift per round trip | 10.91 % | **5.85 %** | −5.06 pp |
-| onset artifact (dB) | −3.50 | −7.53 | −4.03 |
-
-`transient excess` is added-HF on transient frames minus that on sustained
-frames; positive means the artifact rides percussion, which is its signature.
-
----
-
-## Honest limits
-
-**Any decoder LoRA trained this way stamps a comb into the output — this one
-doesn't, and that is the whole reason it exists.** The autoencoder's un-patch is
-a bare reshape at `patch_size 256`, so output channel index and
-time-position-within-patch are the same axis, and any channel-wise bias the
-adapter learns is repeated identically in every patch. That is a harmonic comb at
-`sr/256 = 172.27 Hz`, with an F3 fundamental — it reads as a wrong note, not as
-noise. It is inaudible in a mix and obvious once a stem separator strips the
-masking content, which is how it was found.
-
-`squeakfix_v3` was trained with an explicit penalty on that structure
-(`--lambda_patch 30`). A `v1` trained identically *without* it is the control.
-
-Measured on the distribution that matters — audio **generated by the model
-itself** (medium + a DiT LoRA), the same latents decoded through each adapter, so
-the decoder is the only variable. Comb excess in dB over a control comb at
-meaningless spacing, mean of 4 generations:
-
-| variant | comb excess | vs stock |
-|---|---|---|
-| stock | 2.80 | — |
-| v1 @ strength 1 | 13.70 | **+10.90** |
-| **v3 @ strength 1** | 1.97 | **−0.83** |
-| stock, +3 round trips | 1.64 | −1.17 |
-| v1 @ 1, +3 round trips | 13.34 | +10.54 |
-| **v3 @ 1, +3 round trips** | 1.37 | **−1.43** |
-| v1 @ strength 2 | 18.52 | +15.72 |
-| **v3 @ strength 2** | 3.49 | **+0.68** |
-
-v1 adds ~11 dB of comb. **v3 sits at or slightly below stock**, and stays there
-under re-encoding. Even at strength 2 — double what it ships at, where every
-effect is 2–4× clearer — it is within 0.7 dB of stock, while v1 is nearly 16 dB
-above it.
-
-One caveat for anyone reproducing this: on **real** audio pushed round the
-autoencoder, rather than on model output, v3 measures +1.5 to +4.0 dB of comb
-excess instead of ~0. Real music and model output are different distributions and
-the artifact does not behave the same on both. Measure on generated audio — that
-is what the decoder is actually asked to render, and it is where the artifact was
-audible in the first place.
-
-Other things worth knowing:
-
-- **This is one checkpoint from one dataset**, and it was selected partly by ear.
-  The in-loop ladder kept improving past step 2000; step 2000 is what was chosen
-  on re-encode behaviour and listening. Your material may want a different one.
-- **The squeaks it targets are partly an upstream prompt-distribution problem.**
-  Out-of-distribution prompts produce far more of the offending frames than
-  in-distribution ones. This adapter reduces the artifact; it does not make
+## Measured
+
+Four `koan` generations of 2 minutes, screened from 12 candidates by how far
+6–16 kHz tonality runs away with the adapter off. Each latent is decoded twice —
+adapter off, adapter on — and each chain re-encodes in place, so dN is genuinely
+N round trips of that decoder config. The adapter is the only variable.
+
+| depth | tonality p95 | tonal frames | 12–16 kHz | SI-SDR vs own d0 |
+|---|---|---|---|---|
+| d0 — fresh generation | 11.25 → 11.33 | 780 → 933 | 20.7 → 21.4 | — |
+| d1 — one continuation or transform | 12.46 → **11.59** | 972 → 1074 | 19.9 → **21.2** | 13.5 → **17.5** |
+| d2 | 14.42 → **11.81** | 1492 → **1246** | 19.3 → **21.0** | 8.9 → **12.8** |
+| d3 | 17.03 → **12.06** | 2453 → **1411** | 18.6 → **20.9** | 6.7 → **10.4** |
+
+**Stock tonality climbs +5.79 dB over three round trips. With the adapter it
+climbs +0.73 dB.** That holds on every generation individually — stock +4.98 to
++6.97, the adapter +0.18 to +1.40 — and it is the whole claim: the artifact
+stops compounding.
+
+**The tonal-frame column rises at d0 and d1, and that is not a regression.**
+That count rewards peakiness, and the adapter puts high-frequency energy back;
+restored harmonics read as tonal. It is also dominated by two of the four
+generations, which start near 1000 and 2100 frames because glitchcore genuinely
+is tonal. The other two start at **zero** and stay there with the adapter — 0 →
+39 and 0 → 8 at d3 — while stock reaches 1038 and 268. Where the artifact has
+room to appear, the adapter suppresses it; where the material is already tonal,
+the count cannot tell artifact from content. Read p95, not the count.
+
+**It is not sanding the top end**, which is the easy way to post a good number.
+At every depth it holds more 12–16 kHz energy than stock and the gap *widens*
+with depth (+0.70, +1.31, +1.76, +2.30 dB at d0–d3), while SI-SDR against its
+own d0 runs 3.6 to 3.9 dB better. It drifts less rather than erasing what drifts.
+
+At d0 the change is air, not squeak count: on a separate screened 30 s set the
+adapter moves tonality by −0.37 dB — nothing — while restoring 1.5 to 2.4 dB of
+16–22 kHz top octave in all three generations. Trust the clips above over any of
+these numbers.
+
+This table is `koan` at 120 s and fp16. An earlier unscreened run covering `kev`
+as well, at both 30 s and 120 s, showed the same direction at depth.
+
+## Limits
+
+- **Decoder LoRAs trained this way stamp a comb into the output — this one
+  doesn't, and that's most of why it exists.** The un-patch is a bare reshape at
+  `patch_size 256`, so output channel and time-position-within-patch are the same
+  axis, and any channel-wise bias the adapter learns repeats identically in every
+  patch: a harmonic comb at `sr/256 = 172.27 Hz` that reads as a wrong note, not
+  as noise. Inaudible in a mix, obvious once a stem separator strips the masking
+  content, which is how it was found. `--lambda_patch 30` is what prevents it. On
+  model output, a `v1` control trained on the identical recipe with
+  `--lambda_patch 0` sits **+10.9 dB** of comb excess over stock; v3 sits
+  **−0.8 dB**, and both hold that gap through three further round trips. On
+  *real* audio rather than model output v3 measures +1.5 to +4.0 dB — different
+  distribution, so measure on generated audio.
+- **SAME-L only.** SAME-S shares the patch grid but its artifact sits 1–8 kHz and
+  wants a different recipe. Loading this there won't error; it'll sound wrong.
+- **The gain scales with re-encode depth** — small for one-shot generation, it
+  compounds across chained continuations.
+- **The squeaks are partly an upstream prompt-distribution problem.** OOD prompts
+  produce far more offending frames; this reduces the artifact, it doesn't make
   prompt choice irrelevant.
-- **The benefit scales with re-encode depth.** If your workflow is one-shot
-  generation and nothing else, the measurable gain is small. If you chain
-  continuations or transforms, it compounds in your favour.
-- **It is a SAME-L adapter.** SAME-S has the same patch grid but its artifact
-  sits in a different band (1–8 kHz rather than 6 kHz and up) and wants a
-  different recipe. Loading this on SAME-S will not error — it will just sound
-  wrong.
+- **One checkpoint, one dataset, chosen partly by ear** at step 2000 on re-encode
+  behaviour. Your material may want a different one.
 - **Neither half of the autoencoder is bit-deterministic** (encoder 1.5 %
-  relative, decoder 7e-3 max abs). Any A/B you run against this adapter has to be
-  read as a multiple of those floors; absolute tolerances are meaningless.
-
----
+  relative, decoder 7e-3 max abs) — read any A/B as a multiple of those floors.
 
 ## Training
 
-| | |
-|---|---|
-| base model | `stabilityai/SAME-L` |
-| target | `decoder` (encoder frozen) |
-| rank / alpha | 16 / 16.0 |
-| trainable | 5.63M params, 98 tensors (~1.30 % of the decoder) |
-| checkpoint | step 2000 of a run configured for 8000, stopped at 4000 |
-| precision | fp32 training, fp16 storage |
-| hardware | single GB10 (DGX Spark), ~2.9 s/step at 10 s crops, under 10 GB |
+Self-supervised — audio only, no captions, no paired data. Rank 16 / alpha 16,
+5.63M trainable params (~1.30 % of the decoder), step 2000 of a run configured
+for 8000, fp32 training and fp16 storage, single GB10 (DGX Spark) at ~2.9 s/step
+on 10 s crops, under 10 GB.
 
 ```bash
 python scripts/train_decoder_lora.py \
@@ -246,39 +199,16 @@ python scripts/train_decoder_lora.py \
     --out_dir out/declora
 ```
 
-The objective is self-supervised — audio only, no captions, no paired data.
 Latents come from three buckets: real audio, drifted audio (`E(D(E(x)))` at depth
-≥ 1, targeted against the **original** audio so the decoder is asked to undo
-accumulated drift), and latents sampled from the base DiT. The DiT bucket earns
-its place because generated latents drift 15–18.5 % against real audio's 10.5 %,
-and that gap is in the base model rather than in any adapter.
-
-Losses: multi-resolution log-STFT L1 (K-weighted, kept deliberately — this
-decoder over-generates HF, so removing the perceptual de-emphasis would push the
-wrong way), relative round-trip consistency `‖E(D(z)) − z‖/‖z‖` with the encoder
-frozen, a **one-sided** HF tonality penalty (so legitimate cymbal ring and
-sibilance are never punished), and the patch-grid penalty described above. No
-discriminator: adversarial training makes a decoder invent *more* detail, and the
-failure mode of plain reconstruction losses is the direction this wants.
-
-Full method, ablations and traps: [Decoder LoRA
-workflow](https://github.com/Stability-AI/stable-audio-3/blob/main/docs/workflows/decoder-lora.md).
+≥ 1, targeted against the **original** so the decoder is asked to undo
+accumulated drift), and latents sampled from the base DiT. No discriminator —
+adversarial training makes a decoder invent *more* detail, and the failure mode
+of plain reconstruction losses is the direction this wants.
 
----
-
-## Files
-
-| file | what it is |
-|---|---|
-| `squeakfix_v3.safetensors` | the adapter — SAME-L decoder, rank 16, trained with `--lambda_patch 30` |
-
-Provenance (base model, step, full recipe) is embedded in the file's
-`lora_config` metadata, so it identifies itself without this card.
-
-The `v1` column in the tables above is an internal checkpoint trained on the
-identical recipe with `--lambda_patch 0`. It is not published — it is reported
-because "the patch penalty matters" is a claim that needs the control.
-
-## Citation
+Full method, losses, ablations and traps: [Decoder LoRA
+workflow](https://github.com/Stability-AI/stable-audio-3/blob/main/docs/workflows/decoder-lora.md).
+Provenance — base model, step, full recipe — is embedded in the file's
+`lora_config` metadata, so the checkpoint identifies itself without this card.
+`v1` (identical recipe, `--lambda_patch 0`) is an internal control, not published.
 
 The autoencoder this adapts: [SAME](https://arxiv.org/abs/2605.18613).