v7: Add auto-tuner — self-supervised param optimization using reconstruction quality

sample_extractor.py

@@ -1,12 +1,11 @@
 #!/usr/bin/env python3
 """
-Sample Extractor v6 — Tested on real hardstyle tracks.
+Sample Extractor v7 — Auto-tuning via reconstruction quality.
 
-Fixes from v5:
-  - NCC compare window auto-scales to median hit length (no more zero-pad inflation)
-  - Target range uses n_clusters directly when binary search hits a cliff
-  - Better defaults for real music (delta=0.12, energy=-35, min_gap=0.03)
-  - Caching for stem separation, BPM, NCC distance matrix
+New: auto_tune() optimizes parameters against the uploaded audio itself.
+No ground truth needed — measures spectral envelope correlation between
+the rendered reconstruction and the original stem. Sweeps onset detection
+params and cluster counts, using cached NCC matrices for speed.
 """
 
 import argparse, json, os, sys, warnings, hashlib
@@ -64,88 +63,74 @@ def cache_clear(): _cache.clear()
 
 # ─── Stage 1: Stem separation ────────────────────────────────────────────────
 
-def extract_stem(audio_path: str, stem: str = "drums", device: str = "cpu",
-                 model_name: str = "htdemucs_ft", shifts: int = 1,
-                 overlap: float = 0.25) -> tuple:
+def extract_stem(audio_path, stem="drums", device="cpu",
+                 model_name="htdemucs_ft", shifts=1, overlap=0.25):
     if stem == "all":
         y, sr = librosa.load(audio_path, sr=44100, mono=True)
         return y.astype(np.float32), sr
-
     with open(audio_path, 'rb') as f:
-        file_hash = hashlib.md5(f.read(200000)).hexdigest()
-    ck = ("stem", file_hash, stem, model_name, shifts, overlap)
-    cached = cache_get(ck)
-    if cached is not None:
-        print(f"[Stage 1] Using cached {stem} stem"); return cached
-
+        fh = hashlib.md5(f.read(200000)).hexdigest()
+    ck = ("stem", fh, stem, model_name, shifts, overlap)
+    c = cache_get(ck)
+    if c is not None: print(f"[Stage 1] Cached {stem} stem"); return c
     from demucs.pretrained import get_model
     from demucs.apply import apply_model
     print(f"[Stage 1] Extracting '{stem}' with {model_name}...")
-    model = get_model(model_name); model.eval().to(device)
-    sr = model.samplerate
-    if stem not in model.sources:
-        raise ValueError(f"'{stem}' not in {model.sources}")
-    audio_np, _ = librosa.load(audio_path, sr=sr, mono=False)
-    if audio_np.ndim == 1: audio_np = np.stack([audio_np, audio_np])
-    elif audio_np.shape[0] > 2: audio_np = audio_np[:2]
-    elif audio_np.shape[0] == 1: audio_np = np.concatenate([audio_np, audio_np], axis=0)
-    wav = torch.from_numpy(audio_np).float().unsqueeze(0).to(device)
+    model = get_model(model_name); model.eval().to(device); sr = model.samplerate
+    if stem not in model.sources: raise ValueError(f"'{stem}' not in {model.sources}")
+    a, _ = librosa.load(audio_path, sr=sr, mono=False)
+    if a.ndim==1: a=np.stack([a,a])
+    elif a.shape[0]>2: a=a[:2]
+    elif a.shape[0]==1: a=np.concatenate([a,a],axis=0)
+    wav = torch.from_numpy(a).float().unsqueeze(0).to(device)
     with torch.no_grad():
-        sources = apply_model(model, wav, device=device, shifts=shifts, split=True, overlap=overlap)
-    result = sources[0, model.sources.index(stem)].mean(dim=0).cpu().numpy()
-    print(f"  ✓ {stem}: {len(result)/sr:.1f}s")
-    return cache_set(ck, (result.astype(np.float32), sr))
+        src = apply_model(model, wav, device=device, shifts=shifts, split=True, overlap=overlap)
+    r = src[0, model.sources.index(stem)].mean(dim=0).cpu().numpy()
+    print(f"  ✓ {stem}: {len(r)/sr:.1f}s")
+    return cache_set(ck, (r.astype(np.float32), sr))
 
 
 # ─── Stage 2: Onset detection ────────────────────────────────────────────────
 
-def detect_onsets(y: np.ndarray, sr: int, pre_pad: float = 0.005,
-                  min_dur: float = 0.02, max_dur: float = 1.5,
-                  min_gap: float = 0.03, energy_threshold_db: float = -35.0,
-                  mode: str = "auto", backtrack: bool = True,
-                  onset_delta: float = 0.12) -> list:
-    print(f"[Stage 2] Detecting onsets (mode={mode}, delta={onset_delta}, energy≥{energy_threshold_db}dB)...")
+def detect_onsets(y, sr, pre_pad=0.005, min_dur=0.02, max_dur=1.5,
+                  min_gap=0.03, energy_threshold_db=-35.0,
+                  mode="auto", backtrack=True, onset_delta=0.12):
+    print(f"[Stage 2] Onsets (mode={mode}, delta={onset_delta}, energy≥{energy_threshold_db}dB)...")
     if mode == "percussive":
-        onset_env = librosa.onset.onset_strength(y=y, sr=sr, aggregate=np.median, fmax=8000)
+        oe = librosa.onset.onset_strength(y=y, sr=sr, aggregate=np.median, fmax=8000)
     elif mode == "harmonic":
-        y_harm, _ = librosa.effects.hpss(y)
-        onset_env = librosa.onset.onset_strength(y=y_harm, sr=sr, fmax=8000, lag=2, max_size=3)
+        yh, _ = librosa.effects.hpss(y)
+        oe = librosa.onset.onset_strength(y=yh, sr=sr, fmax=8000, lag=2, max_size=3)
     elif mode == "broadband":
-        onset_env = librosa.onset.onset_strength(y=y, sr=sr)
+        oe = librosa.onset.onset_strength(y=y, sr=sr)
     else:
-        y_harm, y_perc = librosa.effects.hpss(y)
-        envs = [
-            librosa.onset.onset_strength(y=y, sr=sr, fmin=20, fmax=250, aggregate=np.median),
-            librosa.onset.onset_strength(y=y, sr=sr, fmin=250, fmax=4000, aggregate=np.median),
-            librosa.onset.onset_strength(y=y, sr=sr, fmin=4000, fmax=min(sr//2,20000), aggregate=np.median),
-            librosa.onset.onset_strength(y=y_harm, sr=sr, lag=2),
-        ]
+        yh, yp = librosa.effects.hpss(y)
+        envs = [librosa.onset.onset_strength(y=y,sr=sr,fmin=20,fmax=250,aggregate=np.median),
+                librosa.onset.onset_strength(y=y,sr=sr,fmin=250,fmax=4000,aggregate=np.median),
+                librosa.onset.onset_strength(y=y,sr=sr,fmin=4000,fmax=min(sr//2,20000),aggregate=np.median),
+                librosa.onset.onset_strength(y=yh,sr=sr,lag=2)]
         def _n(x): m=x.max(); return x/m if m>0 else x
-        onset_env = np.maximum.reduce([_n(e) for e in envs])
-
-    wait = max(1, int(min_gap * sr / 512))
-    frames = librosa.onset.onset_detect(onset_envelope=onset_env, sr=sr, wait=wait,
+        oe = np.maximum.reduce([_n(e) for e in envs])
+    w = max(1, int(min_gap*sr/512))
+    fr = librosa.onset.onset_detect(onset_envelope=oe, sr=sr, wait=w,
         pre_avg=3, post_avg=3, pre_max=3, post_max=5,
         delta=onset_delta, backtrack=backtrack, units='frames')
-    times = librosa.frames_to_time(frames, sr=sr)
-    print(f"  Raw onsets: {len(times)}")
-
-    threshold = 10 ** (energy_threshold_db / 20)
-    hits = []
+    times = librosa.frames_to_time(fr, sr=sr)
+    print(f"  Raw: {len(times)}")
+    thr = 10**(energy_threshold_db/20); hits = []
     for i, t in enumerate(times):
-        s = max(0, int((t - pre_pad) * sr))
+        s = max(0, int((t-pre_pad)*sr))
         e = min(int(times[i+1]*sr) if i+1<len(times) else len(y), s+int(max_dur*sr))
         seg = y[s:e]
-        if len(seg) < int(min_dur*sr): continue
+        if len(seg)<int(min_dur*sr): continue
         rms = np.sqrt(np.mean(seg**2))
-        if rms < threshold: continue
+        if rms<thr: continue
         fl = min(int(0.005*sr), len(seg)//4)
-        if fl > 0: seg = seg.copy(); seg[-fl:] *= np.linspace(1, 0, fl)
-        sc = float(librosa.feature.spectral_centroid(y=seg, sr=sr).mean())
-        hits.append(Hit(audio=seg, sr=sr, onset_time=t, duration=len(seg)/sr,
-                        index=len(hits), rms_energy=float(rms), spectral_centroid=sc))
-    print(f"  ✓ Valid hits: {len(hits)}")
-    return hits
+        if fl>0: seg=seg.copy(); seg[-fl:]*=np.linspace(1,0,fl)
+        sc = float(librosa.feature.spectral_centroid(y=seg,sr=sr).mean())
+        hits.append(Hit(audio=seg,sr=sr,onset_time=t,duration=len(seg)/sr,
+                        index=len(hits),rms_energy=float(rms),spectral_centroid=sc))
+    print(f"  ✓ {len(hits)} hits"); return hits
 
 
 # ─── Stage 3: Classification ─────────────────────────────────────────────────
@@ -163,20 +148,19 @@ LABEL_RULES = [
     ("mid",          lambda lr,mr,hr,c,zcr,d: c>800),
 ]
 
-def classify_hit(hit: Hit) -> str:
-    y, sr = hit.audio, hit.sr
+def classify_hit(hit):
+    y,sr = hit.audio, hit.sr
     D = np.abs(librosa.stft(y, n_fft=2048))
-    freqs = librosa.fft_frequencies(sr=sr, n_fft=2048)
-    le = np.sum(D[(freqs>=20)&(freqs<200)]**2)
-    me = np.sum(D[(freqs>=200)&(freqs<4000)]**2)
-    he = np.sum(D[(freqs>=4000)]**2)
-    total = le+me+he+1e-10; lr,mr,hr = le/total,me/total,he/total
+    f = librosa.fft_frequencies(sr=sr, n_fft=2048)
+    le=np.sum(D[(f>=20)&(f<200)]**2); me=np.sum(D[(f>=200)&(f<4000)]**2)
+    he=np.sum(D[(f>=4000)]**2); t=le+me+he+1e-10
+    lr,mr,hr = le/t,me/t,he/t
     zcr = float(librosa.feature.zero_crossing_rate(y=y).mean())
     for name, fn in LABEL_RULES:
         if fn(lr,mr,hr,hit.spectral_centroid,zcr,hit.duration): return name
     return "other"
 
-def classify_hits(hits: list) -> list:
+def classify_hits(hits):
     print(f"[Stage 3] Classifying {len(hits)} hits...")
     for h in hits: h.label = classify_hit(h)
     counts = defaultdict(int)
@@ -187,212 +171,167 @@ def classify_hits(hits: list) -> list:
 
 # ─── Stage 4: NCC-based clustering ───────────────────────────────────────────
 
-def ncc_max(a: np.ndarray, b: np.ndarray) -> float:
-    """NCC peak. Amplitude-invariant. Compares the shorter length only."""
-    # Use the shorter clip's length — no zero-padding inflation
-    n = min(len(a), len(b))
-    a, b = a[:n].copy(), b[:n].copy()
-    a -= a.mean(); b -= b.mean()
-    norm = np.sqrt(np.dot(a,a) * np.dot(b,b))
-    if norm < 1e-10: return 0.0
-    cc = fftconvolve(a, b[::-1], mode='full')
-    return float(np.max(np.abs(cc))) / norm
-
+def ncc_max(a, b):
+    n = min(len(a), len(b)); a,b = a[:n].copy(), b[:n].copy()
+    a-=a.mean(); b-=b.mean()
+    norm = np.sqrt(np.dot(a,a)*np.dot(b,b))
+    if norm<1e-10: return 0.0
+    return float(np.max(np.abs(fftconvolve(a,b[::-1],mode='full'))))/norm
 
-def build_ncc_distance_matrix(hits: list, max_compare_samples: int = 8820) -> np.ndarray:
-    """Cached NCC distance matrix. Auto-scales compare window to hit lengths."""
+def build_ncc_distance_matrix(hits, max_compare_samples=8820):
     key = ("ncc_dist", tuple(_audio_hash(h.audio) for h in hits), max_compare_samples)
-    cached = cache_get(key)
-    if cached is not None:
-        print(f"  Using cached NCC distance matrix"); return cached
-    N = len(hits)
-    D = np.zeros((N, N), dtype=np.float32)
+    c = cache_get(key)
+    if c is not None: print(f"  Cached NCC matrix"); return c
+    N=len(hits); D=np.zeros((N,N),dtype=np.float32)
     for i in range(N):
-        ai = hits[i].audio[:max_compare_samples]
-        for j in range(i+1, N):
-            bj = hits[j].audio[:max_compare_samples]
-            D[i,j] = D[j,i] = max(0.0, 1.0 - ncc_max(ai, bj))
+        ai=hits[i].audio[:max_compare_samples]
+        for j in range(i+1,N):
+            D[i,j]=D[j,i]=max(0.0, 1.0-ncc_max(ai,hits[j].audio[:max_compare_samples]))
     return cache_set(key, D)
 
-
 def _labels_to_clusters(labels, hits):
-    cluster_map = defaultdict(list)
-    for i, lab in enumerate(labels): cluster_map[lab].append(i)
+    cm = defaultdict(list)
+    for i,l in enumerate(labels): cm[l].append(i)
     clusters = []
-    for _, indices in sorted(cluster_map.items()):
-        votes = defaultdict(int)
-        for idx in indices: votes[hits[idx].label] += 1
-        majority = max(votes, key=votes.get)
-        existing = sum(1 for c in clusters if c.label.rsplit('_',1)[0] == majority)
-        clusters.append(Cluster(cluster_id=len(clusters), label=f"{majority}_{existing}",
-                                 hits=[hits[i] for i in indices]))
+    for _, idx in sorted(cm.items()):
+        v = defaultdict(int)
+        for i in idx: v[hits[i].label]+=1
+        maj = max(v, key=v.get)
+        ex = sum(1 for c in clusters if c.label.rsplit('_',1)[0]==maj)
+        clusters.append(Cluster(cluster_id=len(clusters), label=f"{maj}_{ex}",
+                                 hits=[hits[i] for i in idx]))
     clusters.sort(key=lambda c: c.count, reverse=True)
-    for i, c in enumerate(clusters): c.cluster_id = i
+    for i,c in enumerate(clusters): c.cluster_id=i
     return clusters
 
-
-def cluster_hits(hits: list, ncc_threshold: float = 0.80,
-                 max_compare_ms: float = 0,
-                 target_min: int = 0, target_max: int = 0,
-                 linkage: str = 'average') -> list:
-    """NCC clustering with target range support.
-
-    max_compare_ms: 0 = auto (use median hit length). Otherwise milliseconds.
-    target_min/max: if both > 0, find a cluster count in this range.
-    """
+def cluster_hits(hits, ncc_threshold=0.80, max_compare_ms=0,
+                 target_min=0, target_max=0, linkage='average'):
     from sklearn.cluster import AgglomerativeClustering
-
     if not hits: return []
-    N = len(hits); sr = hits[0].sr
-    if N == 1: return [Cluster(cluster_id=0, label=f"{hits[0].label}_0", hits=[hits[0]])]
-
-    # Auto-scale compare window to median hit length
-    if max_compare_ms <= 0:
-        median_len = int(np.median([len(h.audio) for h in hits]))
-        max_samples = max(int(0.03 * sr), median_len)  # at least 30ms
-    else:
-        max_samples = int(max_compare_ms / 1000.0 * sr)
-
-    print(f"[Stage 4] NCC clustering ({N} hits, compare={max_samples/sr*1000:.0f}ms, linkage={linkage})...")
-    print(f"  Computing {N*(N-1)//2} pairwise NCC distances...")
-    D = build_ncc_distance_matrix(hits, max_compare_samples=max_samples)
-
-    use_target = target_min > 0 and target_max > 0 and target_max >= target_min
-    target_min = max(1, min(target_min, N))
-    target_max = max(target_min, min(target_max, N))
-
-    if use_target:
-        print(f"  Target: {target_min}–{target_max} clusters")
-
-        # Strategy 1: Binary search on distance threshold
-        lo, hi = 0.001, 1.0
-        best_labels, best_n, best_dist = None, -1, 0.5
+    N=len(hits); sr=hits[0].sr
+    if N==1: return [Cluster(cluster_id=0, label=f"{hits[0].label}_0", hits=[hits[0]])]
+    if max_compare_ms<=0:
+        ms = max(int(0.03*sr), int(np.median([len(h.audio) for h in hits])))
+    else: ms = int(max_compare_ms/1000.0*sr)
+    print(f"[Stage 4] NCC clustering ({N} hits, {ms/sr*1000:.0f}ms, {linkage})...")
+    print(f"  Computing {N*(N-1)//2} pairwise distances...")
+    D = build_ncc_distance_matrix(hits, max_compare_samples=ms)
+    use_t = target_min>0 and target_max>0 and target_max>=target_min
+    tmin=max(1,min(target_min or 1,N)); tmax=max(tmin,min(target_max or N,N))
+    if use_t:
+        print(f"  Target: {tmin}–{tmax}")
+        lo,hi=0.001,1.0; bl,bn,bd=None,-1,0.5
         for _ in range(30):
-            mid = (lo + hi) / 2
-            agg = AgglomerativeClustering(n_clusters=None, distance_threshold=max(0.001, mid),
-                                           metric='precomputed', linkage=linkage)
-            labels = agg.fit_predict(D)
-            n = len(set(labels))
-            if target_min <= n <= target_max:
-                best_labels, best_n, best_dist = labels, n, mid; break
-            elif n > target_max: lo = mid
-            else: hi = mid
-            if best_labels is None or abs(n-(target_min+target_max)/2) < abs(best_n-(target_min+target_max)/2):
-                best_labels, best_n, best_dist = labels, n, mid
-
-        # Strategy 2: If binary search didn't land in range, use n_clusters directly
-        if best_n < target_min or best_n > target_max:
-            target_mid = (target_min + target_max) // 2
-            target_mid = min(target_mid, N - 1)
-            print(f"  Binary search got {best_n}, falling back to n_clusters={target_mid}")
+            mid=(lo+hi)/2
+            agg=AgglomerativeClustering(n_clusters=None,distance_threshold=max(0.001,mid),
+                                         metric='precomputed',linkage=linkage)
+            lb=agg.fit_predict(D); n=len(set(lb))
+            if tmin<=n<=tmax: bl,bn,bd=lb,n,mid; break
+            elif n>tmax: lo=mid
+            else: hi=mid
+            if bl is None or abs(n-(tmin+tmax)/2)<abs(bn-(tmin+tmax)/2): bl,bn,bd=lb,n,mid
+        if bn<tmin or bn>tmax:
+            tm=min((tmin+tmax)//2, N-1)
+            print(f"  Fallback n_clusters={tm}")
             try:
-                agg = AgglomerativeClustering(n_clusters=target_mid, metric='precomputed', linkage=linkage)
-                best_labels = agg.fit_predict(D)
-                best_n = target_mid
-            except Exception as e:
-                print(f"  n_clusters fallback failed: {e}")
-
-        labels = best_labels
-        print(f"  → {best_n} clusters (dist_threshold={best_dist:.4f})")
+                agg=AgglomerativeClustering(n_clusters=tm,metric='precomputed',linkage=linkage)
+                bl=agg.fit_predict(D); bn=tm
+            except: pass
+        labels=bl; print(f"  → {bn} clusters")
     else:
-        dist_threshold = max(0.001, 1.0 - ncc_threshold)
-        print(f"  Fixed: NCC≥{ncc_threshold} (dist≤{dist_threshold:.3f})")
-        agg = AgglomerativeClustering(n_clusters=None, distance_threshold=dist_threshold,
-                                       metric='precomputed', linkage=linkage)
-        labels = agg.fit_predict(D)
-
+        dt=max(0.001, 1.0-ncc_threshold); print(f"  Fixed: dist≤{dt:.3f}")
+        labels=AgglomerativeClustering(n_clusters=None,distance_threshold=dt,
+                                        metric='precomputed',linkage=linkage).fit_predict(D)
     print(f"  ✓ {len(set(labels))} clusters")
-    clusters = _labels_to_clusters(labels, hits)
-    for c in clusters: print(f"    {c.label}: {c.count} hits")
-    return clusters
+    cl = _labels_to_clusters(labels, hits)
+    for c in cl: print(f"    {c.label}: {c.count} hits")
+    return cl
 
 
 # ─── Stage 5: Quality scoring ────────────────────────────────────────────────
 
 def sample_quality_score(y, sr, label="other"):
     import scipy.stats
-    rms_env = librosa.feature.rms(y=y, frame_length=512, hop_length=128)[0]
-    if len(rms_env) >= 10:
-        pk = np.argmax(rms_env); post = rms_env[pk:]
-        tail_r = np.mean(post[-max(3,len(post)//5):])/(rms_env[pk]+1e-8)
-        c1 = max(0, 1.0-tail_r*5)
+    rms_env=librosa.feature.rms(y=y,frame_length=512,hop_length=128)[0]
+    if len(rms_env)>=10:
+        pk=np.argmax(rms_env); post=rms_env[pk:]
+        c1=max(0,1.0-np.mean(post[-max(3,len(post)//5):])/( rms_env[pk]+1e-8)*5)
         if len(post)>=5:
-            slope,_,r,_,_ = scipy.stats.linregress(np.arange(len(post)), np.log(post+1e-8))
-            c2 = max(0,r**2) if slope<0 else r**2*0.3
+            sl,_,r,_,_=scipy.stats.linregress(np.arange(len(post)),np.log(post+1e-8))
+            c2=max(0,r**2) if sl<0 else r**2*0.3
         else: c2=0.0
-    else: c1,c2 = 0.5,0.0
-    completeness = c1*0.6+c2*0.4
-    snr = 10*np.log10(np.percentile(y**2,99)/(np.percentile(y**2,10)+1e-12))
-    n_snr = np.clip((snr-10)/40,0,1)
-    onsets = librosa.onset.onset_detect(y=y, sr=sr, units='samples', backtrack=True)
-    if len(onsets)>0:
-        os_s=int(onsets[0]); pre=y[max(0,os_s-int(sr*.02)):os_s]; sig=y[os_s:os_s+int(sr*.1)]
-        n_pre = np.clip((-10*np.log10(np.mean(pre**2+1e-12)/np.mean(sig**2+1e-12))-5)/30,0,1) \
-                if len(pre)>10 and len(sig)>10 else 0.5
-    else: n_pre=0.5
-    cleanness = n_snr*0.5+n_pre*0.5
-    oe = librosa.onset.onset_strength(y=y, sr=sr)
-    sharpness = float(np.max(oe)/(np.mean(oe)+1e-8)) if len(oe)>1 else 1.0
-    onset_q = float(np.clip((sharpness-1.0)/5.0,0,1))
-    total = (completeness*0.30+cleanness*0.40+onset_q*0.20+0.5*0.10)*100
-    return {'total':float(total),'completeness':float(completeness),
-            'cleanness':float(cleanness),'onset_quality':float(onset_q)}
+    else: c1,c2=0.5,0.0
+    comp=c1*0.6+c2*0.4
+    snr=10*np.log10(np.percentile(y**2,99)/(np.percentile(y**2,10)+1e-12))
+    ns=np.clip((snr-10)/40,0,1)
+    ons=librosa.onset.onset_detect(y=y,sr=sr,units='samples',backtrack=True)
+    if len(ons)>0:
+        o=int(ons[0]); pre=y[max(0,o-int(sr*.02)):o]; sig=y[o:o+int(sr*.1)]
+        np2=np.clip((-10*np.log10(np.mean(pre**2+1e-12)/np.mean(sig**2+1e-12))-5)/30,0,1) \
+            if len(pre)>10 and len(sig)>10 else 0.5
+    else: np2=0.5
+    clean=ns*0.5+np2*0.5
+    oe=librosa.onset.onset_strength(y=y,sr=sr)
+    sh=float(np.max(oe)/(np.mean(oe)+1e-8)) if len(oe)>1 else 1.0
+    oq=float(np.clip((sh-1.0)/5.0,0,1))
+    tot=(comp*0.30+clean*0.40+oq*0.20+0.5*0.10)*100
+    return {'total':float(tot),'completeness':float(comp),'cleanness':float(clean),'onset_quality':float(oq)}
 
 def select_best(clusters):
-    print(f"[Stage 5] Selecting best representatives...")
+    print(f"[Stage 5] Selecting best...")
     for c in clusters:
         if c.count<=1: c.best_hit_idx=0; continue
-        scores = [sample_quality_score(h.audio,h.sr,c.label.rsplit('_',1)[0])['total'] for h in c.hits]
-        c.best_hit_idx = int(np.argmax(scores))
+        sc=[sample_quality_score(h.audio,h.sr,c.label.rsplit('_',1)[0])['total'] for h in c.hits]
+        c.best_hit_idx=int(np.argmax(sc))
 
 
 # ─── Stage 6: Synthesis ──────────────────────────────────────────────────────
 
 def synthesize_from_cluster(cluster):
     if cluster.count<2: return None
-    tl = int(np.median([len(h.audio) for h in cluster.hits]))
-    aligned, weights = [], []
-    pp_target = None
-    for i, h in enumerate(cluster.hits):
-        a = h.audio.copy(); pp = np.argmax(np.abs(a))
-        if pp_target is None: pp_target = pp
-        shift = pp_target-pp
-        if shift>0: a=np.pad(a,(shift,0))
-        elif shift<0: a=a[-shift:]
-        a = a[:tl] if len(a)>=tl else np.pad(a,(0,tl-len(a)))
-        pk = np.abs(a).max()
+    tl=int(np.median([len(h.audio) for h in cluster.hits]))
+    al,wt=[],[]
+    pp=None
+    for i,h in enumerate(cluster.hits):
+        a=h.audio.copy(); p=np.argmax(np.abs(a))
+        if pp is None: pp=p
+        s=pp-p
+        if s>0: a=np.pad(a,(s,0))
+        elif s<0: a=a[-s:]
+        a=a[:tl] if len(a)>=tl else np.pad(a,(0,tl-len(a)))
+        pk=np.abs(a).max()
         if pk>0: a=a/pk
-        aligned.append(a); weights.append(2.0 if i==cluster.best_hit_idx else 1.0)
-    aligned=np.array(aligned); w=np.array(weights); w/=w.sum()
-    synth=np.average(aligned,axis=0,weights=w); pk=np.abs(synth).max()
-    return (synth*0.95/pk).astype(np.float32) if pk>0 else synth.astype(np.float32)
+        al.append(a); wt.append(2.0 if i==cluster.best_hit_idx else 1.0)
+    al=np.array(al); w=np.array(wt); w/=w.sum()
+    sy=np.average(al,axis=0,weights=w); pk=np.abs(sy).max()
+    return (sy*0.95/pk).astype(np.float32) if pk>0 else sy.astype(np.float32)
 
 
 # ─── Stage 7: MIDI + rendering ───────────────────────────────────────────────
 
 def build_midi(clusters, bpm=120.0):
     import pretty_midi
-    pm = pretty_midi.PrettyMIDI(initial_tempo=bpm)
+    pm=pretty_midi.PrettyMIDI(initial_tempo=bpm)
     for i,c in enumerate(clusters): c.midi_note=min(36+i,127)
-    inst = pretty_midi.Instrument(program=0, is_drum=True, name='Extracted Samples')
+    inst=pretty_midi.Instrument(program=0,is_drum=True,name='Extracted Samples')
     pm.instruments.append(inst)
     for c in clusters:
         for h in c.hits:
-            vel=max(1,min(127,int(h.rms_energy/0.3*127)))
-            inst.notes.append(pretty_midi.Note(velocity=vel,pitch=c.midi_note,
+            v=max(1,min(127,int(h.rms_energy/0.3*127)))
+            inst.notes.append(pretty_midi.Note(velocity=v,pitch=c.midi_note,
                 start=h.onset_time,end=h.onset_time+max(h.duration,0.05)))
     inst.notes.sort(key=lambda n: n.start); return pm
 
-def export_midi(clusters, output_path, bpm=120.0):
-    pm=build_midi(clusters,bpm); pm.write(output_path)
-    print(f"  ✓ MIDI: {output_path} ({len(pm.instruments[0].notes)} notes)"); return pm
+def export_midi(clusters, path, bpm=120.0):
+    pm=build_midi(clusters,bpm); pm.write(path)
+    print(f"  ✓ MIDI: {path} ({len(pm.instruments[0].notes)} notes)"); return pm
 
 def detect_bpm(y, sr):
-    ck=("bpm",_audio_hash(y),sr); cached=cache_get(ck)
-    if cached is not None: print(f"  Cached BPM: {cached}"); return cached
-    onset_env=librosa.onset.onset_strength(y=y,sr=sr,aggregate=np.median)
-    bpm=float(librosa.feature.tempo(onset_envelope=onset_env,sr=sr).item())
-    _,beats=librosa.beat.beat_track(onset_envelope=onset_env,sr=sr,units='time')
+    ck=("bpm",_audio_hash(y),sr); c=cache_get(ck)
+    if c is not None: return c
+    oe=librosa.onset.onset_strength(y=y,sr=sr,aggregate=np.median)
+    bpm=float(librosa.feature.tempo(onset_envelope=oe,sr=sr).item())
+    _,beats=librosa.beat.beat_track(onset_envelope=oe,sr=sr,units='time')
     if len(beats)>2:
         ibi=60.0/float(np.median(np.diff(beats)))
         for c in [bpm,ibi]:
@@ -403,16 +342,16 @@ def detect_bpm(y, sr):
     return cache_set(ck, round(bpm,1))
 
 def render_midi_with_samples(clusters, sr=44100):
-    max_end=max((h.onset_time+h.duration for c in clusters for h in c.hits),default=1.0)
-    buf=np.zeros(int((max_end+1.0)*sr),dtype=np.float64)
+    me=max((h.onset_time+h.duration for c in clusters for h in c.hits),default=1.0)
+    buf=np.zeros(int((me+1.0)*sr),dtype=np.float64)
     for c in clusters:
-        sample=c.best_hit.audio.astype(np.float64)
-        ref_e=c.best_hit.rms_energy if c.best_hit.rms_energy>0 else 0.1
+        s=c.best_hit.audio.astype(np.float64)
+        re=c.best_hit.rms_energy if c.best_hit.rms_energy>0 else 0.1
         for h in c.hits:
-            vs=min(2.0,h.rms_energy/(ref_e+1e-8))**0.5
-            s=int(h.onset_time*sr); e=s+len(sample)
+            vs=min(2.0,h.rms_energy/(re+1e-8))**0.5
+            i=int(h.onset_time*sr); e=i+len(s)
             if e>len(buf): buf=np.concatenate([buf,np.zeros(e-len(buf))])
-            buf[s:e]+=sample*vs
+            buf[i:e]+=s*vs
     pk=np.abs(buf).max()
     return (buf/pk*0.9).astype(np.float32) if pk>1e-8 else buf.astype(np.float32)
 
@@ -422,31 +361,180 @@ def build_sample_map(clusters):
 
 def build_archive(clusters, bpm, sr, midi_path=None, rendered_audio=None):
     import zipfile, tempfile, io
-    zip_path=tempfile.mktemp(suffix='.zip')
-    index={'bpm':round(bpm,1),'sample_rate':sr,'total_clusters':len(clusters),
-           'total_hits':sum(c.count for c in clusters),'samples':{}}
-    with zipfile.ZipFile(zip_path,'w',compression=zipfile.ZIP_STORED) as zf:
+    zp=tempfile.mktemp(suffix='.zip')
+    idx={'bpm':round(bpm,1),'sample_rate':sr,'total_clusters':len(clusters),
+         'total_hits':sum(c.count for c in clusters),'samples':{}}
+    with zipfile.ZipFile(zp,'w',compression=zipfile.ZIP_STORED) as zf:
         for c in clusters:
-            best=c.best_hit; fname=f"samples/{c.label}.wav"
-            buf=io.BytesIO(); sf.write(buf,best.audio,sr,format='WAV',subtype='PCM_24')
-            zf.writestr(fname,buf.getvalue())
-            onset_times=sorted([h.onset_time for h in c.hits])
-            index['samples'][c.label]={
-                'file':fname,'classification':c.label.rsplit('_',1)[0],
+            b=c.best_hit; fn=f"samples/{c.label}.wav"
+            buf=io.BytesIO(); sf.write(buf,b.audio,sr,format='WAV',subtype='PCM_24')
+            zf.writestr(fn,buf.getvalue())
+            ot=sorted([h.onset_time for h in c.hits])
+            idx['samples'][c.label]={
+                'file':fn,'classification':c.label.rsplit('_',1)[0],
                 'midi_note':c.midi_note,'occurrences':c.count,
-                'onset_times_sec':[round(t,4) for t in onset_times],
-                'duration_sec':round(best.duration,4),
-                'rms_energy':round(best.rms_energy,6),
-                'spectral_centroid_hz':round(best.spectral_centroid,1),
-            }
+                'onset_times_sec':[round(t,4) for t in ot],
+                'duration_sec':round(b.duration,4),
+                'rms_energy':round(b.rms_energy,6),
+                'spectral_centroid_hz':round(b.spectral_centroid,1)}
             if c.synthesized is not None:
                 sf2=f"samples/{c.label}__synthesized.wav"; b2=io.BytesIO()
                 sf.write(b2,c.synthesized,sr,format='WAV',subtype='PCM_24')
-                zf.writestr(sf2,b2.getvalue())
-                index['samples'][c.label]['synthesized_file']=sf2
-        zf.writestr('index.json',json.dumps(index,indent=2))
+                zf.writestr(sf2,b2.getvalue()); idx['samples'][c.label]['synthesized_file']=sf2
+        zf.writestr('index.json',json.dumps(idx,indent=2))
         if midi_path and os.path.exists(midi_path): zf.write(midi_path,'reconstruction.mid')
         if rendered_audio is not None:
             rb=io.BytesIO(); sf.write(rb,rendered_audio,sr,format='WAV',subtype='PCM_16')
             zf.writestr('rendered_reconstruction.wav',rb.getvalue())
-    return zip_path
+    return zp
+
+
+# ─── Auto-tuner ──────────────────────────────────────────────────────────────
+
+def _spectral_envelope_corr(original, rendered, sr, n_fft=4096, hop=2048):
+    """Spectral envelope correlation between two signals. Phase-insensitive.
+    Returns correlation coefficient [−1, 1]. Higher = better reconstruction."""
+    n = min(len(original), len(rendered))
+    if n < n_fft: return 0.0
+    S_orig = np.abs(librosa.stft(original[:n], n_fft=n_fft, hop_length=hop))
+    S_rend = np.abs(librosa.stft(rendered[:n], n_fft=n_fft, hop_length=hop))
+    # Average over time to get spectral envelope
+    env_o = S_orig.mean(axis=1)
+    env_r = S_rend.mean(axis=1)
+    if env_o.std() < 1e-10 or env_r.std() < 1e-10: return 0.0
+    return float(np.corrcoef(env_o, env_r)[0, 1])
+
+
+def _rms_envelope_corr(original, rendered, sr, hop=1024):
+    """RMS amplitude envelope correlation. Measures timing/dynamics match."""
+    n = min(len(original), len(rendered))
+    if n < hop * 4: return 0.0
+    rms_o = librosa.feature.rms(y=original[:n], hop_length=hop)[0]
+    rms_r = librosa.feature.rms(y=rendered[:n], hop_length=hop)[0]
+    n2 = min(len(rms_o), len(rms_r))
+    if n2 < 4: return 0.0
+    rms_o, rms_r = rms_o[:n2], rms_r[:n2]
+    if rms_o.std() < 1e-10 or rms_r.std() < 1e-10: return 0.0
+    return float(np.corrcoef(rms_o, rms_r)[0, 1])
+
+
+def _reconstruction_score(original, rendered, sr):
+    """Combined score [0, 100] measuring how well the reconstruction matches."""
+    spec_corr = _spectral_envelope_corr(original, rendered, sr)
+    rms_corr = _rms_envelope_corr(original, rendered, sr)
+    # Penalize if reconstruction is much shorter/longer
+    len_ratio = min(len(rendered), len(original)) / (max(len(rendered), len(original)) + 1)
+    score = (spec_corr * 0.5 + rms_corr * 0.4 + len_ratio * 0.1) * 100
+    return max(0.0, score)
+
+
+def auto_tune(stem_audio, sr, mode="auto", log_fn=None):
+    """Automatically find the best extraction parameters for this audio.
+
+    Sweeps onset detection params and cluster counts. Uses the cached NCC matrix
+    so re-clustering is near-instant after the first onset detection.
+
+    Returns: (best_params: dict, best_score: float, log: list[str])
+
+    The returned params can be passed directly to the extraction pipeline.
+    """
+    log = []
+    def _log(msg):
+        log.append(msg)
+        if log_fn: log_fn(msg)
+        print(msg)
+
+    _log(f"[Auto-tune] Starting parameter search on {len(stem_audio)/sr:.1f}s audio...")
+
+    # Parameter grid — coarse sweep first
+    onset_configs = [
+        {"onset_delta": 0.08, "energy_threshold_db": -40, "min_gap": 0.02},
+        {"onset_delta": 0.10, "energy_threshold_db": -35, "min_gap": 0.025},
+        {"onset_delta": 0.12, "energy_threshold_db": -35, "min_gap": 0.03},
+        {"onset_delta": 0.15, "energy_threshold_db": -30, "min_gap": 0.04},
+        {"onset_delta": 0.20, "energy_threshold_db": -28, "min_gap": 0.05},
+        {"onset_delta": 0.25, "energy_threshold_db": -25, "min_gap": 0.06},
+    ]
+
+    cluster_targets = [3, 5, 8, 10, 15, 20, 30]
+
+    best_score = -1
+    best_params = {}
+    best_clusters = None
+    results = []
+
+    for oc_idx, oc in enumerate(onset_configs):
+        _log(f"\n  Config {oc_idx+1}/{len(onset_configs)}: delta={oc['onset_delta']}, "
+             f"energy={oc['energy_threshold_db']}dB, gap={oc['min_gap']}s")
+
+        hits = detect_onsets(stem_audio, sr, mode=mode, **oc)
+        if len(hits) < 2:
+            _log(f"    → Only {len(hits)} hits, skipping")
+            continue
+
+        hits = classify_hits(hits)
+
+        # NCC matrix computed once per onset config (cached within)
+        for n_target in cluster_targets:
+            if n_target >= len(hits): continue
+
+            clusters = cluster_hits(hits, target_min=n_target, target_max=n_target,
+                                     linkage='average')
+            if not clusters: continue
+
+            # Quick select best + render
+            for c in clusters:
+                if c.count <= 1: c.best_hit_idx = 0
+                else:
+                    energies = [h.rms_energy for h in c.hits]
+                    c.best_hit_idx = int(np.argmax(energies))  # fast: pick loudest
+
+            rendered = render_midi_with_samples(clusters, sr=sr)
+            score = _reconstruction_score(stem_audio, rendered, sr)
+
+            results.append({**oc, 'n_clusters': len(clusters),
+                            'target': n_target, 'n_hits': len(hits), 'score': score})
+
+            if score > best_score:
+                best_score = score
+                best_params = {**oc, 'n_clusters': len(clusters), 'target_min': n_target,
+                               'target_max': n_target}
+                best_clusters = clusters
+                _log(f"    ★ target={n_target} → {len(clusters)} clusters, "
+                     f"score={score:.1f} (NEW BEST)")
+            else:
+                _log(f"    target={n_target} → {len(clusters)} clusters, score={score:.1f}")
+
+    # Fine-tune: try ±1 around best target with best onset config
+    if best_params:
+        bt = best_params.get('target_min', 10)
+        _log(f"\n  Fine-tuning around best (delta={best_params['onset_delta']}, "
+             f"target≈{bt})...")
+
+        fine_oc = {k: best_params[k] for k in ['onset_delta', 'energy_threshold_db', 'min_gap']}
+        hits = detect_onsets(stem_audio, sr, mode=mode, **fine_oc)
+        if len(hits) >= 2:
+            hits = classify_hits(hits)
+            for ft in range(max(2, bt-3), bt+4):
+                if ft >= len(hits): continue
+                clusters = cluster_hits(hits, target_min=ft, target_max=ft, linkage='average')
+                if not clusters: continue
+                for c in clusters:
+                    if c.count <= 1: c.best_hit_idx = 0
+                    else: c.best_hit_idx = int(np.argmax([h.rms_energy for h in c.hits]))
+                rendered = render_midi_with_samples(clusters, sr=sr)
+                score = _reconstruction_score(stem_audio, rendered, sr)
+                if score > best_score:
+                    best_score = score
+                    best_params = {**fine_oc, 'n_clusters': len(clusters),
+                                   'target_min': ft, 'target_max': ft}
+                    best_clusters = clusters
+                    _log(f"    ★ target={ft} → {len(clusters)} clusters, "
+                         f"score={score:.1f} (NEW BEST)")
+
+    _log(f"\n[Auto-tune] Best: score={best_score:.1f}, "
+         f"delta={best_params.get('onset_delta')}, "
+         f"energy={best_params.get('energy_threshold_db')}dB, "
+         f"clusters={best_params.get('n_clusters')}")
+
+    return best_params, best_score, log