Rebuild CODA on Stable Audio 3 Small Music

Replace the MusicGen multi-pass chaining with SA3's native audio
inpainting: one diffusion call continues the clip into a finished
44.1kHz stereo track, deleting the windowed passes, energy guards and
re-roll logic entirely.

- engine.py: SA3 continuation core. preload() to CPU at boot, fp16 on
GPU inside the @spaces.GPU window; inpaint mask = [source_end, total];
source clip cast to model dtype; Windows-safe seed; over-long clips
rejected so the mask can't invert.
- stitch.py: stereo-native splice. Loudness-match, short equal-power
crossfade at the seam, cos^2 closing fade, peak guard, all at 44.1k.
- verify.py: dev-only math QA — duration, silence-collapse, clipping,
seam/loudness/tempo/key continuity, spectral rolloff, stereo width,
with a dark diagnostic plot.
- app.py: dark "DAW console" UI. Total-length slider (30-120s), optional
vibe prompt, instant on-upload analysis, staged progress, output player
built visible. Over-long uploads blocked with a clear message.
- requirements.txt mirrors Stability's ZeroGPU stack: torch 2.7.1/cu128,
stable-audio-tools from upstream, pytorch_lightning; Demucs dropped.
- Retarget tests to the new modules; drop the MusicGen build (preserved
on the musicgen-fallback branch) and stale research notes.

Verified end-to-end on Blackwell: 8-step generation in ~1s, all verify
gates pass on the default 60s continuation; full UI flow tested.

.gitignore

@@ -32,3 +32,8 @@ Thumbs.db
 *.pdf
 umbra-ai-architecture.md
 memory-audit-*.md
+
+# local planning / scratch / research artifacts — never ship to the public Space
+PLAN_*.md
+RESEARCH_*.md
+*coda_commits*

README.md

@@ -1,7 +1,7 @@
 ---
 title: CODA
 emoji: 🎵
-colorFrom: yellow
+colorFrom: indigo
 colorTo: yellow
 sdk: gradio
 sdk_version: 6.16.0
@@ -11,7 +11,7 @@ pinned: false
 license: mit
 short_description: AI that finishes the song you quit on.
 models:
-  - facebook/musicgen-medium
+  - stabilityai/stable-audio-3-small-music
 ---
 
 # CODA — the songs you quit on, finished.
@@ -23,83 +23,101 @@ key, same tempo, same groove — then splices the new part onto your original so
 cleanly you have to hunt for the seam.
 
 One job, done well. No lyric bot, no cover-art printer — just a real, listenable
-continuation of *your* clip.
+continuation of *your* clip, in 44.1 kHz stereo.
 
 ## How it works
 
 1. **Listen.** librosa detects the key, tempo, and meter — pure DSP, no ML. If
    the recording is lo-fi (a voice memo, a phone capture, an old MP3 rip), CODA
    cleans a *copy* first — rumble filter, spectral noise gate, level — and
-   listens to that, so it follows the *song* and not the hiss. Your real
+   conditions on that, so it follows the *song* and not the hiss. Your real
    original still goes into the final track (tick **remaster my part** to apply
    the same cleanup to your section too).
-2. **Separate.** HT-Demucs splits vocals from the instrumental. MusicGen was
-   trained on instrumental music, so feeding it a vocal prompt is
-   out-of-distribution — it garbles or drops the voice. CODA prompts MusicGen
-   with the *instrumental* (the sum of the non-vocal stems, which also drops the
-   tape hiss Demucs couldn't attribute to an instrument). Your original vocals
-   carry the front of the finished track.
-3. **Continue.** MusicGen-medium extends the music from the cutoff: a first pass
-   that listens to 20s of your clip, then chained 12s-context / 18s-new passes,
-   every one inside the model's trained 30s window. There's **no text prompt** —
-   classifier-free guidance is off (`guidance_scale=1.0`), because in MusicGen's
-   CFG the text condition is all that gets amplified and the audio prompt cancels
-   out; a caption would only drag the output toward generic stock music. The
-   single biggest quality lever is hidden here: **every prompt is RMS-normalized
-   to a confident level before the model sees it.** A quiet lo-fi prompt is what
-   makes MusicGen drift into silence and "ghost noise"; hand it a full-level
-   prompt and the continuation stays sustained and full. A per-pass energy guard
-   holds the level and re-rolls any pass that collapses.
-4. **Stitch.** The continuation is loudness-matched to your recording and the
-   splice lands inside the codec-aligned overlap with an **equal-gain** crossfade
-   (equal-power would swell +3dB on correlated audio — an audible seam). The
-   track then fades out to a clean close instead of cutting off mid-phrase.
+2. **Continue.** [Stable Audio 3 Small Music](https://huggingface.co/stabilityai/stable-audio-3-small-music)
+   does the rest in a **single call**. SA3 is a latent-diffusion model with
+   native audio *inpainting*: CODA places your clip at the front of the buffer
+   and masks the region after it, and the model fills that region — conditioned
+   on the whole clip — with a coherent continuation. No 30-second windows, no
+   multi-pass chaining, no energy guards, no re-rolls. Eight diffusion steps with
+   the pingpong sampler, a couple of seconds on a GPU. Leave the vibe box empty
+   for a pure audio-led continuation that holds your key and tempo; type a vibe
+   to creatively steer the new section.
+3. **Stitch.** The continuation is loudness-matched to your recording, joined at
+   the seam with a short equal-power crossfade, and faded out to a clean close.
+   Everything is 44.1 kHz stereo — your original is resampled up to meet the SA3
+   tail, never the other way around.
 
 Progress streams through every stage, so you never stare at a dead screen.
 
+## Why Stable Audio 3 (and not MusicGen)
+
+CODA's earlier builds fought MusicGen's limits: a 30 s trained window forcing
+fragile multi-pass chaining, 32 kHz mono output, and a tendency to drift into
+silence on quiet prompts. SA3 Small Music removes all of it at once:
+
+| | MusicGen-medium | SA3 Small Music |
+|---|---|---|
+| Continuation | chain 12 s-ctx / 18 s-new passes, compounding drift | one native inpaint call over the whole clip |
+| Output | 32 kHz **mono** | **44.1 kHz stereo** |
+| Speed | multiple passes per track | ~8 steps, a couple of seconds |
+| License | CC-BY-NC (non-commercial) | Stability Community (commercial < $1M revenue) |
+
+The hardest, most fragile part of the old build — the windowed chaining with its
+energy guards and collapse re-rolls — is simply deleted.
+
 ## The stack — small on purpose
 
 | Component | Size | Job |
 |---|---|---|
-| [MusicGen Medium](https://huggingface.co/facebook/musicgen-medium) | 1.5B | audio-prompted music continuation |
-| HT-Demucs | ~80M | vocal / instrumental separation |
+| [Stable Audio 3 Small Music](https://huggingface.co/stabilityai/stable-audio-3-small-music) | ~0.6B | native audio-inpaint continuation |
+| T5Gemma (bundled with SA3) | ~0.5B | optional text conditioning for the vibe box |
 | librosa + SciPy | 0 params | key/tempo/meter detection, lo-fi cleanup |
 
-Well under the 32B cap, runs entirely on a single ZeroGPU window, no cloud APIs.
-Why medium and not large? A/B'd on the same prompts, medium's continuations came
-back as dense or denser at half the latency — which on ZeroGPU buys more
-generation inside the window. Small collapses to near-silence on dense lo-fi
-prompts.
+Well under the 32B cap, runs entirely inside a single ZeroGPU window (generation
+is seconds, not the whole budget), no cloud APIs.
 
 ## What it won't pretend to do
 
-MusicGen can't generate vocals — Meta stripped voices from its training data by
-design. CODA doesn't fake it: the continuation is **instrumental**, and your
-original vocals play untouched up to the seam. The band plays on; you write the
-next verse.
+SA3 is a *music* model — the continuation is instrumental-leaning, and CODA
+doesn't fake vocals it can't generate. The honest design choice: **your original
+recording plays untouched up to the seam**, vocals and all, and the generated
+section carries the music on from there. The band plays on; you write the next
+verse. A typed vibe steers the new section creatively but can pull it away from
+the original's exact key and tempo — that's the trade you're choosing when you
+use it; leave it empty for a faithful continuation.
 
 ## Using it
 
-Upload a WAV, MP3, or FLAC (a 20–60 second clip works best), or hit **try the
-demo — PUSHBACK**. Pick how many seconds to add, optionally tick *remaster my
-part*, and press **Finish this song**. You'll see the detected key/tempo the
-moment a clip loads, watch the stages stream, and get the finished track to play
-or download.
+Upload a WAV, MP3, or FLAC (a 15–30 second clip works best), or hit **try the
+demo — PUSHBACK**. Set the finished length, optionally describe a vibe or tick
+*remaster my part*, and press **Finish this song**. You'll see the detected
+key/tempo the moment a clip loads, watch the stages stream, and get a 44.1 kHz
+stereo track to play or download.
 
-Run it locally:
+Run it locally (needs Python 3.10 and a CUDA GPU; the SA3 weights are gated, so
+accept the licence on the model page and `huggingface-cli login` first):
 
 ```bash
 pip install -r requirements.txt
 python app.py
 ```
 
+Deploying as a Space: because the SA3 weights are gated, add an **`HF_TOKEN`**
+secret (from an account that has accepted the licence) in the Space settings, or
+the model download 401s at startup. The bundled demo clip lives outside git (see
+`.gitignore`) — upload `examples/pushback_demo.mp3` to the Space directly.
+
 ## Notes for the curious
 
-The continuation settings come out of a deep dive into the transformers MusicGen
-source — write-up in
-[`RESEARCH_music_continuation_2026-06-10.md`](RESEARCH_music_continuation_2026-06-10.md).
-Code is MIT. MusicGen weights are CC-BY-NC (non-commercial) — fine here, worth
-knowing if you fork it.
+`verify.py` is a dev-only QA harness: it measures the finished track against the
+original for silence-collapse, clipping, seam continuity, tempo/key continuity,
+spectral rolloff, and stereo width, and writes a diagnostic plot. It is not in
+the app's runtime path — it's how regressions get caught between ear-checks.
+
+Code is MIT. SA3 weights are under the
+[Stability AI Community License](https://stability.ai/license) (free for
+commercial use under $1M annual revenue) and bundle a T5Gemma encoder under the
+Gemma Terms of Use — worth knowing if you fork it.
 
 **Demo clip credit:** `examples/pushback_demo.mp3` is a clip by the band
 **PUSHBACK**, sourced from TikTok, included solely as a sample to demonstrate the

RESEARCH_music_continuation_2026-06-10.md

@@ -1,163 +0,0 @@
-# CODA Music Continuation — Root-Cause Research & Recommendations
-
-**Date:** 2026-06-10
-**Scope:** Research only — no code changed. Sources: `transformers` source (modeling_musicgen.py, logits_process.py, feature_extraction_encodec.py), MusicGen paper (arXiv 2306.05284), audiocraft repo (model card, musicgen.py, genmodel.py, official demo notebook), facebook/musicgen-large generation_config.json, community issue threads, and June-2026 survey of alternative models.
-
----
-
-## TL;DR
-
-**The "weird funk pop" output is not a mystery — it's the predictable result of two settings interacting:**
-
-1. **`guidance_scale=7.0` amplifies ONLY the text prompt, never the audio prompt.** Verified in the transformers source: classifier-free guidance duplicates the audio-prompt tokens into *both* the conditional and unconditional branches, so they cancel out of the CFG formula `uncond + scale * (cond - uncond)`. Only the text-encoder states are nulled in the unconditional branch. The "style adherence" slider is therefore a **text-adherence** knob — at 7 it drags generation *away* from what the audio implies and *toward* the text, at more than double Meta's trained value (3.0).
-
-2. **The text prompt is functionally an empty caption, and MusicGen's prior for empty captions IS funk-pop stock music.** Training captions are stock-library metadata ("90s rock song with a guitar riff", genre/BPM/mood tags). A meta-instruction like *"continuation of the same song, identical instruments, identical timbre, same production and mixing, professional studio recording"* describes a *relationship to other audio*, which never appears in training captions — T5 embeds it as near-noise. The training corpus is overwhelmingly ShutterStock/Pond5 production-library music, so a vague caption regresses to generic Western stock instrumental. The per-pass section hints ("chorus, fuller arrangement, more energy") push the same direction.
-
-So the current code cranks a 7× amplifier on a caption that means "generic stock music." That is precisely "weird funk pop bullshit."
-
-**Also fundamental:** MusicGen **cannot continue vocals, ever.** Vocals were stripped from its training data twice (tag filtering, then HT-Demucs separation — stated verbatim in Meta's model card: "Vocals have been removed from the data source… The model is not able to generate realistic vocals"). The README's promise ("Vocals, instruments, lyrics — it picks up all of it") is not deliverable with MusicGen as the backbone.
-
----
-
-## 1. Is MusicGen capable of what we want?
-
-**Partially. Set expectations correctly:**
-
-| Goal | Achievable? |
-|---|---|
-| Continue tempo, key, groove, rough genre | **Yes** — this is what the autoregressive token prefix carries |
-| Same instrumentation, broadly ("a rock band stays a rock band") | **Mostly**, with correct settings (below) |
-| *Identical* timbre/production ("same recording, same take") | **No.** Hard ceiling: everything passes through EnCodec at 2.2 kbps (4 codebooks × 11 bits × 50 Hz), 32 kHz mono. Real guitar/drums come back with smeared cymbals, softened transients, and the "AI sheen" before the LM even contributes |
-| Continue vocals | **Never.** Vocal-free training data, by design |
-
-Continuation was never a trained or paper-evaluated task — it's an emergent property of the autoregressive LM that audiocraft exposes as `generate_continuation()`. Meta's own demos prompt with only **0.5–2 seconds** of audio. The paper's limitations section concedes: "Our simple generation method does not allow us to have fine-grained control over adherence of the generation to the conditioning."
-
-**Verdict:** with the fixes below, MusicGen-large can deliver "plausibly the same band keeps playing" for *instrumental* material. It cannot deliver "the same song with the same instruments" to a discerning ear, and it cannot touch vocals.
-
----
-
-## 2. How audio conditioning actually works (verified in transformers source)
-
-Trace through `MusicgenForConditionalGeneration.generate()` (modeling_musicgen.py):
-
-1. `input_values` (the waveform from the processor) → `_prepare_audio_encoder_kwargs_for_generation()` → `audio_encoder.encode()` → EnCodec RVQ codes → reshaped into `decoder_input_ids` (lines ~1744–1818). The audio prompt becomes a **frozen decoder token prefix** via `build_delay_pattern_mask`; generation only fills the empty slots after it.
-2. **The output of `generate()` includes the prompt**, re-decoded through EnCodec (lossy). There is no slicing of the prefix. The current CODA code already accounts for this correctly (crossfading inside the overlap region) — keep that.
-3. **CFG mechanics — the smoking gun.** `_prepare_text_encoder_kwargs_for_generation` (lines ~1732–1738): the unconditional branch is built by concatenating `torch.zeros_like(last_hidden_state)` — *text states only*. `prepare_inputs_for_generation` (lines ~1626–1631): `decoder_input_ids = decoder_input_ids.repeat((2, 1))` — *audio prompt copied into both branches*. `ClassifierFreeGuidanceLogitsProcessor`: `scores = uncond + (cond - uncond) * guidance_scale`. Since the audio prefix conditions both branches identically, **`guidance_scale` is purely a text knob. There is no knob in this implementation that increases audio-prompt fidelity.** Faithfulness to the audio comes from the prefix alone, and is *diluted* by strong text guidance.
-4. **Defaults from facebook/musicgen-large `generation_config.json`:** `guidance_scale: 3.0`, `max_length: 1500` (= 30.0 s at 50 tokens/s), `do_sample: true`.
-5. **Window math:** total sequence = prompt tokens + `max_new_tokens`. Nothing enforces the 1500-token (30 s) trained window when `max_new_tokens` is set — sinusoidal positional embeddings silently extrapolate with degraded output past it. Current CODA math (20 s prompt + 10 s new = exactly 1500) sits at the edge; correct, no headroom.
-6. **Resampling:** the EnCodec feature extractor does **no resampling**; it hard-errors if `sampling_rate != 32000` is passed (good — CODA passes it) and silently produces pitch-shifted garbage if omitted. CODA's librosa resample-to-32k + `sampling_rate=MUSICGEN_SR` is correct.
-7. **Shapes/padding:** mono 1-D float32 is the canonical input (a `(1, N)` array raises). `padding=True` with a single clip adds zero padding — safe. (Batching unequal-length prompts would inject silence tokens into the conditioning — avoid, but CODA doesn't batch.)
-8. **fp32:** correct and necessary. The precision-sensitive part is EnCodec encode/decode and the T5 conditioning; community/literature confirm fp16 there produces the degraded "bitcrushed" output — this was the 8-bit failure mode, and the current fp32 fix is right. (LM-only bf16 would be a safe future speed optimization; full-fp16 is not.)
-
----
-
-## 3. What's wrong with the current `continue_music.py` — specifically
-
-| # | Problem | Where | Severity |
-|---|---|---|---|
-| 1 | `guidance_scale=7.0` default — 2.3× Meta's trained value, amplifies text only, actively fights audio fidelity, and degrades audio quality (documented HF caveat) | `continue_track()` signature; `app.py` slider (min 3 / default 7 / max 10) | **Critical — primary cause of "funk pop"** |
-| 2 | Meta-instruction text prompt ("identical instruments, identical timbre…") is out-of-distribution → behaves as a vague caption → stock-music prior | `base` string in `continue_track()` | **Critical — the other half of the same bug** |
-| 3 | Per-pass section hints ("chorus, fuller arrangement, more energy", "big chorus, peak energy") are genre-generic captions injected at guidance 7 — each chained pass gets pulled further toward stock pop | `SECTION_ARC` / `_section_plan()` | **High** |
-| 4 | The "style adherence" slider label is inverted from reality: raising it makes output *more generic*, not more faithful | `app.py` | High (UX/diagnosis trap) |
-| 5 | 6 chained passes for 60 s (10 s new per pass) — each pass re-encodes generated audio and re-rolls the dice; drift compounds per pass. audiocraft's own extend loop uses `extend_stride=18` (12 s context, 18 s new) = ~3 passes for 60 s | `per_pass` math in `continue_track()` | Medium |
-| 6 | Vocal input goes straight into the prompt. MusicGen has never seen a voice; it will drop, garble, or replace it | `_load_tail()` / pipeline design | **Critical for any vocal demo** |
-| 7 | No timbre/EQ post-matching — generated 32 kHz-band-limited mono is spliced against a 44.1 kHz master with only an RMS gain match, so even a good continuation reads as "different record" | `stitch_with_crossfade()` | Medium |
-
-What's already **correct** (don't touch): fp32 + TF32, librosa resample to 32 kHz with `sampling_rate=` passed, mono 1-D float32 input, crossfade inside the codec-roundtripped overlap, equal-gain seam for correlated material, resampling generated audio *up* to the original's rate, window math 20 s + 10 s = 1500 tokens.
-
----
-
-## 4. The fix — exact changes
-
-### Fix 1 (do first): guidance + text — `continue_music.py`
-
-**Two supported modes; implement (a) as default, (b) as the option:**
-
-**(a) Pure continuation — no text, no CFG.** This is the canonical mode: Meta's MusicGen-Style page describes continuation as "given the conditioning, MusicGen continues it **without any textual description**", and audiocraft's `generate_continuation(descriptions=None)` is the reference implementation. Training used 20% condition dropout, so unconditional is in-distribution.
-
-```python
-# default path: audio prompt only
-inputs = processor(
-    audio=prompt_audio,
-    sampling_rate=MUSICGEN_SR,
-    return_tensors="pt",
-).to(model.device)
-# merge in null text conditioning so the seq2seq generate path is well-formed
-uncond = model.get_unconditional_inputs(num_samples=1)
-output = model.generate(
-    **inputs,
-    encoder_outputs=None,  # see note below
-    do_sample=True,
-    guidance_scale=1.0,    # CFG off — nothing for it to amplify anyway
-    temperature=1.0,
-    top_k=250,             # audiocraft defaults
-    max_new_tokens=max_new_tokens,
-)
-```
-(Implementation note: the clean way in transformers is `model.generate(input_values=inputs.input_values, padding_mask=inputs.padding_mask, **vars-from-get_unconditional_inputs-minus-duplicates, guidance_scale=1.0, ...)` — or simply keep passing `text=[""]` through the processor with `guidance_scale=1.0`, which is equivalent in effect since CFG is off. Verify both on a test clip; keep whichever is stable on the installed transformers version. **Pin transformers < 4.57** if you ever touch the melody variant — melody conditioning silently broke after 4.48, GitHub issue #45647.)
-
-**(b) Described continuation — user-supplied caption, guidance 3.0.** If the user types a real description ("garage rock, distorted electric guitar, live drums, male vocals removed, 120 bpm, E minor"), that caption is in-distribution and CFG at Meta's trained value 3.0 helps hold the genre. Auto-append detected key/BPM as now. **Never auto-generate meta-instructions.**
-
-- Change `continue_track()` default `guidance_scale=7.0` → `1.0`; treat >1 as only valid when a user caption exists.
-- Delete the `base` meta-instruction string.
-- **Delete `SECTION_ARC` and `_section_plan()`** (or reduce to a single final-pass "outro, song ending" hint *only* in described mode). The audio chaining carries continuity; the hints only inject stock-pop pull.
-
-### Fix 2: UI — `app.py`
-
-- Replace the "style adherence" slider (currently min 3, so even its minimum is text-amplifying) with:
-  - a free-text **"describe your song (optional)"** box → mode (b) when filled, mode (a) when empty;
-  - if a guidance slider is kept at all: range 1.0–5.0, default 1.0 (no text) / 3.0 (with text), labeled **"text influence"**.
-
-### Fix 3: vocals — Demucs gate (Demucs is already in requirements.txt)
-
-Before building the prompt: run HT-Demucs on the tail, measure vocal-stem energy. If vocals are present:
-1. Continue **the instrumental mix only** (this matches how the training data itself was prepared — HT-Demucs-separated instrumentals are exactly in-distribution).
-2. Keep the user's original (with vocals) untouched up to the seam; the continuation is instrumental.
-3. Update the README honestly: lyrics from Qwen3 are a *songwriting aid* deliverable, not synthesized vocals. (No open model on a ZeroGPU budget will clone-and-continue the user's voice well — YuE-extend is the closest and it's slow and finicky.)
-
-### Fix 4: chaining — match audiocraft's reference loop
-
-Keep first-pass prompt at 15–20 s (community sweet spot for fidelity). For subsequent passes use **12 s of context / 18 s new** (audiocraft's `extend_stride=18` default): 60 s of new audio in 3 passes instead of 6 — half the drift opportunities, half the GPU time. Keep total tokens ≤ 1500 per pass.
-
-### Fix 5: post-match the seam — matchering
-
-Add [`matchering`](https://github.com/sergree/matchering) (pure-Python, lightweight): REFERENCE = the original clip, TARGET = the generated continuation, before `stitch_with_crossfade()`. It matches RMS, spectral envelope, and peak — this is the single cheapest improvement to "sounds like the same record," and it's exactly what an audio engineer would do at a session splice: match the master, then crossfade on a musical boundary. (Optional polish: use the detected BPM to snap the seam to a downbeat.) Note it cannot invent content above 16 kHz — the 32 kHz EnCodec ceiling stands.
-
-### Expected outcome after Fixes 1–5
-
-Tempo/key/groove continuity, broadly matching instrumentation, no genre teleport, production glued by EQ-match. Still mono-derived, still slightly "AI-sheened," still instrumental-only. That is MusicGen's ceiling.
-
----
-
-## 5. If the ceiling isn't good enough: the 2026 alternatives
-
-Ranked for CODA's use case (faithful extension of arbitrary user audio, single ZeroGPU slice):
-
-1. **ACE-Step 1.5** (Jan 2026; Apache/MIT-style, 8–16 GB VRAM) — the only open model where "**extend** my actual audio, keep timbre" is a designed first-class feature (`extend`, `repaint`, `audio_cover_strength`), **with vocal support in 50+ languages**. Best single-model replacement candidate; chain repaints for arbitrary length. Caveat: limited independent benchmarking yet.
-2. **Stable Audio 3 Medium** (May 2026; 1.4B, ~6 GB, Stability Community License) — documented causal continuation/inpainting mode, 44.1 kHz **stereo** (fixes the mono+bandwidth ceiling). Unproven on vocals. Worth an A/B against ACE-Step on instrumental material.
-3. **YuE-extend** — true continuation with voice cloning from separated stems; best vocal continuity in open weights, but slow (minutes/song) and ≤30 s prompt practical limit.
-4. **MusicGen-Style** (facebook/musicgen-style) — conditions on a 1.5–4.5 s excerpt for timbre/style match; combining it with a continuation prefix is theoretically possible in audiocraft but undocumented/unvalidated. Research-grade only.
-5. **Per-stem MusicGen continuation: don't.** Isolated stems are out-of-distribution for MusicGen (literature: models "produce nonsensical outputs when fed isolated vocals" — SingSong); only stem-native models (MusicGen-Stem, StemGen) do this, and their weights are research releases.
-
-**License flag:** MusicGen weights are **CC-BY-NC** (non-commercial). Fine for the hackathon; a problem if CODA ever ships commercially. ACE-Step and Stable Audio 3 (under $1M revenue) are both more permissive.
-
-**Recommended path:** ship the hackathon on MusicGen with Fixes 1–5 (small, low-risk diffs), and prototype ACE-Step 1.5 `extend` as CODA v2's backbone — it is designed to do exactly what CODA promises, including vocals.
-
----
-
-## 6. Failure modes — explained
-
-| Symptom | Cause | Status |
-|---|---|---|
-| 8-bit / chiptune output | fp16 EnCodec/T5 path (precision-sensitive); confirmed pattern in community + literature (TinyMusician keeps EnCodec fp32 for this reason) | **Fixed** by the fp32 change — keep it |
-| Random new instruments | Text guidance pulling toward caption prior + per-pass re-rolls in 6-pass chaining | Fixes 1, 4 |
-| Generic MusicGen-default sound | Vague/meta caption → stock-library prior (training data literally is stock music) | Fixes 1, 2 |
-| "Weird funk pop" | guidance 7 × meaningless caption × "more energy" section hints = maximum pull toward the stock-pop prior | Fixes 1, 2 (delete SECTION_ARC) |
-| ~14 s output | Deployment issue, already fixed | — |
-| Vocals garbled/vanish | Vocal-free training data — model-level impossibility | Fix 3 (Demucs gate) |
-
----
-
-## 7. What a professional audio engineer would say
-
-A session engineer asked to "extend this demo" would: comp from the same takes, or re-amp/re-track matching the original chain, then **match the master** (EQ/loudness/width to the reference) and **edit on the grid** (splice at a downbeat, short crossfade). The transferable lessons for CODA: (1) never expect a different "performer" (the model) to nail the take — minimize how much it has to invent (longer audio context, no contradicting text); (2) the *master-matching* step is half of what makes a splice invisible — that's the matchering pass; (3) cut on musical boundaries — use the BPM grid CODA already detects to place the seam on a downbeat; (4) when a part can't be reproduced (vocals), you don't fake it — you arrange around it (instrumental continuation).

app.py

@@ -1,13 +1,13 @@
 """CODA — finish the song you quit on.
 
-Upload a short, unfinished music clip; CODA listens to it (key, tempo, meter),
-separates any vocals so it can hear the instrumental, and continues it with
-MusicGen into a longer, finished-sounding track in the same key, tempo and
-groove — then splices the continuation onto your original with a seamless,
+Upload a short, unfinished music clip. CODA listens to it (key, tempo, meter),
+then continues it into a longer, finished-sounding track in the same feel using
+Stable Audio 3 Small Music — a single native audio-continuation call, 44.1 kHz
+stereo — and splices the new part seamlessly onto your pristine original with a
 level-matched crossfade and a clean closing fade.
 
-Deliberately one job, done well. No lyrics generator, no cover-art printer —
-just a real, listenable continuation of your clip.
+Deliberately one job, done well. No lyrics generator, no cover-art printer — just
+a real, listenable continuation of your clip.
 """
 import os
 import tempfile
@@ -17,12 +17,13 @@ import librosa
 import numpy as np
 import soundfile as sf
 
+import engine
+import stitch
 from analyze import fingerprint
 from enhance import enhance_audio, enhance_to_tempfile, input_quality
 
 # ZeroGPU shim: on a Space `spaces` exists and `@spaces.GPU` attaches a GPU for
-# the duration of the call. Locally (or anywhere without it) we no-op so the
-# app still runs.
+# the duration of the call. Locally we no-op so the app still runs.
 try:
     import spaces
 except ImportError:
@@ -31,27 +32,23 @@ except ImportError:
             return fn if fn else (lambda f: f)
     spaces = _FakeSpaces()
 
-from continue_music import continue_track, stitch_with_crossfade, MUSICGEN_SR
-
-# the bundled demo: a low-quality phone capture of an unfinished song by the
-# band PUSHBACK (shared via TikTok). lo-fi in, finished-sounding out.
+# bundled demo: a low-quality phone capture of an unfinished song by the band
+# PUSHBACK (shared via TikTok). lo-fi in, finished-sounding out.
 PUSHBACK_DEMO = os.path.join(os.path.dirname(__file__),
                              "examples", "pushback_demo.mp3")
 PUSHBACK_CREDIT = ("Demo clip: **PUSHBACK** (via TikTok), used with thanks. "
                    "Bring your own clip to finish your own song.")
 
-# how much new audio the user can ask for. capped so the whole job — vocal
-# separation + a few MusicGen passes + stitch — lands comfortably inside the
-# 240s ZeroGPU window with margin for the first-call weight transfer.
-MIN_ADD, MAX_ADD, DEFAULT_ADD = 12, 40, 30
+# total finished length. SA3 Small generates up to 120 s in one call, so this is
+# a *total length* control (clip + continuation), not a "seconds to add" knob.
+MIN_TOTAL, MAX_TOTAL, DEFAULT_TOTAL = 30, 120, 60
 
-# On a Space, pull the model weights into CPU RAM at boot so the GPU window is
-# spent generating, not reading 6GB off disk. `spaces` defers the actual CUDA
-# placement until the first @spaces.GPU call.
+# On a Space, pull weights into CPU RAM at boot so the GPU window is spent
+# generating, not reading 3 GB off disk. `spaces` defers CUDA placement until
+# the first @spaces.GPU call.
 if os.environ.get("SPACE_ID"):
     try:
-        from continue_music import preload as _preload
-        _preload()
+        engine.preload()
     except Exception as _e:
         print(f"[coda] preload failed ({_e}); will lazy-load", flush=True)
 
@@ -59,30 +56,37 @@ if os.environ.get("SPACE_ID"):
 def _fmt_info(info, quality):
     """human-readable summary of what CODA heard."""
     lines = [
-        f"**Key** · {info['key']}",
-        f"**Tempo** · {info['bpm']} BPM",
-        f"**Meter** · {info['time_signature']}",
-        f"**Your clip** · {info['duration']}s",
+        f"**KEY**  `{info['key']}`",
+        f"**TEMPO**  `{info['bpm']} BPM`",
+        f"**METER**  `{info['time_signature']}`",
+        f"**CLIP**  `{info['duration']}s`",
     ]
     if quality and quality.get("lofi"):
         lines.append(
-            f"**Recording** · lo-fi (~{quality['bandwidth_hz']/1000:.0f}kHz "
-            f"bandwidth) — CODA cleans a copy before it listens, so it follows "
-            f"the *song*, not the hiss")
+            f"**SOURCE**  `lo-fi ~{quality['bandwidth_hz']/1000:.0f}kHz` "
+            f"— CODA cleans a copy before it listens, so it follows the *song*, "
+            f"not the hiss")
     return "  \n".join(lines)
 
 
 def analyze_on_upload(audio_path):
-    """Fast, CPU-only pass that runs the instant a clip is loaded, so the user
-    sees what CODA heard immediately instead of staring at a dead screen."""
+    """Fast CPU-only pass the instant a clip loads, so the user sees what CODA
+    heard immediately instead of a dead screen."""
     if not audio_path:
         return gr.update(value="", visible=False), gr.update(interactive=False)
     try:
-        # listen to a cleaned copy — analysis should track the music, not the
-        # recording's noise floor
         listen_path = enhance_to_tempfile(audio_path)
         info = fingerprint(listen_path)
         quality = input_quality(audio_path)
+        # SA3 continues up to a 120s total, so a clip needs headroom for at
+        # least MIN_NEW seconds of new audio. Block over-long clips here, with a
+        # clear message, instead of failing at generation time.
+        if info["duration"] > engine.MAX_SOURCE_SECONDS:
+            msg = (f"### Clip too long\nThat clip is **{info['duration']:.0f}s**. "
+                   f"CODA continues clips up to **{engine.MAX_SOURCE_SECONDS:.0f}s** "
+                   f"(Stable Audio 3's {engine.MAX_TOTAL_SECONDS:.0f}s total cap). "
+                   f"Trim it shorter and re-upload.")
+            return gr.update(value=msg, visible=True), gr.update(interactive=False)
         md = "### CODA heard\n" + _fmt_info(info, quality)
         return gr.update(value=md, visible=True), gr.update(interactive=True)
     except Exception as e:
@@ -92,61 +96,62 @@ def analyze_on_upload(audio_path):
 
 
 @spaces.GPU(duration=240)
-def finish_song(audio_path, add_seconds, remaster, progress=gr.Progress()):
-    """The whole job, inside one GPU window: listen → separate → continue →
-    stitch. `gr.Progress` streams stage updates to the UI so there's never a
-    dead screen. Returns (output_wav_path, summary_markdown)."""
+def finish_song(audio_path, total_seconds, vibe, remaster,
+                progress=gr.Progress()):
+    """The whole job inside one GPU window: listen -> continue (SA3) -> splice.
+    Returns (output_wav_path, summary_markdown)."""
     if not audio_path:
         raise gr.Error("Upload a clip (or load the PUSHBACK demo) first.")
 
-    add_seconds = int(add_seconds)
+    total_seconds = int(total_seconds)
     progress(0.05, desc="Listening to your clip…")
 
-    # analyze + build the MusicGen prompt feed from a cleaned copy
+    # analyze + build the conditioning feed from a cleaned copy
     listen_path = enhance_to_tempfile(audio_path)
     info = fingerprint(listen_path)
-    quality = input_quality(audio_path)
 
-    # the original, at its own sample rate and channel count — this is what the
-    # listener actually hears for the first stretch of the finished track
+    # the pristine original — what the listener hears for the first stretch
     original, sr = librosa.load(audio_path, sr=None, mono=False)
     if remaster:
         progress(0.12, desc="Remastering your part…")
         original = enhance_audio(original, sr)
 
-    # progress relay: continue_track calls this as it works
-    def _on_event(*event):
-        kind = event[0]
-        if kind == "separating":
-            progress(0.18, desc="Separating vocals from the music…")
-        elif kind == "pass":
-            _, i, n, _audio = event
-            frac = 0.25 + 0.6 * (i / max(n, 1))
-            progress(frac, desc=f"Composing the continuation… (pass {i} of {n})")
-
-    progress(0.18, desc="Separating vocals from the music…")
-    # continue on the *cleaned* feed (CODA follows the song, not the hiss), but
-    # splice back onto the user's real original
-    tail, prompt_samples, _msr = continue_track(
-        listen_path, gen_duration=add_seconds, progress=_on_event)
-
-    progress(0.9, desc="Splicing it onto your original…")
-    out = stitch_with_crossfade(original, tail, prompt_samples, sr)
+    # SA3 is a single call; map its stages onto the bar
+    def _on_stage(stage):
+        marks = {
+            "reading": (0.22, "Reading key, tempo & groove…"),
+            "composing": (0.45, "Composing the continuation…"),
+            "finalizing": (0.82, "Rendering 44.1 kHz stereo…"),
+        }
+        if stage in marks:
+            frac, desc = marks[stage]
+            progress(frac, desc=desc)
+
+    try:
+        new_tail, source_seconds, SR = engine.continue_audio(
+            listen_path, total_seconds=total_seconds,
+            prompt=(vibe or "").strip(), progress=_on_stage)
+    except ValueError as e:
+        # e.g. the clip is too long to continue under the 120s cap
+        raise gr.Error(str(e))
+
+    progress(0.9, desc="Splicing onto your original…")
+    out = stitch.stitch(original, sr, new_tail, source_seconds)
 
     out_path = os.path.join(tempfile.mkdtemp(), "coda_finished.wav")
-    sf.write(out_path, out.T if out.ndim == 2 else out, sr)
+    sf.write(out_path, out.T, SR, subtype="PCM_16")
 
     progress(1.0, desc="Done.")
-    total = out.shape[-1] / sr
+    total = out.shape[-1] / SR
+    added = total - source_seconds
+    vibe_note = f" guided by *“{vibe.strip()}”*" if (vibe or "").strip() else ""
     summary = (
         f"### Finished — {total:.0f}s\n"
-        f"Your **{info['duration']:.0f}s** clip in {info['key']} at "
-        f"{info['bpm']} BPM, continued for **~{add_seconds}s** more in the same "
-        f"key, tempo and feel, then crossfaded onto your original and faded out "
-        f"to a clean close.\n\n"
-        f"*The continuation is instrumental — MusicGen was trained on "
-        f"instrumental music, so CODA strips the vocals before it continues "
-        f"and lets your original vocals carry the front of the track.*"
+        f"Your **{source_seconds:.0f}s** clip in **{info['key']}** at "
+        f"**{info['bpm']} BPM** continued for **~{added:.0f}s** more{vibe_note}, "
+        f"then crossfaded onto your original and faded to a clean close.\n\n"
+        f"*Stable Audio 3 generated the continuation as 44.1 kHz stereo in a "
+        f"single pass; your original recording plays untouched up to the seam.*"
     )
     return out_path, summary
 
@@ -156,31 +161,85 @@ def load_demo():
     return PUSHBACK_DEMO
 
 
+# --- dark "DAW console" theme -------------------------------------------------
+THEME = gr.themes.Base(
+    primary_hue=gr.themes.colors.cyan,
+    secondary_hue=gr.themes.colors.orange,
+    neutral_hue=gr.themes.colors.slate,
+    font=[gr.themes.GoogleFont("Inter"), "ui-sans-serif", "system-ui"],
+    font_mono=[gr.themes.GoogleFont("JetBrains Mono"), "ui-monospace", "monospace"],
+).set(
+    body_background_fill="#0b0d10",
+    body_background_fill_dark="#0b0d10",
+    background_fill_primary="#14171c",
+    background_fill_secondary="#14171c",
+    block_background_fill="#14171c",
+    block_border_color="#222831",
+    block_label_background_fill="#14171c",
+    block_title_text_color="#9aa4b2",
+    body_text_color="#e6e9ef",
+    body_text_color_subdued="#9aa4b2",
+    button_primary_background_fill="#39d0d8",
+    button_primary_background_fill_hover="#4fe0e8",
+    button_primary_text_color="#06181a",
+    color_accent_soft="#1a2026",
+    border_color_accent="#39d0d8",
+    input_background_fill="#0e1115",
+    slider_color="#ffb347",
+)
+
 CSS = """
-#title { text-align:center; margin-bottom:0; }
-#tagline { text-align:center; color:var(--body-text-color-subdued); margin-top:0; }
-.coda-card { border:1px solid var(--border-color-primary); border-radius:12px;
-             padding:16px 18px; background:var(--block-background-fill); }
+:root { --coda-accent:#39d0d8; --coda-amber:#ffb347; }
+.gradio-container { max-width: 1060px !important; margin: 0 auto !important; }
+#coda-head { text-align:center; padding: 8px 0 2px; }
+#coda-title { font-weight:800; letter-spacing:.5px; font-size:2.5rem; margin:0;
+  background:linear-gradient(90deg,#39d0d8,#ffb347);
+  -webkit-background-clip:text; background-clip:text; -webkit-text-fill-color:transparent; }
+#coda-tagline { color:#9aa4b2; margin:.1rem 0 0; font-size:1.02rem; letter-spacing:.3px; }
+#coda-rule { height:2px; border:0; margin:10px auto 16px; max-width:240px;
+  background:linear-gradient(90deg,transparent,#39d0d8,#ffb347,transparent); opacity:.8; }
+#coda-eq { display:flex; gap:4px; justify-content:center; align-items:flex-end; height:26px; margin-top:8px; }
+#coda-eq span { width:5px; background:linear-gradient(180deg,#39d0d8,#1b6e72); border-radius:2px;
+  animation: codaeq 1.1s ease-in-out infinite; }
+#coda-eq span:nth-child(2){animation-delay:.15s} #coda-eq span:nth-child(3){animation-delay:.30s}
+#coda-eq span:nth-child(4){animation-delay:.45s} #coda-eq span:nth-child(5){animation-delay:.6s}
+#coda-eq span:nth-child(6){animation-delay:.3s} #coda-eq span:nth-child(7){animation-delay:.1s}
+@keyframes codaeq { 0%,100%{height:7px;opacity:.55} 50%{height:24px;opacity:1} }
+.coda-card { border:1px solid #222831; border-radius:14px; padding:16px 18px;
+  background:#14171c; box-shadow: inset 0 1px 0 #1c222b; }
+.coda-card h3 { color:var(--coda-accent); text-transform:uppercase; letter-spacing:1.5px;
+  font-size:.8rem; margin:.1rem 0 .7rem; }
+#coda-foot { text-align:center; color:#6b7480; font-size:.85rem; margin-top:14px; }
 """
 
+EQ_BARS = "<div id='coda-eq'>" + "".join("<span></span>" for _ in range(7)) + "</div>"
+
 with gr.Blocks(title="CODA") as app:
-    gr.Markdown("# 🎵 CODA", elem_id="title")
-    gr.Markdown("*the songs you quit on, finished.*", elem_id="tagline")
+    with gr.Column(elem_id="coda-head"):
+        gr.HTML("<h1 id='coda-title'>🎵 CODA</h1>"
+                "<p id='coda-tagline'>the songs you quit on, finished.</p>"
+                + EQ_BARS)
+    gr.HTML("<hr id='coda-rule'/>")
     gr.Markdown(
-        "Upload a short, unfinished music clip. CODA detects its key, tempo and "
-        "groove, then continues it into a longer, finished-sounding track in the "
-        "same feel — and splices the new part seamlessly onto your original."
-    )
+        "Upload a short, unfinished music clip. CODA reads its key, tempo and "
+        "groove, then **Stable Audio 3** continues it into a finished-sounding "
+        "track in the same feel — 44.1 kHz stereo, spliced seamlessly onto your "
+        "original.")
 
-    with gr.Row():
+    with gr.Row(equal_height=False):
         with gr.Column(scale=1):
             audio_input = gr.Audio(
                 label="Your unfinished clip", type="filepath", sources=["upload"])
             demo_btn = gr.Button("🎧 Try the demo — PUSHBACK (via TikTok)",
-                                  size="sm")
-            add_slider = gr.Slider(
-                MIN_ADD, MAX_ADD, value=DEFAULT_ADD, step=1,
-                label="Seconds to add")
+                                 size="sm")
+            total_slider = gr.Slider(
+                MIN_TOTAL, MAX_TOTAL, value=DEFAULT_TOTAL, step=1,
+                label="Finished length (seconds)",
+                info="Total length of the finished track. Longer = a bit slower.")
+            vibe = gr.Textbox(
+                label="Describe the vibe (optional)", lines=1,
+                placeholder="e.g. warm lo-fi, vinyl crackle, mellow piano",
+                info="Leave empty for pure audio-led continuation.")
             remaster = gr.Checkbox(
                 value=False, label="Remaster my part too",
                 info="Apply the same lo-fi cleanup to your original section so "
@@ -190,15 +249,18 @@ with gr.Blocks(title="CODA") as app:
 
         with gr.Column(scale=1):
             info_md = gr.Markdown(visible=False, elem_classes="coda-card")
-            output_audio = gr.Audio(label="Your finished song", type="filepath")
-            summary_md = gr.Markdown(visible=False)
-
-    gr.Markdown(PUSHBACK_CREDIT)
-
-    # analyze the moment a clip lands — instant feedback, no GPU
-    audio_input.change(
-        fn=analyze_on_upload, inputs=[audio_input],
-        outputs=[info_md, finish_btn])
+            # built visible inside the result group: Gradio drops visible=False
+            # audio players at build time, so we never toggle player visibility.
+            with gr.Group(elem_classes="coda-card"):
+                gr.Markdown("### Your finished song")
+                output_audio = gr.Audio(label="", type="filepath",
+                                        interactive=False)
+                summary_md = gr.Markdown(visible=False)
+
+    gr.Markdown(PUSHBACK_CREDIT, elem_id="coda-foot")
+
+    audio_input.change(fn=analyze_on_upload, inputs=[audio_input],
+                       outputs=[info_md, finish_btn])
     demo_btn.click(fn=load_demo, inputs=[], outputs=[audio_input])
 
     def _show_summary():
@@ -206,10 +268,12 @@ with gr.Blocks(title="CODA") as app:
 
     finish_btn.click(
         fn=finish_song,
-        inputs=[audio_input, add_slider, remaster],
+        inputs=[audio_input, total_slider, vibe, remaster],
         outputs=[output_audio, summary_md]).then(
         fn=_show_summary, inputs=[], outputs=[summary_md])
 
 
 if __name__ == "__main__":
-    app.queue().launch(theme=gr.themes.Soft(), css=CSS)
+    # Gradio 6 moved theme/css to launch(); pass them here (and they remain on
+    # Blocks above) so the dark DAW theme applies however the Space serves it.
+    app.queue().launch(theme=THEME, css=CSS)

continue_music.py

@@ -1,499 +0,0 @@
-import math
-
-import librosa
-import numpy as np
-import torch
-from transformers import AutoProcessor, MusicgenForConditionalGeneration
-
-
-# transformers-native MusicGen. the audiocraft package is abandoned and
-# hard-pins torch==2.1.0 / xformers<0.0.23, which breaks the HF Space build
-# against gradio 6.x. transformers supports audio-prompted continuation
-# directly, so we don't need audiocraft at all.
-
-# medium, not large: a/b rolls on the same prompts showed equal-or-denser
-# continuations from medium at half the latency and a third of the ram —
-# which on zerogpu means more passes inside the 240s window. (small is not
-# usable: it collapses to near-silence on dense lo-fi prompts.)
-MODEL_ID = "facebook/musicgen-medium"
-MUSICGEN_SR = 32000
-FRAME_RATE = 50  # musicgen decoder tokens per second
-# musicgen was trained on 30s windows; prompt + new audio per pass must fit.
-# this is a hard model limit — the audio prompt can never exceed ~30s.
-MAX_WINDOW_SECONDS = 30
-# audio context / new-audio split per pass, matching audiocraft's reference
-# extend loop (extend_stride=18): 12s of context + 18s new = exactly the
-# 1500-token trained window. fewer, longer passes = fewer EnCodec re-encodes
-# and re-rolls, so less drift across a long extension.
-CONTEXT_SECONDS = 12
-NEW_SECONDS_PER_PASS = 18
-# the FIRST pass listens to more of the user's clip — community sweet spot
-# for style fidelity is 15-20s — and generates correspondingly less, so the
-# window stays at the trained 30s. later passes re-prompt on model audio,
-# where 12s of context is enough to hold the groove.
-DEFAULT_PROMPT_SECONDS = 20
-# each generated chunk must stay near the prompt's level. unconditional
-# continuation drifts — some rolls decay toward silence, some blow up — and
-# chained passes compound whatever they inherit. the guard rescales a chunk
-# whose rms ratio leaves this band back to the boundary, preserving musical
-# dynamics inside it.
-ENERGY_BAND = (0.7, 1.4)
-# a chunk this far below the prompt level is a failed roll (near-silence /
-# wisps), not a quiet section — regenerate it once rather than amplify mush
-COLLAPSE_RATIO = 0.30
-MAX_RETRIES_PER_TRACK = 2
-# the single biggest quality lever. musicgen was trained on commercial-loudness
-# audio; prompt it with a quiet lo-fi clip (rms ~0.06) and it loses the thread
-# and drifts toward silence within a few seconds — the "ghost noise / wisps"
-# failure. RMS-normalizing every prompt to a confident level before the model
-# sees it keeps the continuation sustained and full (verified: a 16s roll went
-# from tail/head energy 0.28 to 0.63 with this alone). NOT peak normalization —
-# that hands the model loud transients over a quiet body and it collapses even
-# harder (tail/head 0.12). the generated audio comes back at this level too and
-# is matched back down to the original's level at the final stitch.
-PROMPT_TARGET_RMS = 0.12
-# guidance_scale in transformers' musicgen CFG amplifies the TEXT condition
-# only — the audio-prompt tokens are copied into both CFG branches and cancel
-# out of the formula. with no caption there is nothing for it to amplify, so
-# pure continuation runs with CFG off (1.0). when the user supplies a real
-# caption we use meta's trained value.
-GUIDANCE_NO_TEXT = 1.0
-GUIDANCE_WITH_TEXT = 3.0
-# vocal stem rms / mix rms above this = the clip has real vocals
-VOCAL_RMS_THRESHOLD = 0.1
-
-_model = None
-_processor = None
-_demucs = None
-
-
-def _load_model():
-    global _model, _processor
-    if _model is None:
-        _processor = AutoProcessor.from_pretrained(MODEL_ID)
-        device = "cuda" if torch.cuda.is_available() else "cpu"
-        # fp32, NOT fp16: musicgen's text encoder is T5, which overflows in
-        # fp16 (garbage conditioning), and EnCodec audio tokenization audibly
-        # degrades in half precision — together they made the model ignore the
-        # clip and emit generic synth output. audiocraft's reference impl also
-        # keeps EnCodec in fp32. TF32 matmuls recover most of the speed on
-        # ampere+ GPUs without the precision cliff.
-        if device == "cuda":
-            torch.backends.cuda.matmul.allow_tf32 = True
-            torch.backends.cudnn.allow_tf32 = True
-        _model = MusicgenForConditionalGeneration.from_pretrained(
-            MODEL_ID, torch_dtype=torch.float32
-        ).to(device)
-        _model.eval()
-    return _model, _processor
-
-
-def _load_demucs():
-    global _demucs
-    if _demucs is None:
-        from demucs.pretrained import get_model
-        _demucs = get_model("htdemucs")
-        _demucs.eval()
-    return _demucs
-
-
-def preload():
-    """load musicgen + demucs at process start. on zerogpu the per-call gpu
-    window is the scarce resource — weights must come off disk at boot, not
-    inside the window. spaces patches .to('cuda') so placement is deferred
-    until a @spaces.GPU call actually attaches a gpu."""
-    _load_model()
-    _load_demucs()
-    print("[coda] preload: musicgen + demucs resident", flush=True)
-
-
-def _load_tail(path, prompt_duration):
-    """load audio, return mono 32kHz numpy tail of `prompt_duration` seconds."""
-    # librosa (soundfile backend) instead of torchaudio.load — torchaudio 2.9+
-    # delegates decoding to torchcodec, which isn't installed on the Space.
-    track, _ = librosa.load(path, sr=MUSICGEN_SR, mono=True)
-
-    tail_samples = int(prompt_duration * MUSICGEN_SR)
-    if track.shape[0] > tail_samples:
-        track = track[-tail_samples:]
-
-    return track.astype(np.float32)
-
-
-def _vocal_gate(path, prompt_duration):
-    """
-    musicgen's training data had vocals stripped (twice — tag filtering, then
-    HT-Demucs separation), so a vocal prompt is out-of-distribution: the model
-    drops, garbles, or replaces the voice. this gate runs HT-Demucs on the
-    tail and, if it carries real vocal energy, returns the INSTRUMENTAL tail
-    (the sum of the non-vocal stems — matching how the training data was
-    prepared, and dropping the noisy residual demucs can't attribute) as
-    mono float32 @32kHz. returns None when the clip is already instrumental
-    or demucs is unavailable, meaning: use the plain tail.
-    """
-    try:
-        from demucs.apply import apply_model
-    except Exception as e:
-        print(f"[coda] demucs unavailable ({e}); skipping vocal gate", flush=True)
-        return None
-
-    try:
-        demucs = _load_demucs()
-        sep_sr = demucs.samplerate
-
-        wav, _ = librosa.load(path, sr=sep_sr, mono=False)
-        if wav.ndim == 1:
-            wav = np.stack([wav, wav])
-        tail = wav[:, -int(prompt_duration * sep_sr):].astype(np.float32)
-
-        device = "cuda" if torch.cuda.is_available() else "cpu"
-        mix = torch.from_numpy(np.ascontiguousarray(tail))
-        # demucs expects the mix standardized (same as its own separate.py)
-        ref = mix.mean(0)
-        std = float(ref.std()) + 1e-8
-        with torch.no_grad():
-            sources = apply_model(
-                demucs.to(device), ((mix - ref.mean()) / std)[None].to(device),
-                device=device, split=True, overlap=0.25, progress=False,
-            )[0]
-        sources = sources.cpu() * std + ref.mean()
-        vocals = sources[demucs.sources.index("vocals")].numpy()
-
-        vocal_rms = float(np.sqrt(np.mean(vocals ** 2)))
-        mix_rms = float(np.sqrt(np.mean(tail ** 2)) + 1e-9)
-        ratio = vocal_rms / mix_rms
-        if ratio < VOCAL_RMS_THRESHOLD:
-            print(f"[coda] vocal gate: instrumental clip "
-                  f"(vocal/mix rms {ratio:.3f}), using original tail", flush=True)
-            return None
-
-        print(f"[coda] vocal gate: vocals detected (vocal/mix rms {ratio:.3f}) "
-              f"— prompting with the instrumental mix", flush=True)
-        # sum of the non-vocal stems, NOT mix-minus-vocals: demucs stems
-        # don't sum exactly to the mix, and the residual is everything it
-        # couldn't attribute to an instrument — tape hiss, crackle, phasey
-        # vocal ghosts. mix-minus keeps all of that in the prompt and the
-        # model continues the noise; the stem sum is the band, clean.
-        inst = np.stack([
-            sources[demucs.sources.index(s)].numpy()
-            for s in demucs.sources if s != "vocals"
-        ]).sum(axis=0).mean(axis=0)
-        inst = librosa.resample(inst, orig_sr=sep_sr, target_sr=MUSICGEN_SR,
-                                res_type="soxr_hq")
-        return inst.astype(np.float32)
-    except Exception as e:
-        print(f"[coda] vocal gate failed ({e}); using original tail", flush=True)
-        return None
-
-
-def _generate_pass(model, processor, prompt_audio, desc, new_seconds,
-                   guidance_scale):
-    """
-    one musicgen pass conditioned on `prompt_audio` (mono float32 @32kHz).
-    returns the full decoded output: a re-encoded copy of the prompt followed
-    by ~`new_seconds` of new material, 1-D float32 @32kHz.
-
-    the prompt is RMS-normalized to PROMPT_TARGET_RMS first — a quiet prompt is
-    what makes musicgen drift to silence, so every pass gets a confident-level
-    prompt regardless of where the source or the previous pass sat.
-    """
-    prompt_audio = _normalize_rms(prompt_audio, PROMPT_TARGET_RMS)
-    inputs = processor(
-        audio=prompt_audio,
-        sampling_rate=MUSICGEN_SR,
-        text=[desc],
-        padding=True,
-        return_tensors="pt",
-    ).to(model.device)
-
-    max_new_tokens = int(new_seconds * FRAME_RATE)
-    prompt_secs = len(prompt_audio) / MUSICGEN_SR
-    print(f"[coda] generate(): max_new_tokens={max_new_tokens} "
-          f"({new_seconds:.1f}s @ {FRAME_RATE} tok/s), "
-          f"guidance_scale={guidance_scale}, audio_prompt={prompt_secs:.1f}s, "
-          f"text={desc!r}", flush=True)
-
-    with torch.no_grad():
-        output = model.generate(
-            **inputs,
-            do_sample=True,
-            guidance_scale=guidance_scale,
-            max_new_tokens=max_new_tokens,
-        )
-
-    audio = output[0, 0].float().cpu().numpy()
-    print(f"[coda] generate() returned {audio.shape[0]} samples "
-          f"({audio.shape[0] / MUSICGEN_SR:.1f}s incl. re-encoded prompt)",
-          flush=True)
-    return audio
-
-
-def _rms(x):
-    return float(np.sqrt(np.mean(np.asarray(x, dtype=np.float64) ** 2)))
-
-
-def _normalize_rms(x, target, max_gain=12.0, peak_ceiling=0.97):
-    """scale `x` to `target` rms, capping the gain (so we don't blow up a
-    near-silent buffer into noise) and the resulting peak (so transients don't
-    clip the encoder). returns float32."""
-    x = np.asarray(x, dtype=np.float32)
-    cur = _rms(x)
-    if cur < 1e-6:
-        return x
-    gain = min(target / cur, max_gain)
-    out = x * gain
-    peak = float(np.abs(out).max())
-    if peak > peak_ceiling:
-        out = out * (peak_ceiling / peak)
-    return out.astype(np.float32)
-
-
-def _energy_guard(out, prompt_samples, anchor_rms=None):
-    """
-    bound the generated region's level relative to the level of the USER'S
-    clip (`anchor_rms`), not the level of whatever the previous pass left.
-    unconditional musicgen rolls drift — some decay toward silence, some blow
-    up past full scale — and an anchor that re-bases every pass would let
-    that drift compound (0.7 of 0.7 of 0.7 across a chain). a chunk whose
-    rms leaves ENERGY_BAND is rescaled to the boundary (gain capped at 3x so
-    a failed roll doesn't become amplified mush), with a short ramp so the
-    correction never lands as a step. only the NEW region is touched: the
-    re-encoded prompt region must stay honest — the stitch stage rms-matches
-    against it. returns (out, raw_ratio).
-    """
-    prompt_rms = anchor_rms or _rms(out[:prompt_samples])
-    new = out[prompt_samples:]
-    if prompt_rms < 1e-6 or len(new) == 0:
-        return out, 1.0
-    ratio = _rms(new) / prompt_rms
-    lo, hi = ENERGY_BAND
-    gain = 1.0
-    if ratio < lo:
-        gain = min(lo / max(ratio, 1e-6), 3.0)
-    elif ratio > hi:
-        gain = hi / ratio
-    if gain != 1.0:
-        ramp_n = min(int(0.5 * MUSICGEN_SR), len(new))
-        g = np.full(len(new), gain, dtype=np.float32)
-        g[:ramp_n] = np.linspace(1.0, gain, ramp_n, dtype=np.float32)
-        out = np.concatenate([out[:prompt_samples],
-                              new * g]).astype(np.float32)
-        print(f"[coda] energy guard: gen/prompt rms {ratio:.2f} -> "
-              f"rescaled x{gain:.2f}", flush=True)
-    return out, ratio
-
-
-def _aligned_xfade(a_tail, b_head):
-    """
-    blend two time-aligned versions of the SAME content with an equal-gain
-    (linear) curve. equal-power curves are for uncorrelated material — on
-    correlated signals they swell up to +3dB mid-fade, which is exactly the
-    audible volume bump/dip at the seam. for aligned content, gains summing
-    to 1 keep the level dead flat through the blend.
-    """
-    n = min(len(a_tail), len(b_head))
-    g = np.linspace(0.0, 1.0, n, dtype=np.float32)
-    return a_tail[:n] * (1.0 - g) + b_head[:n] * g
-
-
-def _merge_aligned(prev, new_out, prompt_samples, fade_samples):
-    """
-    join `prev` with a generation pass output whose first `prompt_samples`
-    are a re-encode of prev's last `prompt_samples` (time-aligned).
-    crossfades INSIDE that overlap region so the fade completes exactly where
-    the newly generated material begins — the handoff into new content then
-    happens entirely within model audio and is seamless.
-    """
-    prompt_samples = min(prompt_samples, len(prev), len(new_out))
-    fade = min(fade_samples, prompt_samples)
-    if fade <= 0:
-        return np.concatenate([prev, new_out[prompt_samples:]]).astype(np.float32)
-
-    seam = _aligned_xfade(prev[-fade:], new_out[prompt_samples - fade:prompt_samples])
-    return np.concatenate([prev[:-fade], seam, new_out[prompt_samples:]]).astype(np.float32)
-
-
-def continue_track(path, prompt_duration=DEFAULT_PROMPT_SECONDS, gen_duration=60,
-                   key=None, bpm=None, fade_seconds=6.0, caption="",
-                   guidance_scale=None, progress=None):
-    """
-    generates ~`gen_duration` seconds of new audio continuing the input track,
-    chaining multiple musicgen passes when more than one 30s window is needed
-    (each pass is re-prompted with the last CONTEXT_SECONDS of the accumulated
-    output, so timbre carries through the whole extension).
-
-    two modes:
-      - caption empty (default): pure audio-conditioned continuation, no text,
-        CFG off (guidance 1.0). this is the canonical continuation mode —
-        audiocraft's generate_continuation(descriptions=None).
-      - caption given: the user's own description (in-distribution for the
-        text encoder), guidance 3.0 (meta's trained value), with detected
-        key/bpm appended.
-
-    returns (extended_tail, prompt_samples, MUSICGEN_SR) where extended_tail
-    is 1-D float32 @32kHz whose first `prompt_samples` samples are a
-    re-encoded, time-aligned copy of the original's last `prompt_duration`
-    seconds — the caller crossfades the original into that region.
-    """
-    # `progress`, when given, receives ("separating",) before the vocal gate
-    # and ("pass", i, n_passes, audio_so_far) after each generation pass —
-    # purely observational, used by the ui to paint the waveform live.
-    def _notify(*event):
-        if progress is not None:
-            try:
-                progress(*event)
-            except Exception as e:
-                print(f"[coda] progress callback failed ({e})", flush=True)
-
-    model, processor = _load_model()
-
-    tail = _load_tail(path, prompt_duration)
-    # vocal prompts are out-of-distribution for musicgen — swap in the
-    # demucs-separated instrumental when the tail carries vocals
-    _notify("separating")
-    instrumental = _vocal_gate(path, prompt_duration)
-    if instrumental is not None:
-        tail = instrumental
-    prompt_samples = tail.shape[0]
-    prompt_secs = prompt_samples / MUSICGEN_SR
-
-    caption = (caption or "").strip()
-    if caption:
-        desc = caption
-        if key and bpm:
-            desc += f", in {key} at {round(bpm)} bpm"
-        elif key:
-            desc += f", in {key}"
-        guidance = guidance_scale if guidance_scale else GUIDANCE_WITH_TEXT
-    else:
-        # no text condition at all — with guidance 1.0, CFG is off and the
-        # empty caption's encoder states carry no stock-music pull. the audio
-        # prefix alone steers the generation.
-        desc = ""
-        guidance = guidance_scale if guidance_scale else GUIDANCE_NO_TEXT
-
-    # window-safe pass plan. every pass must fit musicgen's trained 30s
-    # window: PROMPT + NEW <= 30s, where the first prompt is long (up to 20s
-    # of the user's clip — fidelity comes from context) and later passes
-    # re-prompt on 12s of model audio and generate 18s. exceeding the window
-    # makes the sinusoidal positions extrapolate and the output degrades
-    # audibly (verified: a 20s+18s pass came back clipping with tempo drift).
-    ctx_samples = int(CONTEXT_SECONDS * MUSICGEN_SR)
-    fade = int(fade_seconds * MUSICGEN_SR)
-
-    first_new = max(1.0, min(NEW_SECONDS_PER_PASS, gen_duration,
-                             MAX_WINDOW_SECONDS - prompt_secs))
-    # mirrors the loop below, including the dropped sub-3s remainder, so the
-    # "pass i of n" the ui shows is the count that actually happens
-    n_passes = 1 + max(0, math.ceil(
-        (gen_duration - first_new - 3.0) / NEW_SECONDS_PER_PASS))
-
-    print(f"[coda] continuation plan: ~{gen_duration:.0f}s of new audio in "
-          f"{n_passes} pass(es) (first: {prompt_secs:.1f}s prompt + "
-          f"{first_new:.1f}s new, then {CONTEXT_SECONDS}s ctx + "
-          f"{NEW_SECONDS_PER_PASS}s new), guidance {guidance} "
-          f"({'caption' if caption else 'pure audio'} mode)", flush=True)
-
-    acc = None
-    remaining = float(gen_duration)
-    retries_left = MAX_RETRIES_PER_TRACK
-    # every generated chunk is held against the level the model is prompted at
-    # (PROMPT_TARGET_RMS), not the previous pass — so drift can't compound and
-    # the guard's band is measured against the same level the model sees.
-    anchor_rms = PROMPT_TARGET_RMS
-    i = 0
-    # a sub-3s remainder isn't worth a model call (~8s of overhead for 2s
-    # of audio nobody will miss next to the closing fade) — drop it
-    while remaining > 3.0 or acc is None:
-        prompt = tail if acc is None else acc[-ctx_samples:]
-        p_secs = len(prompt) / MUSICGEN_SR
-        p_samples = len(prompt)
-        new_secs = max(1.0, min(NEW_SECONDS_PER_PASS, remaining,
-                                MAX_WINDOW_SECONDS - p_secs))
-        out = _generate_pass(model, processor, prompt, desc, new_secs,
-                             guidance)
-        out, ratio = _energy_guard(out, p_samples, anchor_rms)
-        if ratio < COLLAPSE_RATIO and retries_left > 0:
-            # a failed roll (near-silence, wisps) — re-roll the pass once
-            # instead of amplifying mush. the prompt is unchanged; sampling
-            # gives a fresh trajectory.
-            retries_left -= 1
-            print(f"[coda] pass collapsed (gen/prompt rms {ratio:.2f}) — "
-                  f"re-rolling ({retries_left} retries left)", flush=True)
-            continue
-        i += 1
-        if acc is None:
-            acc = out
-        else:
-            acc = _merge_aligned(acc, out, p_samples, fade)
-        remaining -= new_secs
-        _notify("pass", i, n_passes, acc)
-
-    return acc, prompt_samples, MUSICGEN_SR
-
-
-def stitch_with_crossfade(original, extended_tail, prompt_samples_gen, original_sr,
-                          fade_seconds=6.0, end_fade_seconds=4.0):
-    """
-    splice the generated continuation onto the original at the original's
-    native sample rate and channel count, and close the track with a fade-out
-    so it ends like a finished song instead of cutting mid-phrase.
-
-    original:          float32, 1-D (mono) or 2-D (channels, samples) @original_sr
-    extended_tail:     1-D float32 @32kHz from continue_track(); its first
-                       `prompt_samples_gen` samples mirror the end of `original`
-    returns the full track, same shape convention as `original`.
-    """
-    # resample the generated audio UP to the original's rate before stitching —
-    # never resample the original down.
-    if original_sr != MUSICGEN_SR:
-        extended_tail = librosa.resample(
-            extended_tail, orig_sr=MUSICGEN_SR, target_sr=original_sr,
-            res_type="soxr_hq",
-        )
-    prompt_samples = int(round(prompt_samples_gen * original_sr / MUSICGEN_SR))
-    prompt_samples = min(prompt_samples, original.shape[-1], extended_tail.shape[0])
-
-    # loudness-match the generation to the original over the shared prompt
-    # region so the crossfade doesn't pump
-    orig_tail = original[..., -prompt_samples:]
-    if orig_tail.ndim == 2:
-        orig_tail = orig_tail.mean(axis=0)
-    ref_rms = float(np.sqrt(np.mean(orig_tail ** 2)) + 1e-9)
-    gen_rms = float(np.sqrt(np.mean(extended_tail[:prompt_samples] ** 2)) + 1e-9)
-    extended_tail = extended_tail * float(np.clip(ref_rms / gen_rms, 0.5, 2.0))
-
-    # match channel layout (musicgen is mono; duplicate across channels)
-    if original.ndim == 2:
-        extended_tail = np.tile(extended_tail, (original.shape[0], 1))
-
-    fade = min(int(fade_seconds * original_sr), prompt_samples)
-    if fade <= 0:
-        out = np.concatenate(
-            [original, extended_tail[..., prompt_samples:]], axis=-1)
-    else:
-        # the blend ends exactly where the new material begins: original hands
-        # off over the last `fade` samples to the time-aligned re-encoded
-        # prompt, so the entry into generated content happens entirely inside
-        # model audio. equal-GAIN (linear) curve, not equal-power: the two
-        # signals are aligned copies of the same content, and equal-power on
-        # correlated material swells +3dB mid-fade — an audible seam artifact.
-        g = np.linspace(0.0, 1.0, fade, dtype=np.float32)
-        seam = (original[..., -fade:] * (1.0 - g)
-                + extended_tail[..., prompt_samples - fade:prompt_samples] * g)
-        out = np.concatenate(
-            [original[..., :-fade], seam, extended_tail[..., prompt_samples:]],
-            axis=-1)
-
-    out = out.astype(np.float32)
-
-    # smooth fade to silence at the very end so the song closes cleanly
-    end_fade = min(int(end_fade_seconds * original_sr), out.shape[-1])
-    if end_fade > 0:
-        curve = np.cos(np.linspace(0.0, np.pi / 2, end_fade, dtype=np.float32)) ** 2
-        out[..., -end_fade:] *= curve
-
-    peak = np.abs(out).max()
-    if peak > 1.0:
-        out = out / peak
-    return out

engine.py

@@ -0,0 +1,213 @@
+"""engine.py — Stable Audio 3 Small Music continuation core.
+
+CODA's job is one thing done well: take a short, unfinished clip and continue it
+into a finished-sounding track in the same key, tempo and feel. SA3 does that in
+a SINGLE call. Its `generate_diffusion_cond_inpaint` is a native audio-inpainting
+diffusion sampler: place the user's clip at the front of the buffer, mask the
+region after it, and the model fills the masked region conditioned on the kept
+audio — true long-form continuation, 44.1 kHz stereo, no multi-pass chaining,
+no energy guards, no re-roll logic.
+
+This module is the whole generation core. It returns ONLY the newly generated
+tail (the model's [source_end, total] region) plus the source length in seconds;
+`stitch.py` joins that tail onto the user's *pristine* original so the real
+recording (and any vocals) plays untouched up to the seam.
+
+Mask convention (verified against the installed library source):
+  inpaint_mask = ones(buffer); inpaint_mask[start:end] = 0
+  -> 1 = keep the input audio, 0 = generate. So masking [L_src, L_total] keeps
+  the source in [0, L_src] and generates everything after it.
+"""
+import numpy as np
+import torch
+
+MODEL_ID = "stabilityai/stable-audio-3-small-music"
+
+SR = 44100               # SA3 native sample rate (model_config: sample_rate)
+STEPS = 8                # SA3 Small is an 8-step adversarially-distilled model
+SAMPLER = "pingpong"     # the sampler the distilled model was tuned for
+DEFAULT_CFG = 1.0        # distilled-model guidance; the prompt still conditions
+                         # at 1.0 (CFG amplification off, conditional path on)
+MAX_TOTAL_SECONDS = 120  # SA3 Small duration cap (sample_size / sample_rate)
+MIN_NEW_SECONDS = 5      # below this a "continuation" isn't worth a GPU call
+
+_model = None
+_model_config = None
+_sample_size = None
+_on_device = None        # which device the weights currently live on
+
+
+def _device():
+    return "cuda" if torch.cuda.is_available() else "cpu"
+
+
+def preload():
+    """Load model + autoencoder + T5Gemma conditioner into CPU RAM at process
+    start. On ZeroGPU the per-call GPU window is the scarce resource, so weights
+    must come off disk at boot, not inside the window. The CUDA placement + fp16
+    cast is deferred to the first `continue_audio` call (i.e. the @spaces.GPU
+    window), matching how Stability's own Space defers it."""
+    global _model, _model_config, _sample_size
+    if _model is None:
+        from stable_audio_tools import get_pretrained_model
+        _model, _model_config = get_pretrained_model(MODEL_ID)
+        _sample_size = int(_model_config["sample_size"])
+        _model.eval()
+        print(f"[coda] preload: SA3 resident "
+              f"(sr={_model_config['sample_rate']}, "
+              f"sample_size={_sample_size} = "
+              f"{_sample_size / int(_model_config['sample_rate']):.0f}s)",
+              flush=True)
+    return _model, _model_config
+
+
+def _ensure_on_device():
+    """Ensure weights are on the GPU in fp16. Called inside the @spaces.GPU
+    window on every generation. `.to()` is a cheap no-op when the model is
+    already placed, so we re-ensure each call rather than caching device state —
+    that stays correct even if ZeroGPU detaches the GPU between calls. fp16 is
+    only valid on CUDA; on CPU the model stays fp32."""
+    global _model, _on_device
+    dev = _device()
+    _model = _model.to(dev)
+    if dev == "cuda":
+        _model = _model.to(torch.float16)
+    _on_device = dev
+    return _model
+
+
+def _load_source(clip_path):
+    """Load the clip as stereo float32 @44.1k as a (2, N) tensor. SA3's
+    autoencoder is stereo; `prepare_audio` inside the sampler will pad/crop to
+    the buffer length and place this at the FRONT (PadCrop, randomize=False)."""
+    import librosa
+    y, _ = librosa.load(clip_path, sr=SR, mono=False)
+    y = np.asarray(y, dtype=np.float32)
+    if y.ndim == 1:
+        y = np.stack([y, y])           # mono -> stereo
+    elif y.shape[0] > 2:
+        y = y[:2]
+    return torch.from_numpy(np.ascontiguousarray(y))
+
+
+#: longest clip that still leaves room for MIN_NEW of continuation under the cap
+MAX_SOURCE_SECONDS = MAX_TOTAL_SECONDS - MIN_NEW_SECONDS
+
+
+def plan_continuation(source_seconds, total_seconds):
+    """Pure helper (unit-testable, no model): clamp the request to SA3's limits
+    and return (total_seconds, new_seconds, mask_start, mask_end).
+
+    - the mask runs from where the source ends to the total length: that masked
+      region is what SA3 generates, so mask_end MUST exceed mask_start.
+    - total is capped at MAX_TOTAL_SECONDS and floored so at least
+      MIN_NEW_SECONDS of new audio is generated.
+    - raises ValueError when the source is already so long there's no room to
+      continue under the cap (otherwise the mask would invert and SA3 would
+      silently generate nothing).
+    """
+    source_seconds = float(source_seconds)
+    total_seconds = float(total_seconds)
+    if source_seconds > MAX_SOURCE_SECONDS:
+        raise ValueError(
+            f"clip is {source_seconds:.0f}s — too long to continue under SA3's "
+            f"{MAX_TOTAL_SECONDS:.0f}s cap (need room for at least "
+            f"{MIN_NEW_SECONDS:.0f}s of new audio); trim it under "
+            f"{MAX_SOURCE_SECONDS:.0f}s.")
+    # source <= MAX_SOURCE_SECONDS, so source + MIN_NEW <= MAX_TOTAL: the floor
+    # never pushes total past the cap, and mask_end (total) > mask_start (source).
+    total_seconds = min(total_seconds, MAX_TOTAL_SECONDS)
+    total_seconds = max(total_seconds, source_seconds + MIN_NEW_SECONDS)
+    new_seconds = total_seconds - source_seconds
+    return total_seconds, new_seconds, source_seconds, total_seconds
+
+
+def continue_audio(clip_path, total_seconds, prompt="", cfg_scale=DEFAULT_CFG,
+                   seed=-1, progress=None):
+    """Continue `clip_path` up to `total_seconds` in one SA3 inpaint call.
+
+    Returns (new_tail, source_seconds, SR) where:
+      new_tail       : (2, M) float32 @44.1k — ONLY the generated region
+                       [source_end, total]. Peak-normalized to <= 1.0.
+      source_seconds : the clip's true length (the splice boundary, in seconds)
+      SR             : 44100
+
+    `progress(stage_name)` is called (best-effort) at each stage so the UI can
+    paint a live status. SA3 is one diffusion call, so progress is stage-based.
+    """
+    from einops import rearrange
+    from stable_audio_tools.inference.generation import (
+        generate_diffusion_cond_inpaint)
+
+    def _notify(stage):
+        if progress is not None:
+            try:
+                progress(stage)
+            except Exception as e:
+                print(f"[coda] progress callback failed ({e})", flush=True)
+
+    preload()
+    model = _ensure_on_device()
+    dev = _device()
+
+    # The library does `np.random.randint(0, 2**32-1)` when seed == -1, which
+    # overflows int32 on Windows/numpy<2. Draw a safe seed ourselves so the
+    # default path works everywhere, not just on the Linux Space.
+    if seed is None or seed < 0:
+        seed = int(np.random.randint(0, 2 ** 31 - 1))
+
+    _notify("reading")
+    source = _load_source(clip_path)
+    source_seconds = source.shape[-1] / SR
+    # the autoencoder runs in the model's dtype (fp16 on CUDA); the conditioning
+    # audio must match it or the encoder's conv1d rejects the input dtype.
+    model_dtype = next(model.model.parameters()).dtype
+    source = source.to(model_dtype)
+
+    total_seconds, new_seconds, mask_start, mask_end = plan_continuation(
+        source_seconds, total_seconds)
+    prompt = (prompt or "").strip()
+
+    print(f"[coda] continuation: source={source_seconds:.1f}s -> "
+          f"total={total_seconds:.1f}s (+{new_seconds:.1f}s new), "
+          f"mask=[{mask_start:.1f}s, {mask_end:.1f}s], steps={STEPS}, "
+          f"cfg={cfg_scale}, prompt={prompt!r}", flush=True)
+
+    _notify("composing")
+    with torch.no_grad():
+        output = generate_diffusion_cond_inpaint(
+            model,
+            steps=STEPS,
+            cfg_scale=cfg_scale,
+            conditioning=[{"prompt": prompt, "seconds_total": total_seconds}],
+            sample_size=_sample_size,
+            sampler_type=SAMPLER,
+            inpaint_audio=(SR, source),
+            inpaint_mask_start_seconds=mask_start,
+            inpaint_mask_end_seconds=mask_end,
+            seed=seed,
+            device=dev,
+        )
+
+    _notify("finalizing")
+    # (b, d, n) -> (d, b*n); peak-normalize like Stability's reference Space
+    output = rearrange(output, "b d n -> d (b n)")
+    audio = output.to(torch.float32).cpu().numpy()
+    peak = float(np.abs(audio).max())
+    if peak > 1e-9:
+        audio = audio / peak
+
+    if audio.shape[0] == 1:            # safety: ensure stereo
+        audio = np.repeat(audio, 2, axis=0)
+
+    boundary = int(round(source_seconds * SR))
+    end = int(round(total_seconds * SR))
+    end = min(end, audio.shape[-1])
+    new_tail = audio[:, boundary:end]
+    new_tail = np.ascontiguousarray(new_tail.astype(np.float32))
+
+    print(f"[coda] generated tail: shape={new_tail.shape} "
+          f"({new_tail.shape[-1] / SR:.1f}s), peak after norm "
+          f"{float(np.abs(new_tail).max()):.3f}, "
+          f"rms {float(np.sqrt(np.mean(new_tail ** 2))):.3f}", flush=True)
+    return new_tail, source_seconds, SR

requirements.txt

@@ -1,14 +1,29 @@
-torch>=2.4.0
-torchaudio>=2.4.0
-# pinned to the locally GPU-verified version: the musicgen audio-prompt
-# path has silently regressed across 4.x minors before (melody broke after
-# 4.48), so the space must build exactly what was tested
-transformers==4.57.6
-accelerate>=0.26.0
-sentencepiece
+# CODA runs Stable Audio 3 Small Music through the stable-audio-tools library.
+# This dependency set mirrors Stability's own ZeroGPU Space (the proven-green
+# build for this model) and is pinned to the exact torch that was verified
+# end-to-end locally: torch 2.7.1 on the cu128 wheel index, which carries kernels
+# for both the dev GPU (Blackwell sm_120) and ZeroGPU's H200 (sm_90).
+#
+# gradio is provided by the Space SDK (see README front-matter), so it is NOT
+# pinned here. Demucs is intentionally absent: CODA splices the user's pristine
+# original (vocals and all) up to the seam, so no source separation is needed.
+--extra-index-url https://download.pytorch.org/whl/cu128
+torch==2.7.1
+torchaudio==2.7.1
+
+# The SA3 inference library. 0.0.20 (upstream main) is the first version with the
+# SA3 architecture + native inpainting; PyPI only publishes up to 0.0.19, so this
+# installs from the repo. It pulls its own pinned tree (vector-quantize-pytorch,
+# v-diffusion-pytorch, alias-free-torch, torchsde, nnAudio, einops, …).
+stable-audio-tools @ git+https://github.com/Stability-AI/stable-audio-tools.git
+
+# stable-audio-tools imports pytorch_lightning (its LoRA callbacks) without
+# declaring it; the official SA3 Space lists it explicitly, so CODA does too.
+pytorch_lightning
+
+# CODA's own DSP + ZeroGPU glue
 librosa>=0.10.2
-numpy>=1.24.0,<2.0
-scipy>=1.10.0
 soundfile>=0.12.1
-demucs>=4.0.1
+scipy>=1.10.0
+numpy<2
 spaces

stitch.py

@@ -0,0 +1,93 @@
+"""stitch.py — splice the SA3 continuation onto the user's pristine original.
+
+CODA's identity: your real recording plays untouched up to the seam, then the
+generated tail takes over. Everything here is 44.1 kHz stereo — SA3's native
+format and the deliverable's — so the original is resampled up to 44.1k and made
+stereo, and the engine's tail is already there.
+
+Unlike the old MusicGen path, the SA3 tail does NOT contain a re-encoded copy of
+the source; it is fresh audio that begins exactly where the source ends. The seam
+is therefore a join between sequential content, so:
+  - level: the tail is loudness-matched to the original's tail RMS so the seam
+    doesn't pump (gain bounded so a quiet lo-fi clip can't crush the tail);
+  - click: a short equal-power crossfade smooths the join;
+  - close: a cos^2 fade to true silence ends the track like a finished song;
+  - then one peak-normalize lifts the whole (now level-consistent) track to a
+    confident listening level with -1 dBFS of headroom.
+"""
+import librosa
+import numpy as np
+
+SR = 44100
+
+
+def to_stereo_44k(audio, sr):
+    """(channels, N) or (N,) @sr  ->  (2, N') float32 @44.1k stereo."""
+    a = np.asarray(audio, dtype=np.float32)
+    if a.ndim == 1:
+        a = a[None, :]
+    if sr != SR:
+        a = np.stack([
+            librosa.resample(ch, orig_sr=sr, target_sr=SR, res_type="soxr_hq")
+            for ch in a
+        ])
+    if a.shape[0] == 1:
+        a = np.repeat(a, 2, axis=0)
+    elif a.shape[0] > 2:
+        a = a[:2]
+    return np.ascontiguousarray(a.astype(np.float32))
+
+
+def _rms(x):
+    return float(np.sqrt(np.mean(np.asarray(x, dtype=np.float64) ** 2)) + 1e-12)
+
+
+def stitch(original, original_sr, new_tail, source_seconds,
+           crossfade_seconds=0.10, end_fade_seconds=4.0, match_seconds=2.0,
+           peak_ceiling=0.891):
+    """Join the user's original to the SA3-generated tail.
+
+    original       : (channels, N) or (N,) float32 @original_sr — pristine clip
+    new_tail       : (2, M) float32 @44.1k from engine.continue_audio
+    source_seconds : the splice boundary (clip length) in seconds
+    returns        : (2, T) float32 @44.1k, peak == peak_ceiling (-1 dBFS)
+    """
+    orig = to_stereo_44k(original, original_sr)
+    tail = to_stereo_44k(new_tail, SR)
+
+    boundary = min(int(round(source_seconds * SR)), orig.shape[-1])
+    orig = orig[:, :boundary]          # only the real recording up to the seam
+
+    # loudness-match the tail to the original's level at the seam (continuity).
+    # bound the gain: a very quiet lo-fi clip shouldn't drag the full-bodied
+    # tail down to a whisper, and we never amplify the tail wildly either.
+    m = min(int(match_seconds * SR), orig.shape[-1], tail.shape[-1])
+    if m > 0:
+        gain = float(np.clip(_rms(orig[:, -m:]) / _rms(tail[:, :m]), 0.4, 2.5))
+        tail = tail * gain
+
+    # short equal-power crossfade across the join. the two sides are sequential
+    # (not time-aligned copies), so equal-power — not equal-gain — keeps the
+    # energy flat through the blend.
+    fade = min(int(crossfade_seconds * SR), orig.shape[-1], tail.shape[-1])
+    if fade > 0:
+        t = np.linspace(0.0, 1.0, fade, dtype=np.float32)
+        fout, fin = np.cos(t * np.pi / 2), np.sin(t * np.pi / 2)
+        seam = orig[:, -fade:] * fout + tail[:, :fade] * fin
+        out = np.concatenate([orig[:, :-fade], seam, tail[:, fade:]], axis=-1)
+    else:
+        out = np.concatenate([orig, tail], axis=-1)
+    out = out.astype(np.float32)
+
+    # closing fade to true silence so the song ends instead of cutting off
+    end_fade = min(int(end_fade_seconds * SR), out.shape[-1])
+    if end_fade > 0:
+        curve = np.cos(np.linspace(0.0, np.pi / 2, end_fade,
+                                   dtype=np.float32)) ** 2
+        out[:, -end_fade:] *= curve
+
+    # lift the whole, now level-consistent, track to a confident level
+    peak = float(np.abs(out).max())
+    if peak > 1e-9:
+        out = out * (peak_ceiling / peak)
+    return out.astype(np.float32)

test_app_logic.py

@@ -1,68 +1,24 @@
-"""offline test of the app's wiring: instant on-upload analysis, demo loading,
-and the full finish_song pipeline with the model stubbed (no GPU, no weights).
-verifies the real DSP (analyze, enhance, stitch) runs end-to-end on the bundled
-PUSHBACK demo and produces a valid, level-matched output file."""
+"""Tests for app.py wiring: on-upload analysis, demo loading, and the full
+finish_song pipeline with the SA3 engine stubbed (no GPU, no weights). Verifies
+the real DSP (analyze, enhance, stitch) runs end-to-end on the bundled demo and
+produces a valid 44.1 kHz stereo file. Skips if gradio isn't installed."""
 import os
-import sys
 
 import numpy as np
+import pytest
 import soundfile as sf
 
-FAILURES = []
-
-
-def check(name, cond, detail=""):
-    print(f"[{'PASS' if cond else 'FAIL'}] {name} {detail}")
-    if not cond:
-        FAILURES.append(name)
-
-
-import app
-from continue_music import MUSICGEN_SR
+pytest.importorskip("gradio")
+import app   # noqa: E402
+import engine  # noqa: E402
 
 DEMO = app.PUSHBACK_DEMO
-check("bundled PUSHBACK demo exists", os.path.exists(DEMO), DEMO)
-
-# ---- 1. load_demo just hands back the demo path ----
-check("load_demo returns the demo clip", app.load_demo() == DEMO)
-
-# ---- 2. on-upload analysis: instant, CPU-only, enables the button ----
-info_update, btn_update = app.analyze_on_upload(DEMO)
-md = info_update["value"]
-check("analysis reports a key", "Key" in md and "·" in md, md[:60])
-check("analysis reports tempo", "BPM" in md)
-check("analysis makes the panel visible", info_update["visible"] is True)
-check("analysis enables Finish button", btn_update["interactive"] is True)
-
-# empty input keeps the button disabled
-empty_info, empty_btn = app.analyze_on_upload(None)
-check("no clip -> button stays disabled", empty_btn["interactive"] is False)
-
-# ---- 3. finish_song pipeline with the model stubbed ----
-# replace the heavy continuation with a fast fake that mimics its contract:
-# returns (tail, prompt_samples, sr) where tail[:prompt_samples] mirrors the
-# end of the (cleaned) input so the stitch can crossfade into it.
-import librosa
-
-
-def fake_continue_track(path, gen_duration=30, progress=None):
-    if progress:
-        progress("separating")
-        progress("pass", 1, 1, np.zeros(10))
-    src, _ = librosa.load(path, sr=MUSICGEN_SR, mono=True)
-    prompt_samples = min(len(src), 20 * MUSICGEN_SR)
-    prompt = src[-prompt_samples:]
-    new = 0.1 * np.sin(2 * np.pi * 220 *
-                       np.arange(int(gen_duration * MUSICGEN_SR)) / MUSICGEN_SR)
-    return (np.concatenate([prompt, new]).astype(np.float32),
-            prompt_samples, MUSICGEN_SR)
-
-
-app.continue_track = fake_continue_track
+_HAVE_DEMO = os.path.exists(DEMO)
+need_demo = pytest.mark.skipif(not _HAVE_DEMO, reason="bundled demo clip absent")
 
 
 class _Prog:
-    """stand-in for gr.Progress — just records the stages it's told about."""
+    """stand-in for gr.Progress — records the (frac, desc) stages it's told."""
     def __init__(self):
         self.calls = []
 
@@ -70,28 +26,74 @@ class _Prog:
         self.calls.append((frac, desc))
 
 
-prog = _Prog()
-out_path, summary = app.finish_song(DEMO, 20, False, progress=prog)
-
-check("finish_song writes an output file", os.path.exists(out_path), out_path)
-y, sr = sf.read(out_path)
-dur = len(y) / sr
-check("output is longer than the original (continuation added)",
-      dur > 30.0, f"dur={dur:.1f}s")
-check("output never clips", float(np.abs(y).max()) <= 1.0,
-      f"peak={float(np.abs(y).max()):.3f}")
-check("output isn't silent", float(np.sqrt(np.mean(y ** 2))) > 1e-3)
-check("summary names the key/tempo", "BPM" in summary and "continued" in summary)
-check("progress streamed multiple stages", len(prog.calls) >= 4,
-      f"stages={[c[1] for c in prog.calls]}")
-check("progress ends at 100%", prog.calls[-1][0] == 1.0)
-
-# ---- 4. remaster path runs the cleanup on the original too ----
-out_r, _ = app.finish_song(DEMO, 15, True, progress=_Prog())
-check("remaster path produces a valid file", os.path.exists(out_r))
-
-print()
-if FAILURES:
-    print(f"{len(FAILURES)} FAILURES: {FAILURES}")
-    sys.exit(1)
-print("all checks passed")
+@need_demo
+def test_load_demo_returns_clip():
+    assert app.load_demo() == DEMO
+    assert os.path.exists(DEMO)
+
+
+@need_demo
+def test_analyze_on_upload_reports_and_enables():
+    info_update, btn_update = app.analyze_on_upload(DEMO)
+    md = info_update["value"]
+    assert "KEY" in md and "TEMPO" in md and "BPM" in md
+    assert info_update["visible"] is True
+    assert btn_update["interactive"] is True
+
+
+def test_analyze_on_upload_empty_disables_button():
+    _, btn_update = app.analyze_on_upload(None)
+    assert btn_update["interactive"] is False
+
+
+@need_demo
+def test_finish_song_pipeline_with_stubbed_engine(monkeypatch):
+    """stub engine.continue_audio with a fast synthetic tail; the rest of the
+    pipeline (enhance, analyze, stitch, write) runs for real."""
+    def fake_continue_audio(clip_path, total_seconds, prompt="", progress=None,
+                            **kw):
+        if progress:
+            progress("reading")
+            progress("composing")
+            progress("finalizing")
+        new_secs = total_seconds - 29.53          # demo is ~29.53s
+        n = int(max(new_secs, 5) * engine.SR)
+        t = np.arange(n) / engine.SR
+        wave = 0.2 * np.sin(2 * np.pi * 220 * t).astype(np.float32)
+        tail = np.stack([wave, wave])
+        return tail, 29.53, engine.SR
+
+    monkeypatch.setattr(engine, "continue_audio", fake_continue_audio)
+
+    prog = _Prog()
+    out_path, summary = app.finish_song(DEMO, 60, "", False, progress=prog)
+
+    assert os.path.exists(out_path)
+    y, sr = sf.read(out_path)
+    assert sr == 44100
+    assert y.ndim == 2 and y.shape[1] == 2          # 44.1k stereo
+    assert len(y) / sr > 50                          # ~60s finished
+    assert float(np.abs(y).max()) <= 1.0
+    assert float(np.sqrt(np.mean(y ** 2))) > 1e-3    # not silent
+    assert "BPM" in summary and "Stable Audio 3" in summary
+    # progress streamed several stages and ended at 100%
+    assert len(prog.calls) >= 4
+    assert prog.calls[-1][0] == 1.0
+
+
+@need_demo
+def test_finish_song_remaster_path(monkeypatch):
+    def fake_continue_audio(clip_path, total_seconds, prompt="", progress=None,
+                            **kw):
+        n = int(15 * engine.SR)
+        wave = 0.2 * np.sin(2 * np.pi * 220 * np.arange(n) / engine.SR)
+        return np.stack([wave, wave]).astype(np.float32), 29.53, engine.SR
+
+    monkeypatch.setattr(engine, "continue_audio", fake_continue_audio)
+    out_path, _ = app.finish_song(DEMO, 45, "", True, progress=_Prog())
+    assert os.path.exists(out_path)
+
+
+def test_finish_song_rejects_empty_input():
+    with pytest.raises(Exception):
+        app.finish_song(None, 60, "", False, progress=_Prog())

test_engine_logic.py

@@ -0,0 +1,69 @@
+"""Unit tests for engine.py's pure continuation planning — the source-length ->
+mask-bounds + total-length-cap math. No model, no GPU: `plan_continuation` is a
+pure function, so these run anywhere torch+numpy import."""
+import pytest
+
+import engine
+
+
+def test_normal_request_maps_to_tail_mask():
+    total, new, mstart, mend = engine.plan_continuation(30, 60)
+    assert total == 60
+    assert new == 30
+    # the mask runs from where the source ends to the total length
+    assert mstart == 30
+    assert mend == 60
+
+
+def test_total_capped_at_120():
+    total, new, mstart, mend = engine.plan_continuation(30, 200)
+    assert total == engine.MAX_TOTAL_SECONDS == 120
+    assert new == 90
+    assert mstart == 30 and mend == 120
+
+
+def test_min_new_floor_enforced():
+    # asking for barely-longer-than-source still generates at least MIN_NEW
+    total, new, mstart, mend = engine.plan_continuation(30, 31)
+    assert new == engine.MIN_NEW_SECONDS == 5
+    assert total == 35
+    assert mstart == 30 and mend == 35
+
+
+def test_mask_always_brackets_the_new_region():
+    for src, req in [(15, 40), (29.5, 60), (50, 90), (10, 120)]:
+        total, new, mstart, mend = engine.plan_continuation(src, req)
+        assert mstart == src                       # mask starts at the seam
+        assert mend == total                       # …and runs to the end
+        assert abs((mend - mstart) - new) < 1e-6   # masked span == new audio
+        assert total <= engine.MAX_TOTAL_SECONDS
+
+
+def test_source_at_max_keeps_min_new():
+    # the longest allowed clip still gets exactly MIN_NEW of continuation
+    total, new, mstart, mend = engine.plan_continuation(engine.MAX_SOURCE_SECONDS, 130)
+    assert total == engine.MAX_TOTAL_SECONDS == 120
+    assert new == engine.MIN_NEW_SECONDS == 5
+    assert mend > mstart                              # mask never inverts
+
+
+def test_overlong_source_raises_not_inverts():
+    # the old bug: source >= cap produced an inverted mask and a silent
+    # no-op continuation. now it must raise instead.
+    for src in (116, 120, 125, 200):
+        with pytest.raises(ValueError):
+            engine.plan_continuation(src, 60)
+
+
+def test_no_plan_ever_inverts_the_mask():
+    for src in [1, 15, 29.5, 60, 90, 110, 115]:
+        total, new, mstart, mend = engine.plan_continuation(src, 60)
+        assert mend > mstart        # mask_end strictly after mask_start
+        assert new >= engine.MIN_NEW_SECONDS - 1e-6
+
+
+def test_constants_match_sa3_contract():
+    assert engine.SR == 44100
+    assert engine.STEPS == 8
+    assert engine.SAMPLER == "pingpong"
+    assert engine.MAX_TOTAL_SECONDS == 120

test_stitch_logic.py

@@ -1,273 +1,106 @@
-"""offline test of continuation chaining + stitching math (no torch needed).
-stubs the model layer; verifies lengths, seam continuity, channels, rms,
-guidance/caption modes, vocal-gate + mastering fallbacks, and the closing
-fade."""
-import sys
-import types
+"""Unit tests for stitch.py — the stereo-native splice/crossfade math. No model,
+no GPU: stitch is pure librosa+numpy. Covers channel/rate normalization, seam
+length, original preservation, loudness match, closing fade and the peak guard."""
 import numpy as np
+import pytest
 
-# stub torch/transformers so continue_music imports without the heavy deps
-torch_stub = types.ModuleType("torch")
-torch_stub.float16 = "float16"
-torch_stub.float32 = "float32"
-torch_stub.no_grad = lambda: types.SimpleNamespace(__enter__=lambda s: None, __exit__=lambda s, *a: False)
-torch_stub.cuda = types.SimpleNamespace(is_available=lambda: False)
-torch_stub.Tensor = type("Tensor", (), {})  # scipy array-api probes this
-torch_stub.backends = types.SimpleNamespace(
-    cuda=types.SimpleNamespace(matmul=types.SimpleNamespace(allow_tf32=False)),
-    cudnn=types.SimpleNamespace(allow_tf32=False),
-)
-sys.modules["torch"] = torch_stub
-tf_stub = types.ModuleType("transformers")
-tf_stub.AutoProcessor = object
-tf_stub.MusicgenForConditionalGeneration = object
-sys.modules["transformers"] = tf_stub
+import stitch
 
-import continue_music as cm
+SR = stitch.SR
 
-SR = cm.MUSICGEN_SR
-CTX = cm.CONTEXT_SECONDS
-FAILURES = []
 
-
-def check(name, cond, detail=""):
-    status = "PASS" if cond else "FAIL"
-    print(f"[{status}] {name} {detail}")
-    if not cond:
-        FAILURES.append(name)
-
-
-def tone(freq, seconds, sr, phase=0.0):
+def tone(freq, seconds, sr=SR, amp=0.3, phase=0.0, channels=2):
     t = np.arange(int(seconds * sr)) / sr
-    return (0.3 * np.sin(2 * np.pi * freq * t + phase)).astype(np.float32)
-
-
-# ---- 1. chaining: 60s request = 20s first prompt + window-safe passes ----
-passes = []
-descs = []
-guidances = []
-prompts = []
-
-def fake_generate_pass(model, processor, prompt_audio, desc, new_seconds, guidance_scale):
-    passes.append(new_seconds)
-    descs.append(desc)
-    guidances.append(guidance_scale)
-    prompts.append(prompt_audio.copy())
-    # model output = re-encoded prompt + new material
-    new = tone(220, new_seconds, SR)
-    return np.concatenate([prompt_audio * 0.95, new])
-
-cm._load_model = lambda: (None, None)
-cm._generate_pass = fake_generate_pass
-cm._load_tail = lambda path, d: tone(220, min(d, 35), SR)
-
-ext, prompt_samples, gen_sr = cm.continue_track(
-    "fake.wav", gen_duration=60, key="D major", bpm=115.2)
-new_secs = (ext.shape[0] - prompt_samples) / SR
-# 20s first prompt caps pass 1 at 10s new (30s window); then 18s strides:
-# 10 + 18 + 18 + 14 = 60
-check("4 window-safe passes", len(passes) == 4, f"passes={passes}")
-check("first pass: 20s prompt + 10s new",
-      abs(passes[0] - 10) < 0.01 and prompts[0].shape[0] == 20 * SR,
-      f"passes={passes} prompt0={prompts[0].shape[0] / SR}s")
-check("every pass fits the 30s window",
-      all(p.shape[0] / SR + n <= 30.01 for p, n in zip(prompts, passes)),
-      f"{[(p.shape[0] / SR, n) for p, n in zip(prompts, passes)]}")
-check("~60s of new audio", 57.0 <= new_secs <= 62.0, f"new={new_secs:.1f}s")
-check("prompt_samples = 20s @32k",
-      prompt_samples == cm.DEFAULT_PROMPT_SECONDS * SR)
-check("later-pass context is 12s",
-      all(p.shape[0] == CTX * SR for p in prompts[1:]),
-      f"{[p.shape[0] / SR for p in prompts]}")
-check("pure mode: guidance 1.0 (CFG off)", all(g == 1.0 for g in guidances),
-      f"{guidances}")
-check("pure mode: no text prompt at all", all(d == "" for d in descs),
-      f"{descs!r}")
-
-# ---- 2. described mode: user caption -> guidance 3.0, key/bpm appended ----
-passes.clear(); descs.clear(); guidances.clear(); prompts.clear()
-cm.continue_track("fake.wav", gen_duration=18, key="D major", bpm=115.2,
-                  caption="garage rock, distorted electric guitar, live drums")
-check("caption mode: guidance 3.0", all(g == 3.0 for g in guidances),
-      f"{guidances}")
-check("caption used verbatim",
-      all(d.startswith("garage rock, distorted electric guitar") for d in descs),
-      f"{descs!r}")
-check("key/bpm appended in caption mode",
-      all("D major" in d and "115 bpm" in d for d in descs))
-check("no meta-instruction injected",
-      all("identical instruments" not in d and "chorus" not in d for d in descs))
-
-# ---- 3. short + long requests stay window-safe, remainders drop ----
-passes.clear(); descs.clear(); guidances.clear(); prompts.clear()
-cm.continue_track("fake.wav", gen_duration=15)
-check("15s request = 10s + 5s passes", passes == [10.0, 5.0],
-      f"passes={passes}")
-passes.clear()
-cm.continue_track("fake.wav", gen_duration=120)
-total = sum(passes)
-# 10 + 6x18 = 118; the 2s remainder is not worth a model call
-check("120s request = 7 passes, sub-3s remainder dropped",
-      len(passes) == 7, f"passes={passes}")
-check("120s request totals ~118s", 116.0 <= total <= 122.0, f"total={total:.1f}")
-check("long-request passes still fit window",
-      all(p + CTX <= 30.01 for p in passes[1:]))
-
-# ---- 4. vocal gate: graceful fallback + instrumental substitution ----
-# demucs isn't installed in this env: the real gate must fall back to None
-check("vocal gate falls back without demucs",
-      cm._vocal_gate("fake.wav", CTX) is None)
-# when the gate returns an instrumental, it becomes the first-pass prompt
-passes.clear(); prompts.clear()
-marker = tone(330, CTX, SR)
-orig_gate = cm._vocal_gate
-cm._vocal_gate = lambda path, d: marker
-ext_v, ps_v, _ = cm.continue_track("fake.wav", gen_duration=18)
-cm._vocal_gate = orig_gate
-check("instrumental tail used as prompt when vocals detected",
-      np.array_equal(prompts[0], marker))
-check("prompt_samples follows instrumental length", ps_v == marker.shape[0])
-
-# ---- 5. prompt RMS normalization: the anti-decay lever ----
-# the single biggest quality fix — a quiet prompt makes musicgen drift to
-# silence, so every prompt is scaled to PROMPT_TARGET_RMS before the model.
-quiet = tone(220, 4, SR) * 0.2           # quiet, like a lo-fi clip (rms ~0.04)
-normed = cm._normalize_rms(quiet, cm.PROMPT_TARGET_RMS)
-check("normalize: quiet prompt lifted to target rms",
-      abs(cm._rms(normed) / cm.PROMPT_TARGET_RMS - 1) < 0.02,
-      f"rms_out={cm._rms(normed):.3f} target={cm.PROMPT_TARGET_RMS}")
-check("normalize: gain capped so silence isn't blown into noise",
-      cm._rms(cm._normalize_rms(tone(220, 4, SR) * 1e-5, cm.PROMPT_TARGET_RMS))
-      < cm.PROMPT_TARGET_RMS,
-      "near-silent buffer hits the 12x gain cap, not the target")
-loud = tone(220, 4, SR) * 1.5
-check("normalize: peak ceiling prevents encoder clipping",
-      float(np.abs(cm._normalize_rms(loud, cm.PROMPT_TARGET_RMS)).max()) <= 0.971)
-check("normalize: silent buffer passes through untouched",
-      np.array_equal(cm._normalize_rms(np.zeros(1000, np.float32),
-                                       cm.PROMPT_TARGET_RMS),
-                     np.zeros(1000, np.float32)))
-
-# ---- 6. stitching at native 44.1kHz stereo ----
-orig = np.stack([tone(220, 35, 44100), tone(220, 35, 44100, phase=0.1)])
-full = cm.stitch_with_crossfade(orig, ext, prompt_samples, 44100,
-                                fade_seconds=3.0, end_fade_seconds=4.0)
-
-check("output stereo", full.ndim == 2 and full.shape[0] == 2, f"shape={full.shape}")
-expected_len = orig.shape[-1] + int(round((ext.shape[0] - prompt_samples) * 44100 / SR))
-check("output length = original + upsampled new content",
-      abs(full.shape[-1] - expected_len) <= 2,
-      f"got {full.shape[-1]}, expected ~{expected_len}")
-check("original preserved before fade",
-      np.allclose(full[:, :orig.shape[-1] - 3 * 44100], orig[:, :-3 * 44100], atol=1e-6))
-check("no clipping", np.abs(full).max() <= 1.0, f"peak={np.abs(full).max():.3f}")
-
-# seam continuity: no sample-to-sample jump bigger than the waveform itself allows
-seam_region = full[0, orig.shape[-1] - 3 * 44100 - 100: orig.shape[-1] + 44100]
-max_jump = np.abs(np.diff(seam_region)).max()
-ref_jump = np.abs(np.diff(full[0, :44100])).max()
-check("no click at seam", max_jump < ref_jump * 1.5,
-      f"max_jump={max_jump:.4f} vs ref={ref_jump:.4f}")
-
-# level stays flat through the blend (equal-gain on correlated content —
-# equal-power would swell ~+3dB at the midpoint here)
-mid = orig.shape[-1] - int(1.5 * 44100)  # middle of the 3s blend
-mid_rms = np.sqrt(np.mean(full[0, mid - 11025: mid + 11025] ** 2))
-pre_rms = np.sqrt(np.mean(full[0, mid - 6 * 44100: mid - 5 * 44100] ** 2))
-check("no volume swell mid-blend", abs(mid_rms / pre_rms - 1) < 0.1,
-      f"mid={mid_rms:.4f} pre={pre_rms:.4f} ratio={mid_rms / pre_rms:.3f}")
-
-# closing fade: track ends at silence
-check("ends at silence", np.abs(full[:, -100:]).max() < 1e-3,
-      f"end peak={np.abs(full[:, -100:]).max():.5f}")
-check("fade region is monotone-ish quieter",
-      np.abs(full[0, -4410:]).max() < np.abs(full[0, -4 * 44100:-3 * 44100]).max())
-
-# ---- 7. rms matching: quiet generation gets boosted toward original level ----
-quiet_ext = ext * 0.6
-full_q = cm.stitch_with_crossfade(orig, quiet_ext, prompt_samples, 44100,
-                                  fade_seconds=3.0, end_fade_seconds=0.0)
-tail_rms = np.sqrt(np.mean(full_q[:, -44100 * 5:] ** 2))
-orig_rms = np.sqrt(np.mean(orig[:, -44100 * 5:] ** 2))
-check("rms matched within 25%", abs(tail_rms / orig_rms - 1) < 0.25,
-      f"tail={tail_rms:.3f} orig={orig_rms:.3f}")
-
-# ---- 8. mono original passes through as 1-D ----
-full_m = cm.stitch_with_crossfade(orig[0], ext, prompt_samples, 44100, fade_seconds=3.0)
-check("mono stays 1-D", full_m.ndim == 1)
-
-# ---- 9. progress callback: fires per pass, never breaks generation ----
-events = []
-cm.continue_track("fake.wav", gen_duration=36,
-                  progress=lambda *ev: events.append(ev))
-kinds = [e[0] for e in events]
-check("progress: separating fires first", kinds[0] == "separating", f"{kinds}")
-# 36s = 10 + 18 + 8
-check("progress: one event per pass", kinds.count("pass") == 3, f"{kinds}")
-check("progress: pass carries (i, n, audio)",
-      events[1][1] == 1 and events[1][2] == 3 and hasattr(events[1][3], "shape"))
-check("progress: audio grows between passes",
-      events[2][3].shape[0] > events[1][3].shape[0])
-# a broken callback must not kill the generation
-ext_cb, _, _ = cm.continue_track(
-    "fake.wav", gen_duration=18,
-    progress=lambda *ev: (_ for _ in ()).throw(ValueError("boom")))
-check("progress: callback exceptions are swallowed", ext_cb is not None)
-
-# ---- 10. _merge_aligned keeps alignment between chained passes ----
-prev = tone(220, 30, SR)
-nxt = np.concatenate([prev[-CTX * SR:] * 0.95, tone(220, 18, SR)])
-merged = cm._merge_aligned(prev, nxt, CTX * SR, 6 * SR)
-check("merge length = prev + new", merged.shape[0] == prev.shape[0] + 18 * SR,
-      f"got {merged.shape[0]}")
-
-# ---- 11. energy guard: holds the level against the anchor ----
-p = tone(220, 12, SR)
-quiet = np.concatenate([p, tone(220, 18, SR) * 0.5])     # 0.5x the anchor level
-anchor = float(np.sqrt(np.mean(p.astype(np.float64) ** 2)))
-guarded, ratio = cm._energy_guard(quiet.copy(), len(p), anchor)
-g_rms = np.sqrt(np.mean(guarded[len(p) + SR:] ** 2))  # past the 0.5s ramp
-check("guard: quiet chunk boosted to band floor",
-      abs(g_rms / anchor - cm.ENERGY_BAND[0]) < 0.05,
-      f"ratio_in={ratio:.2f} rms_out/anchor={g_rms / anchor:.2f}")
-dead = np.concatenate([p, tone(220, 18, SR) * 0.05])     # failed roll: 0.05x
-guarded_d, ratio_d = cm._energy_guard(dead.copy(), len(p), anchor)
-gd_rms = np.sqrt(np.mean(guarded_d[len(p) + SR:] ** 2))
-check("guard: gain capped at 3x on dead rolls",
-      abs(gd_rms / anchor - 0.15) < 0.03,
-      f"ratio_in={ratio_d:.2f} rms_out/anchor={gd_rms / anchor:.2f}")
-check("guard: prompt region untouched",
-      np.array_equal(guarded[:len(p)], quiet[:len(p)]))
-loud = np.concatenate([p, tone(220, 18, SR) * 2.0])      # 2.0 = 6.7x anchor
-guarded_l, _ = cm._energy_guard(loud.copy(), len(p), anchor)
-gl_rms = np.sqrt(np.mean(guarded_l[len(p) + SR:] ** 2))
-check("guard: hot chunk pulled to band ceiling",
-      abs(gl_rms / anchor - cm.ENERGY_BAND[1]) < 0.1,
-      f"rms_out/anchor={gl_rms / anchor:.2f}")
-inband = np.concatenate([p, tone(220, 18, SR)])
-guarded_i, ratio_i = cm._energy_guard(inband.copy(), len(p), anchor)
-check("guard: in-band chunk passes untouched",
-      np.array_equal(guarded_i, inband), f"ratio={ratio_i:.2f}")
-
-# ---- 12. collapse re-roll: a near-silent pass regenerates ----
-roll_calls = []
-
-def collapsing_pass(model, processor, prompt_audio, desc, new_seconds, guidance_scale):
-    roll_calls.append(new_seconds)
-    level = 0.01 if len(roll_calls) == 1 else 1.0   # first roll is dead air
-    return np.concatenate([prompt_audio * 0.95,
-                           tone(220, new_seconds, SR) * level])
-
-orig_pass = cm._generate_pass
-cm._generate_pass = collapsing_pass
-ext_r, _, _ = cm.continue_track("fake.wav", gen_duration=10)
-cm._generate_pass = orig_pass
-check("collapsed pass re-rolls once", len(roll_calls) == 2,
-      f"calls={roll_calls}")
-cm._generate_pass = fake_generate_pass
-
-print()
-if FAILURES:
-    print(f"{len(FAILURES)} FAILURES: {FAILURES}")
-    sys.exit(1)
-print("all checks passed")
+    y = (amp * np.sin(2 * np.pi * freq * t + phase)).astype(np.float32)
+    if channels == 1:
+        return y
+    return np.stack([y, np.sin(2 * np.pi * freq * t + phase + 0.1) * amp]).astype(np.float32)
+
+
+def test_to_stereo_44k_from_mono_22k():
+    mono = tone(220, 1.0, sr=22050, channels=1)
+    out = stitch.to_stereo_44k(mono, 22050)
+    assert out.shape[0] == 2                       # mono -> stereo
+    assert abs(out.shape[1] - 44100) <= 2          # 22050 -> 44100 (1s)
+
+
+def test_to_stereo_44k_truncates_extra_channels():
+    five = np.zeros((5, 1000), dtype=np.float32)
+    out = stitch.to_stereo_44k(five, SR)
+    assert out.shape[0] == 2
+
+
+def test_output_is_stereo_44k_and_unclipped():
+    orig = tone(220, 30, channels=2)
+    tail = tone(220, 30, channels=2)
+    out = stitch.stitch(orig, SR, tail, source_seconds=30)
+    assert out.ndim == 2 and out.shape[0] == 2
+    peak = float(np.abs(out).max())
+    assert peak <= 1.0
+    assert peak == pytest.approx(0.891, abs=1e-3)   # lifted to -1 dBFS
+
+
+def test_length_is_original_plus_tail_minus_crossfade():
+    orig = tone(220, 30, channels=2)
+    tail = tone(330, 25, channels=2)
+    xfade = 0.10
+    out = stitch.stitch(orig, SR, tail, source_seconds=30,
+                        crossfade_seconds=xfade)
+    expected = orig.shape[-1] + tail.shape[-1] - int(xfade * SR)
+    assert abs(out.shape[-1] - expected) <= 2
+
+
+def test_original_preserved_before_seam():
+    orig = tone(220, 10, channels=2)
+    tail = tone(440, 10, channels=2)
+    out = stitch.stitch(orig, SR, tail, source_seconds=10,
+                        crossfade_seconds=0.1, end_fade_seconds=0.0,
+                        peak_ceiling=1.0)
+    boundary = int(10 * SR)
+    # before the crossfade region the original should match up to the global
+    # gain stitch applies (compare shapes/correlation, not exact equality)
+    pre = out[:, : boundary - int(0.2 * SR)]
+    ref = orig[:, : pre.shape[-1]]
+    # high correlation == the original content is intact (only scaled)
+    corr = np.corrcoef(pre[0], ref[0])[0, 1]
+    assert corr > 0.999
+
+
+def test_closing_fade_ends_in_silence():
+    orig = tone(220, 5, channels=2)
+    tail = tone(220, 10, channels=2)
+    out = stitch.stitch(orig, SR, tail, source_seconds=5, end_fade_seconds=4.0)
+    tail_peak = float(np.abs(out[:, -200:]).max())
+    assert tail_peak < 1e-3                          # true silence at the end
+
+
+def test_quiet_tail_loudness_matched_up():
+    # a tail within the gain clamp (2x quieter) should be matched to the
+    # original's level at the seam; extreme ratios are deliberately only
+    # partially corrected (see the [0.4, 2.5] clamp in stitch.stitch).
+    orig = tone(220, 10, amp=0.4, channels=2)
+    quiet_tail = tone(220, 10, amp=0.2, channels=2)   # 2x quieter — inside clamp
+    out = stitch.stitch(orig, SR, quiet_tail, source_seconds=10,
+                        end_fade_seconds=0.0, peak_ceiling=1.0)
+    seam = int(10 * SR)
+    orig_rms = np.sqrt(np.mean(out[:, seam - SR: seam] ** 2))
+    tail_rms = np.sqrt(np.mean(out[:, seam + SR: seam + 3 * SR] ** 2))
+    assert tail_rms / orig_rms > 0.8
+
+
+def test_mono_original_becomes_stereo():
+    orig = tone(220, 5, channels=1)
+    tail = tone(220, 5, channels=2)
+    out = stitch.stitch(orig, SR, tail, source_seconds=5)
+    assert out.shape[0] == 2                          # output is always stereo
+
+
+def test_no_seam_click():
+    orig = tone(220, 8, channels=2)
+    tail = tone(220, 8, channels=2, phase=1.3)        # different phase at join
+    out = stitch.stitch(orig, SR, tail, source_seconds=8,
+                        crossfade_seconds=0.1, end_fade_seconds=0.0)
+    boundary = int(8 * SR)
+    seam = out[0, boundary - 1000: boundary + 1000]
+    ref = np.abs(np.diff(out[0, :SR])).max()
+    assert np.abs(np.diff(seam)).max() < ref * 3

test_verify_logic.py

@@ -0,0 +1,96 @@
+"""Unit tests for verify.py — the math QA metrics. Builds synthetic finished
+tracks (good, silence-collapsed, clipped) as temp WAVs and checks the right
+metric catches each fault. No model needed."""
+import numpy as np
+import soundfile as sf
+
+import verify
+
+SR = verify.SR
+
+
+def _stereo(freqs, seconds, amp=0.3):
+    """sum of sine partials -> a richer (non-pure-tone) stereo signal."""
+    t = np.arange(int(seconds * SR)) / SR
+    y = sum(np.sin(2 * np.pi * f * t) for f in freqs) / len(freqs)
+    L = (amp * y).astype(np.float32)
+    R = (amp * np.roll(y, 13)).astype(np.float32)   # slight decorrelation
+    return np.stack([L, R])
+
+
+def _write(path, audio):
+    sf.write(str(path), audio.T, SR, subtype="PCM_16")
+
+
+def test_relative_keys():
+    assert "A minor" in verify._relative_keys("C major")
+    assert "C major" in verify._relative_keys("A minor")
+    assert "C major" in verify._relative_keys("C major")
+
+
+def test_good_continuation_passes_health_metrics(tmp_path):
+    chord = [220, 277, 330]                          # A major-ish triad
+    orig = _stereo(chord, 10)
+    finished = _stereo(chord, 40)                    # continuous, same content
+    op, fp = tmp_path / "o.wav", tmp_path / "f.wav"
+    _write(op, orig)
+    _write(fp, finished)
+    rep = verify.verify(str(op), str(fp), source_seconds=10)
+    m = rep["metrics"]
+    assert m["no_silence_collapse"]["pass"]
+    assert m["no_clipping"]["pass"]
+    assert m["duration"]["pass"]
+    assert m["loudness_continuity"]["pass"]
+    assert m["spectral_rolloff"]["pass"]
+
+
+def test_silence_collapse_is_caught(tmp_path):
+    chord = [220, 277, 330]
+    orig = _stereo(chord, 10)
+    new = _stereo(chord, 30)
+    new[:, 5 * SR:15 * SR] = 0.0                     # a dead 10s stretch mid-tail
+    finished = np.concatenate([_stereo(chord, 10), new], axis=-1)
+    op, fp = tmp_path / "o.wav", tmp_path / "f.wav"
+    _write(op, orig)
+    _write(fp, finished)
+    rep = verify.verify(str(op), str(fp), source_seconds=10)
+    assert not rep["metrics"]["no_silence_collapse"]["pass"]
+
+
+def test_clipping_is_caught(tmp_path):
+    chord = [220, 277, 330]
+    orig = _stereo(chord, 10)
+    finished = _stereo(chord, 30) * 4.0              # drive it hard
+    finished = np.clip(finished, -1.0, 1.0)          # …into hard clipping
+    op, fp = tmp_path / "o.wav", tmp_path / "f.wav"
+    _write(op, orig)
+    _write(fp, finished)
+    rep = verify.verify(str(op), str(fp), source_seconds=10)
+    assert not rep["metrics"]["no_clipping"]["pass"]
+
+
+def test_closing_fade_not_flagged_as_collapse(tmp_path):
+    """a real cos^2 closing fade must NOT trip the silence-collapse metric."""
+    chord = [220, 277, 330]
+    finished = _stereo(chord, 40)
+    fade = int(4.0 * SR)
+    curve = np.cos(np.linspace(0, np.pi / 2, fade)) ** 2
+    finished[:, -fade:] *= curve
+    orig = _stereo(chord, 10)
+    op, fp = tmp_path / "o.wav", tmp_path / "f.wav"
+    _write(op, orig)
+    _write(fp, finished)
+    rep = verify.verify(str(op), str(fp), source_seconds=10, fade_seconds=4.0)
+    assert rep["metrics"]["no_silence_collapse"]["pass"]
+
+
+def test_report_shape(tmp_path):
+    chord = [220, 277, 330]
+    op, fp = tmp_path / "o.wav", tmp_path / "f.wav"
+    _write(op, _stereo(chord, 10))
+    _write(fp, _stereo(chord, 30))
+    rep = verify.verify(str(op), str(fp), source_seconds=10)
+    assert set(["metrics", "passed", "finished", "boundary"]).issubset(rep)
+    assert isinstance(rep["passed"], bool)
+    for name, mtr in rep["metrics"].items():
+        assert set(["value", "pass", "reason"]).issubset(mtr)

verify.py

@@ -0,0 +1,287 @@
+"""verify.py — mathematical audio QA for CODA continuations (dev/test tool).
+
+Not imported by the app at runtime. Given the user's original clip, the finished
+track, and the splice boundary, it measures whether the generated region is real,
+continuous music — the things an ear-check can miss between sessions:
+
+  duration · silence-collapse · clipping · loudness continuity · seam click ·
+  tempo continuity · key continuity · spectral rolloff · stereo width
+
+Each metric returns a value, a pass/fail against a threshold, and a short reason.
+`verify(...)` returns a structured report; `plot_report(...)` writes a diagnostic
+PNG (waveform + mel-spectrogram + seam-RMS overlay + a pass/fail table).
+
+CLI:  python verify.py <original> <finished> <source_seconds> [out.png]
+"""
+import sys
+
+import librosa
+import numpy as np
+
+from analyze import _key_from_audio, _scalar_tempo
+
+SR = 44100
+
+# thresholds (plan §4)
+SILENCE_WINDOW_S = 2.0
+SILENCE_MIN_RATIO = 0.30          # every 2s window > 0.3x source RMS
+CLIP_MAX_FRACTION = 1e-4          # < 0.01% of samples at full scale
+LOUDNESS_TOL_DB = 6.0             # seam RMS step within +/- 6 dB
+SEAM_JUMP_FACTOR = 6.0            # seam jump < 6x the 99.9th-pct local delta
+TEMPO_TOL = 0.08                  # generated tempo within +/-8% of source
+ROLLOFF_MIN_RATIO = 0.70          # new rolloff >= 0.7x source
+STEREO_CORR_RANGE = (0.10, 0.98)  # not mono-collapsed, not decorrelated noise
+
+
+def _mono(y):
+    return y.mean(axis=0) if y.ndim == 2 else y
+
+
+def _rms(x):
+    x = np.asarray(x, dtype=np.float64)
+    return float(np.sqrt(np.mean(x ** 2)) + 1e-12)
+
+
+def _db(ratio):
+    return 20.0 * np.log10(max(ratio, 1e-12))
+
+
+def _relative_keys(key):
+    """key string + its relative major/minor, for continuity matching."""
+    names = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']
+    try:
+        root, mode = key.split()
+    except ValueError:
+        return {key}
+    i = names.index(root)
+    out = {key}
+    if mode == 'major':
+        out.add(f'{names[(i + 9) % 12]} minor')   # relative minor
+    else:
+        out.add(f'{names[(i + 3) % 12]} major')    # relative major
+    return out
+
+
+def verify(original_path, finished_path, source_seconds, fade_seconds=4.0):
+    """Return a report dict: {metrics: {name: {value, pass, reason}}, passed:bool,
+    and arrays for plotting}. `fade_seconds` is the stitch closing fade, excluded
+    from the silence-collapse scan so the intentional ending isn't flagged."""
+    fin, _ = librosa.load(finished_path, sr=SR, mono=False)
+    if fin.ndim == 1:
+        fin = np.stack([fin, fin])
+    fin_m = _mono(fin)
+    total_s = fin.shape[-1] / SR
+
+    boundary = int(round(source_seconds * SR))
+    boundary = max(0, min(boundary, fin.shape[-1] - 1))
+    src_region = fin_m[:boundary]
+    new_region = fin_m[boundary:]
+
+    src_rms = _rms(src_region) if len(src_region) else _rms(fin_m)
+    metrics = {}
+
+    # 1. duration sane
+    metrics['duration'] = {
+        'value': round(total_s, 2),
+        'pass': total_s > source_seconds + 1.0,
+        'reason': f'{total_s:.1f}s total, source {source_seconds:.1f}s',
+    }
+
+    # 2. silence collapse — every window in the new region carries energy.
+    # exclude the intentional closing fade (last fade_seconds) so a real ending
+    # isn't read as a collapse.
+    win = int(SILENCE_WINDOW_S * SR)
+    body = new_region[:max(0, len(new_region) - int((fade_seconds + 1.0) * SR))]
+    worst = 1.0
+    if len(body) >= win:
+        ratios = [_rms(body[i:i + win]) / src_rms
+                  for i in range(0, len(body) - win + 1, win)]
+        worst = min(ratios) if ratios else 1.0
+    metrics['no_silence_collapse'] = {
+        'value': round(worst, 3),
+        'pass': worst > SILENCE_MIN_RATIO,
+        'reason': f'quietest 2s window = {worst:.2f}x source RMS '
+                  f'(need > {SILENCE_MIN_RATIO})',
+    }
+
+    # 3. clipping
+    clip_frac = float(np.mean(np.abs(fin) >= 0.999))
+    metrics['no_clipping'] = {
+        'value': clip_frac,
+        'pass': clip_frac < CLIP_MAX_FRACTION,
+        'reason': f'{clip_frac*100:.4f}% samples at full scale',
+    }
+
+    # 4. loudness continuity across the seam
+    w = int(3.0 * SR)
+    pre = fin_m[max(0, boundary - w):boundary]
+    post = fin_m[boundary:boundary + w]
+    step_db = _db(_rms(post) / _rms(pre)) if len(pre) and len(post) else 0.0
+    metrics['loudness_continuity'] = {
+        'value': round(step_db, 2),
+        'pass': abs(step_db) < LOUDNESS_TOL_DB,
+        'reason': f'seam RMS step {step_db:+.1f} dB '
+                  f'(tol +/-{LOUDNESS_TOL_DB:.0f})',
+    }
+
+    # 5. seam discontinuity — no audible click at the splice point. reference
+    # the seam's largest sample step against a HIGH QUANTILE of the surrounding
+    # |delta| distribution, not its std: on percussive/bright music the biggest
+    # single delta is heavy-tailed and dwarfs the std with no click present, so
+    # an std-based gate false-positives on drums/electronic continuations.
+    g = int(0.05 * SR)
+    seg = fin_m[max(0, boundary - g):boundary + g]
+    if len(seg) > 4:
+        diffs = np.abs(np.diff(seg))
+        local = np.abs(np.diff(fin_m[max(0, boundary - SR):boundary + SR]))
+        local_ref = float(np.quantile(local, 0.999) + 1e-9) if len(local) else 1.0
+        jump = float(diffs.max()) / local_ref
+    else:
+        jump = 0.0
+    metrics['no_seam_click'] = {
+        'value': round(jump, 2),
+        'pass': jump < SEAM_JUMP_FACTOR,
+        'reason': f'max seam jump {jump:.1f}x the 99.9th-pct local delta '
+                  f'(need < {SEAM_JUMP_FACTOR})',
+    }
+
+    # 6/7. tempo + key continuity (source region vs new region)
+    src_for_analysis = src_region if len(src_region) > SR else fin_m
+    src_tempo = _scalar_tempo(librosa.beat.beat_track(y=src_for_analysis, sr=SR)[0])
+    new_tempo = _scalar_tempo(librosa.beat.beat_track(y=new_region, sr=SR)[0]) \
+        if len(new_region) > SR else src_tempo
+    tempo_dev = abs(new_tempo - src_tempo) / max(src_tempo, 1e-6)
+    # allow half/double-time relationship (common + musically valid)
+    half_double = min(tempo_dev,
+                      abs(new_tempo - 2 * src_tempo) / max(2 * src_tempo, 1e-6),
+                      abs(new_tempo - 0.5 * src_tempo) / max(0.5 * src_tempo, 1e-6))
+    metrics['tempo_continuity'] = {
+        'value': f'{src_tempo:.0f}->{new_tempo:.0f} bpm',
+        'pass': half_double < TEMPO_TOL,
+        'reason': f'{half_double*100:.1f}% deviation (tol {TEMPO_TOL*100:.0f}%, '
+                  f'half/double allowed)',
+    }
+
+    src_key = _key_from_audio(src_for_analysis, SR)
+    new_key = _key_from_audio(new_region, SR) if len(new_region) > SR else src_key
+    metrics['key_continuity'] = {
+        'value': f'{src_key} -> {new_key}',
+        'pass': new_key in _relative_keys(src_key),
+        'reason': f'generated key {new_key} vs source {src_key} '
+                  f'(relative maj/min ok)',
+    }
+
+    # 8. spectral rolloff — confirm the tail isn't band-limited
+    src_roll = float(np.mean(librosa.feature.spectral_rolloff(
+        y=src_for_analysis, sr=SR))) + 1e-6
+    new_roll = float(np.mean(librosa.feature.spectral_rolloff(
+        y=new_region, sr=SR))) if len(new_region) > SR else src_roll
+    metrics['spectral_rolloff'] = {
+        'value': f'{src_roll/1000:.1f}->{new_roll/1000:.1f} kHz',
+        'pass': new_roll >= ROLLOFF_MIN_RATIO * src_roll,
+        'reason': f'new {new_roll/1000:.1f}kHz vs source {src_roll/1000:.1f}kHz '
+                  f'(need >= {ROLLOFF_MIN_RATIO:.0%})',
+    }
+
+    # 9. stereo width in the new region
+    if fin.shape[0] == 2 and fin.shape[-1] - boundary > SR:
+        L, R = fin[0, boundary:], fin[1, boundary:]
+        if np.std(L) > 1e-6 and np.std(R) > 1e-6:
+            corr = float(np.corrcoef(L, R)[0, 1])
+        else:
+            corr = 1.0
+    else:
+        corr = 1.0
+    lo, hi = STEREO_CORR_RANGE
+    metrics['stereo_width'] = {
+        'value': round(corr, 3),
+        'pass': lo <= corr <= hi or corr == 1.0,
+        'reason': f'L/R correlation {corr:.2f} (target {lo}-{hi}; '
+                  f'1.0 = intentional mono)',
+    }
+
+    passed = all(m['pass'] for m in metrics.values())
+    return {
+        'metrics': metrics,
+        'passed': passed,
+        'finished': fin,
+        'boundary': boundary,
+        'source_seconds': source_seconds,
+        'total_seconds': total_s,
+    }
+
+
+def print_report(report):
+    print("\n==== CODA VERIFY ====")
+    width = max(len(k) for k in report['metrics'])
+    for name, m in report['metrics'].items():
+        tag = 'PASS' if m['pass'] else 'FAIL'
+        print(f"  [{tag}] {name:<{width}}  {m['reason']}")
+    print(f"  ----\n  OVERALL: {'PASS' if report['passed'] else 'FAIL'}\n")
+
+
+def plot_report(report, out_png):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+    import librosa.display   # submodule isn't pulled in by `import librosa`
+
+    fin = report['finished']
+    fin_m = _mono(fin)
+    b = report['boundary']
+    sr = SR
+    t = np.arange(fin_m.shape[-1]) / sr
+
+    fig, axes = plt.subplots(3, 1, figsize=(12, 9), facecolor="#0b0d10")
+    for ax in axes:
+        ax.set_facecolor("#14171c")
+        ax.tick_params(colors="#9aa4b2")
+        for s in ax.spines.values():
+            s.set_color("#2a2f37")
+
+    axes[0].plot(t, fin_m, color="#39d0d8", lw=0.4)
+    axes[0].axvline(b / sr, color="#ffb347", lw=1.5, label="seam")
+    axes[0].set_title("Finished waveform (seam marked)", color="#e6e9ef")
+    axes[0].legend(facecolor="#14171c", labelcolor="#e6e9ef")
+
+    S = librosa.feature.melspectrogram(y=fin_m, sr=sr, n_mels=128)
+    Sdb = librosa.power_to_db(S, ref=np.max)
+    librosa.display.specshow(Sdb, sr=sr, x_axis="time", y_axis="mel", ax=axes[1])
+    axes[1].axvline(b / sr, color="#ffb347", lw=1.5)
+    axes[1].set_title("Mel-spectrogram", color="#e6e9ef")
+
+    rows = [[k, ("PASS" if m['pass'] else "FAIL"), str(m['value'])]
+            for k, m in report['metrics'].items()]
+    axes[2].axis("off")
+    tbl = axes[2].table(cellText=rows,
+                        colLabels=["metric", "result", "value"],
+                        loc="center", cellLoc="left")
+    tbl.auto_set_font_size(False)
+    tbl.set_fontsize(9)
+    for (r, c), cell in tbl.get_celld().items():
+        cell.set_edgecolor("#2a2f37")
+        if r == 0:
+            cell.set_facecolor("#22272e")
+            cell.set_text_props(color="#e6e9ef")
+        else:
+            ok = report['metrics'][rows[r - 1][0]]['pass']
+            cell.set_facecolor("#14171c")
+            cell.set_text_props(color="#5fd38d" if ok else "#ff6b6b")
+    fig.suptitle(f"CODA verify — {'PASS' if report['passed'] else 'FAIL'}",
+                 color="#e6e9ef", fontsize=14)
+    fig.tight_layout()
+    fig.savefig(out_png, dpi=110, facecolor="#0b0d10")
+    plt.close(fig)
+    print(f"  wrote {out_png}")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 4:
+        print("usage: python verify.py <original> <finished> "
+              "<source_seconds> [out.png]")
+        sys.exit(1)
+    rep = verify(sys.argv[1], sys.argv[2], float(sys.argv[3]))
+    print_report(rep)
+    if len(sys.argv) > 4:
+        plot_report(rep, sys.argv[4])
+    sys.exit(0 if rep['passed'] else 2)