Make polish real post-processing; fix distortion, underline and dead MP3 click

Audit of the reported problems, all confirmed and fixed:

Polish was preview-only, which is not what post-processing means. Speed,
tone and level are now rendered into the exported file by a new
/api/audio/{id}/export endpoint — WSOLA time-stretch (pitch preserved,
duration accurate to 0.2%), RBJ shelving EQ (measured within 0.1dB of
target) and a boost-only leveller, block-processed so a 5.5-hour take
costs ~1.7 minutes and bounded memory. Download links switch to the
rendered export as soon as a setting is changed, and the panel says
which one you will get.

The distortion was real: preview applied +4.6dB of makeup gain after
compression with nothing to catch peaks, so anything above -4.6dBFS
clipped. Replaced with a limiter-terminated graph. The exported
leveller only ever boosts — it previously normalised every take to the
same loudness, making a healthy take quieter.

Stage 'Download WAV' was underlined because .btn-ink lacked
text-decoration:none while .btn-pill-outline had it; moved to .btn.
Clicking MP3 did nothing visible while the server encoded, so exports
now announce themselves.

Voice-clone previews were never affected by polish — the preview
element is separate from the result element; verified.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

app.py

@@ -852,6 +852,149 @@ async def api_last_take() -> dict:
 
 MP3_CACHE: dict[str, bytes] = {}  # audio_id -> encoded mp3, built lazily on first request
 
+# --- Post-processing (the "polish" controls act on the exported file) ---
+TONE_SHELVES = {                    # (low-shelf dB, high-shelf dB)
+    "neutral": (0.0, 0.0),
+    "warm": (4.0, -3.0),
+    "bright": (-2.0, 4.5),
+}
+POLISH_BLOCK_SECONDS = 30           # bounds memory regardless of take length
+
+
+def _shelf_sos(kind: str, f0: float, gain_db: float, fs: float) -> np.ndarray:
+    """RBJ cookbook shelving biquad, as a single second-order section."""
+    A = 10 ** (gain_db / 40.0)
+    w0 = 2 * np.pi * f0 / fs
+    cos_w0, sin_w0 = np.cos(w0), np.sin(w0)
+    alpha = sin_w0 / 2.0 * np.sqrt(2.0)
+    sqrtA2alpha = 2.0 * np.sqrt(A) * alpha
+    if kind == "low":
+        b = [A * ((A + 1) - (A - 1) * cos_w0 + sqrtA2alpha),
+             2 * A * ((A - 1) - (A + 1) * cos_w0),
+             A * ((A + 1) - (A - 1) * cos_w0 - sqrtA2alpha)]
+        a = [(A + 1) + (A - 1) * cos_w0 + sqrtA2alpha,
+             -2 * ((A - 1) + (A + 1) * cos_w0),
+             (A + 1) + (A - 1) * cos_w0 - sqrtA2alpha]
+    else:
+        b = [A * ((A + 1) + (A - 1) * cos_w0 + sqrtA2alpha),
+             -2 * A * ((A - 1) + (A + 1) * cos_w0),
+             A * ((A + 1) + (A - 1) * cos_w0 - sqrtA2alpha)]
+        a = [(A + 1) - (A - 1) * cos_w0 + sqrtA2alpha,
+             2 * ((A - 1) - (A + 1) * cos_w0),
+             (A + 1) - (A - 1) * cos_w0 - sqrtA2alpha]
+    return np.array([[b[0] / a[0], b[1] / a[0], b[2] / a[0], 1.0, a[1] / a[0], a[2] / a[0]]])
+
+
+def _time_stretch(x: np.ndarray, rate: float) -> np.ndarray:
+    """WSOLA time-scaling: rate > 1 shortens (faster), < 1 lengthens (slower).
+
+    Pitch is preserved — the point of the exercise, since plain resampling
+    would turn a slowed voice into a drawl an octave down.
+    """
+    if abs(rate - 1.0) < 1e-3 or len(x) < 4096:
+        return x
+    N, search = 1024, 128
+    Hs = N // 2
+    Ha = max(1, int(round(Hs * rate)))
+    win = np.hanning(N).astype(np.float32)
+    frames = max(1, int((len(x) - N - search) / Ha))
+    out = np.zeros(frames * Hs + N, dtype=np.float32)
+    norm = np.zeros_like(out)
+    prev_tail = x[:N] * win
+    for i in range(frames):
+        want = i * Ha
+        lo = max(0, want - search)
+        hi = min(len(x) - N, want + search)
+        if hi <= lo:
+            seg_start = min(max(0, want), max(0, len(x) - N))
+        else:
+            cand = x[lo:hi + N]
+            # pick the offset whose overlap best matches the previous tail
+            windows = np.lib.stride_tricks.sliding_window_view(cand, N)[: hi - lo + 1]
+            scores = windows[:, :Hs] @ prev_tail[Hs:]
+            seg_start = lo + int(np.argmax(scores))
+        seg = x[seg_start:seg_start + N]
+        if len(seg) < N:
+            break
+        seg = seg * win
+        o = i * Hs
+        out[o:o + N] += seg
+        norm[o:o + N] += win
+        prev_tail = seg
+    np.maximum(norm, 1e-6, out=norm)
+    return out / norm
+
+
+def _polish_wav(wav_bytes: bytes, speed: float, tone: str, level: bool) -> bytes:
+    """Apply the polish settings to a stored take and return a new WAV.
+
+    Processed in blocks so a five-hour render doesn't need gigabytes at once.
+    """
+    from scipy.signal import sosfilt, sosfilt_zi
+
+    sample_rate, samples = wavfile.read(io.BytesIO(wav_bytes))
+    if samples.ndim > 1:
+        samples = samples[:, 0]
+    low_db, high_db = TONE_SHELVES.get(tone, TONE_SHELVES["neutral"])
+    sos = None
+    if low_db or high_db:
+        parts = []
+        if low_db:
+            parts.append(_shelf_sos("low", 250.0, low_db, sample_rate))
+        if high_db:
+            parts.append(_shelf_sos("high", 3500.0, high_db, sample_rate))
+        sos = np.vstack(parts)
+    zi = sosfilt_zi(sos) * 0.0 if sos is not None else None
+
+    block = POLISH_BLOCK_SECONDS * sample_rate
+    overlap = int(0.025 * sample_rate)  # crossfade between stretched blocks
+    fade = np.linspace(0.0, 1.0, overlap, dtype=np.float32)
+    pieces: list[np.ndarray] = []
+    peak = 1e-6
+    sq_sum = 0.0
+    sq_n = 0
+    for start in range(0, len(samples), block):
+        chunk = samples[start:start + block].astype(np.float32) / 32768.0
+        if sos is not None:
+            chunk, zi = sosfilt(sos, chunk, zi=zi)
+            chunk = chunk.astype(np.float32)
+        chunk = _time_stretch(chunk, speed)
+        if pieces and overlap and len(chunk) > overlap and len(pieces[-1]) > overlap:
+            pieces[-1][-overlap:] = pieces[-1][-overlap:] * (1 - fade) + chunk[:overlap] * fade
+            chunk = chunk[overlap:]
+        if len(chunk):
+            peak = max(peak, float(np.abs(chunk).max()))
+            sq_sum += float(np.dot(chunk, chunk))
+            sq_n += len(chunk)
+        pieces.append(chunk)
+
+    if level:
+        # Lift quiet speech toward a target loudness; the limiter below only
+        # touches peaks, so this raises level without squashing the whole take.
+        # Boost-only: a take that is already at a healthy level is left alone
+        # rather than pulled down to a target.
+        rms = np.sqrt(sq_sum / max(1, sq_n))
+        gain = float(min(6.0, max(1.0, 0.18 / max(rms, 1e-6))))
+    else:
+        gain = float(min(1.0, 0.99 / peak))  # only pull down if it would clip
+
+    KNEE = 0.8
+    out = bytearray()
+    for chunk in pieces:
+        y = chunk * gain
+        if level:
+            mag = np.abs(y)
+            over = mag > KNEE
+            if over.any():
+                excess = (mag[over] - KNEE) / (1.0 - KNEE)
+                y[over] = np.sign(y[over]) * (KNEE + (1.0 - KNEE) * np.tanh(excess))
+        np.clip(y, -1.0, 1.0, out=y)
+        out += (y * 32767.0).astype(np.int16).tobytes()
+
+    header = io.BytesIO()
+    wavfile.write(header, sample_rate, np.frombuffer(bytes(out), dtype=np.int16))
+    return header.getvalue()
+
 
 def _encode_mp3(wav_bytes: bytes) -> bytes:
     """Encode our PCM16 WAV to mono MP3 (96 kbps — transparent for 24kHz speech)."""
@@ -890,6 +1033,43 @@ async def api_audio_mp3(audio_id: str) -> Response:
     )
 
 
+POLISH_CACHE: dict[tuple, bytes] = {}   # (audio_id, speed, tone, level, fmt) -> bytes
+
+
+@app.get("/api/audio/{audio_id}/export")
+async def api_audio_export(
+    audio_id: str,
+    speed: float = 1.0,
+    tone: str = "neutral",
+    level: bool = False,
+    fmt: str = "wav",
+) -> Response:
+    """Download the take with the polish settings baked in."""
+    entry = AUDIO_STORE.get(audio_id)
+    if entry is None:
+        raise HTTPException(status_code=404, detail="Audio not found or expired.")
+    speed = round(min(1.25, max(0.8, speed)), 2)
+    tone = tone if tone in TONE_SHELVES else "neutral"
+    fmt = "mp3" if fmt == "mp3" else "wav"
+    key = (audio_id, speed, tone, bool(level), fmt)
+    if key not in POLISH_CACHE:
+        _, wav_bytes = entry
+        loop = asyncio.get_event_loop()
+        processed = await loop.run_in_executor(
+            None, _polish_wav, wav_bytes, speed, tone, bool(level)
+        )
+        if fmt == "mp3":
+            processed = await loop.run_in_executor(None, _encode_mp3, processed)
+        POLISH_CACHE.clear()          # one polished export at a time; these are large
+        POLISH_CACHE[key] = processed
+    data = POLISH_CACHE[key]
+    return Response(
+        content=data,
+        media_type="audio/mpeg" if fmt == "mp3" else "audio/wav",
+        headers={"Content-Disposition": f'attachment; filename="chorus-polished.{fmt}"'},
+    )
+
+
 @app.get("/api/audio/{audio_id}/peaks")
 async def api_audio_peaks(audio_id: str, buckets: int = 2048) -> dict:
     """RMS envelope for the waveform display.

static/app.js

@@ -84,6 +84,7 @@ const el = {};
   "stageDot", "stageLine", "stageSpeaker", "stageCloseBtn", "stageDownloadBtn",
   "stageScriptToggle", "stageTranscript", "stagePolishToggle", "polishPanel",
   "polishSpeed", "polishSpeedValue", "polishTone", "polishBoost", "polishReset",
+  "polishNote", "polishStatus",
   "generationTime", "audioDuration", "resultModel", "downloadBtn",
   "realtimeRow", "realtimeFactor", "warmupRow", "warmupTime",
   "downloadMp3Btn", "stageDownloadMp3Btn",
@@ -1429,7 +1430,20 @@ const TONE_CURVES = {
   bright: { low: -2, high: 4.5 },
 };
 
-const polish = { ctx: null, low: null, high: null, comp: null, gain: null, tone: "neutral" };
+const polish = { ctx: null, low: null, high: null, gain: null, limiter: null, tone: "neutral", audioId: null };
+
+function polishSettings() {
+  return {
+    speed: Number(el.polishSpeed.value),
+    tone: polish.tone,
+    level: el.polishBoost.checked,
+  };
+}
+
+function polishIsDefault() {
+  const s = polishSettings();
+  return Math.abs(s.speed - 1) < 0.001 && s.tone === "neutral" && !s.level;
+}
 
 function ensureAudioGraph() {
   if (polish.ctx) return true;
@@ -1446,13 +1460,21 @@ function ensureAudioGraph() {
     polish.high = polish.ctx.createBiquadFilter();
     polish.high.type = "highshelf";
     polish.high.frequency.value = 3500;
-    polish.comp = polish.ctx.createDynamicsCompressor();
     polish.gain = polish.ctx.createGain();
+    // A brick-wall-ish limiter always sits last: the old graph applied makeup
+    // gain after compression with nothing to catch peaks, which clipped and
+    // was heard as distortion.
+    polish.limiter = polish.ctx.createDynamicsCompressor();
+    polish.limiter.threshold.value = -1.5;
+    polish.limiter.knee.value = 0;
+    polish.limiter.ratio.value = 20;
+    polish.limiter.attack.value = 0.003;
+    polish.limiter.release.value = 0.12;
     source.connect(polish.low);
     polish.low.connect(polish.high);
-    polish.high.connect(polish.comp);
-    polish.comp.connect(polish.gain);
-    polish.gain.connect(polish.ctx.destination);
+    polish.high.connect(polish.gain);
+    polish.gain.connect(polish.limiter);
+    polish.limiter.connect(polish.ctx.destination);
     applyPolish();
     return true;
   } catch (error) {
@@ -1474,17 +1496,51 @@ function applyPolish() {
     btn.classList.toggle("active", btn.dataset.tone === polish.tone);
   });
 
+  updateExportLinks();
+
   if (!polish.ctx) return;
   const curve = TONE_CURVES[polish.tone] || TONE_CURVES.neutral;
   polish.low.gain.value = curve.low;
   polish.high.gain.value = curve.high;
-  const boost = el.polishBoost.checked;
-  // ratio 1 is a straight wire, so the compressor is bypassed when off.
-  polish.comp.threshold.value = boost ? -26 : 0;
-  polish.comp.ratio.value = boost ? 4 : 1;
-  polish.gain.gain.value = boost ? 1.7 : 1;
+  polish.gain.gain.value = el.polishBoost.checked ? 1.6 : 1;
+}
+
+/* Downloads carry the polish settings: default settings stream the stored take
+   untouched, anything else is rendered by the server. */
+function updateExportLinks() {
+  if (!polish.audioId) return;
+  const plain = `/api/audio/${polish.audioId}`;
+  const s = polishSettings();
+  const query = `speed=${s.speed}&tone=${s.tone}&level=${s.level}`;
+  const isDefault = polishIsDefault();
+  const wavUrl = isDefault ? plain : `${plain}/export?${query}&fmt=wav`;
+  const mp3Url = isDefault ? `${plain}.mp3` : `${plain}/export?${query}&fmt=mp3`;
+  el.downloadBtn.href = wavUrl;
+  el.stageDownloadBtn.href = wavUrl;
+  el.downloadMp3Btn.href = mp3Url;
+  el.stageDownloadMp3Btn.href = mp3Url;
+  el.polishNote.textContent = isDefault
+    ? "Settings are live here; downloads give you the original take."
+    : "Downloads are rendered with these settings — that can take a moment.";
 }
 
+// Encoding/rendering happens on the server when the link is clicked, and a
+// long take takes real time, so say so instead of appearing to do nothing.
+function noteExportStarted(kind) {
+  el.polishStatus.hidden = false;
+  el.polishStatus.textContent = `Preparing your ${kind}… the download starts when it's ready (long takes can take a minute or two).`;
+  clearTimeout(noteExportStarted.timer);
+  noteExportStarted.timer = setTimeout(() => { el.polishStatus.hidden = true; }, 20000);
+}
+
+[["downloadBtn", "WAV"], ["stageDownloadBtn", "WAV"],
+ ["downloadMp3Btn", "MP3"], ["stageDownloadMp3Btn", "MP3"]].forEach(([id, kind]) => {
+  el[id].addEventListener("click", () => {
+    // The stored WAV is served instantly; everything else is rendered on demand.
+    if (kind === "MP3" || !polishIsDefault()) noteExportStarted(kind);
+  });
+});
+
 function polishTouched() {
   ensureAudioGraph();
   if (polish.ctx && polish.ctx.state === "suspended") polish.ctx.resume();
@@ -1782,13 +1838,11 @@ async function presentTake(audioId, durationSeconds, snapshot) {
   setStatus("complete");
   const url = `/api/audio/${audioId}`;
   el.resultAudio.src = url;
-  el.downloadBtn.href = url;
-  el.stageDownloadBtn.href = url;
-  const mp3Url = `/api/audio/${audioId}.mp3`;
+  polish.audioId = audioId;
   el.downloadMp3Btn.hidden = false;
   el.stageDownloadMp3Btn.hidden = false;
-  el.downloadMp3Btn.href = mp3Url;
-  el.stageDownloadMp3Btn.href = mp3Url;
+  el.polishStatus.hidden = true;
+  updateExportLinks();
   el.audioDuration.textContent = formatDuration(durationSeconds);
   el.playerTime.textContent = `0:00 / ${formatClock(durationSeconds)}`;
   el.stageTime.textContent = `0:00 / ${formatClock(durationSeconds)}`;

static/index.html

@@ -242,10 +242,11 @@
             </div>
           </div>
           <label class="polish-check">
-            <input type="checkbox" id="polishBoost" /> Even out quiet speech
+            <input type="checkbox" id="polishBoost" /> Lift quiet speech
           </label>
+          <div class="polish-status" id="polishStatus" hidden></div>
           <div class="polish-note">
-            <span>Affects playback here — downloads stay the original take.</span>
+            <span id="polishNote">Preview only until you change something — then downloads are rendered with these settings.</span>
             <button type="button" class="polish-reset" id="polishReset">Reset</button>
           </div>
         </div>

static/styles.css

@@ -437,6 +437,7 @@ select:focus { outline: none; border-color: #d9a98c; }
   font-family: var(--font-ui);
   font-size: 0.84rem;
   font-weight: 700;
+  text-decoration: none;  /* anchors styled as buttons must not underline */
   border-radius: var(--radius-sm);
   border: 1px solid var(--border-strong);
   background: var(--paper);
@@ -974,6 +975,16 @@ body.is-generating .canvas { opacity: 0.6; transition: opacity 0.2s; }
   font-size: 0.72rem;
   color: var(--ink-ghost);
 }
+.polish-status {
+  margin-top: 10px;
+  padding: 9px 12px;
+  border-radius: 10px;
+  background: var(--accent-soft);
+  color: var(--accent-hover);
+  font-size: 0.76rem;
+  font-weight: 600;
+  line-height: 1.45;
+}
 .polish-reset {
   background: none;
   border: none;